Troubleshooting

When something does not work

Kionjo says what is wrong in the status bar, the Shoot tab's check lines, the Cut tab's warnings and log, and the tooltips of disabled buttons. Read those first. This page explains the common ones.

ffmpeg not found

The status bar says "ffmpeg not found: click to set its path", and the Cut tab's build buttons are disabled.

Install ffmpeg from ffmpeg.org. On Windows, use the gyan.dev "full" build: it has every filter Kionjo uses.
Either put its bin folder on PATH and restart Unity, or open Preferences > Kionjo and set ffmpeg to the file or its folder.
The line under the field shows what Kionjo found, for example "ffmpeg 7.1 at C:\...".

Good to knowKionjo checks the Preferences path first, then PATH. It looks for ffprobe next to ffmpeg, then on PATH. "ffmpeg at ... did not answer -version" means the file exists but did not run: point to a working ffmpeg.

Black or empty render, or a camera that does not move

"No camera: add a Kionjo Camera Source or tag a camera MainCamera." Kionjo renders through the Kionjo Camera Source's camera, else the camera tagged MainCamera. Add one of them.
"The take has no "Head" track: the camera will not move." Name the head camera's track Head in the Kionjo Recorder, then record again.
"Not found in the scene: ..." in the render log. A hide or show path no longer matches the scene. Fix the path in the shot's Staging section.
"An XR device is active". The headset is still connected. Stop Link before a replay or a render.
The render stopped. Leaving Play mode cancels a running render. Kionjo renders only in Play mode.
Running Unity with -nographics. That gives Unity no graphics device, so nothing can be rendered. Never pass it for renders.
An image card shows black. Its image file was not found: the Cut tab's warnings say "card image not found, shown as black".

Render selected take is disabled

Hover the button: its tooltip gives the reason.

"Enter Play mode to render."
"Record a take first." A Performance shot needs a take.
"This shot uses a device capture or is organise only." Only Offline Render shots are rendered.
"A job is running." Wait, or press Cancel in the status bar.
The same "No camera" reason as above.

Record does nothing

Space does nothing. It works only while the Kionjo window has focus, the Shoot tab is open and you are not typing in a field. Wearing the headset often takes focus away from the editor: click the Record button with the mouse instead.
"Enter Play mode to record." Takes are recorded in Play mode.
"Add a Kionjo Recorder to your rig." Use Add Component > SeedeXR > Kionjo Recorder, or the Shoot tab's Add a Kionjo Recorder button.
"The Kionjo Recorder has no tracks." Add the head camera and the hands as tracks.
"Cards are not recorded." Select a shot, not a card.
Your game's ToggleTake() logs "no take is pending". Select a shot in the Shoot tab first.
The take stopped by itself. It reached the recorder's Max Take Seconds (120 by default). The take marks the event cap.

The shot is Not ready

Each x line is an error. Fix them and press Stage or Check again.

"Hide: /Path not found" or "Show: /Path not found": the object was renamed or moved. Drop it on the drop zone again and remove the old path.
"Hide: /Path is still active" or "Show: /Path is inactive": something in your scene changed it back. Check your stage handlers.
"No camera source": add a Kionjo Camera Source or tag a camera MainCamera.
"No Kionjo Recorder with tracks in the scene": add one. For a Live Camera render this is only a warning.

"Hide list is empty" is information, not an error: it reminds you that everything in the scene will be visible.

Subtitle and card fonts

Kionjo always copies a real font file into the cut folder and points ffmpeg at it. It never asks the system for a font by name, because that lookup crashes ffmpeg on Windows.

"No font for text cards: set Title Font in the storyboard's subtitle style." Kionjo found neither your font nor a default (Arial on Windows and macOS, DejaVu Sans on Linux). Set Title Font Path in the storyboard's Subtitles settings to a TTF or OTF file.
Subtitles show in the wrong font. Set Font Path to the file, and Font Name to the family name inside that file. The name must match.
Subtitle colour looks wrong. Colour is an ASS colour in the order &HAABBGGRR: blue comes before red.

Words trim does not work

Words trim needs Python with the faster-whisper package. When it cannot run, Kionjo falls back to Silence trim and logs the reason in the Console, for example "word trim of line.wav fell back to silence: Python not found".

Install Python and faster-whisper.
In Preferences > Kionjo, set Python to that Python, if it is not the one called python on PATH.
Build the draft again.

Good to knowEach line is transcribed once. The word timings are cached in Library/KionjoCache/words until the audio file changes. At a line's own start and end, Kionjo uses the silence edge, because whisper tends to end words early.

A shot or a sound is missing from the draft

The Cut tab's Warnings list names what was left out and why:

"S03: no source, skipped (render the take or import a capture)."
"S03: organise only, left out of the cut."
"S03: still has no thumbnail, shown as a title card."
"S03: voice line.wav not found, skipped" or "has no length, skipped".
"S03: SFX event "seal" not in the take, skipped" or "is outside the shot's range, skipped". Check the take you picked with Use, and the shot's In Point and Out Point.
"Music track.mp3: file not found, skipped."

"Nothing to cut yet" means no shot has a source and there are no cards: render a shot, import a capture or add a card. Build a draft only when renders have finished: the cut picks its sources when you press the button.

Good to knowWhen an ffmpeg step fails, the job stops, keeps the folder, and the Log shows the end of ffmpeg's output. cut.log has all of it, and commands.txt lets you re-run each step by hand.

Driving Kionjo headless

WaitForEndOfFrame never fires in batchmode. Kionjo does not rely on it: it renders each frame on demand, late in the frame, through a URP render request or Camera.Render. That is why renders also work headless.

If you write your own capture around Kionjo, for example an IKionjoFrameSink or a test, do not wait for end of frame either. And never pass -nographics: without a graphics device there is nothing to render.

The kionjo commands are missing or answer from the wrong project

The commands exist only when com.unity.pipeline 0.9 or newer is installed in the project. Without it they are not compiled. Everything else still works.
Always pass --project-path "<your project>". With two editors open, the CLI may otherwise answer from the other one.
stage, record and render need Play mode.

See drive Kionjo from an agent or a script.

Still stuck?

Open an issue on GitHub with the Cut tab's log or cut.log, or reach the team through seedexr.com.