Troubleshooting

Export failures, missing FFmpeg, capture permissions, provider errors, and agent limits.

Export refuses to start

OpenScene checks FFmpeg before rendering and reports the problem instead of failing halfway. Confirm the binary is discoverable through an absolute directory on PATH, or name it explicitly — relative paths are rejected:

VIDEO_TOOL_FFMPEG_PATH=/absolute/path/to/ffmpeg npm run dev

Settings → Local Tools reports local runtime readiness, so check there first.

The export does not match the Program Monitor

The monitor is a best-effort review surface; the FFmpeg output is authoritative. Frame-perfect multitrack mastering is not a guarantee this build makes — see Exporting.

Window capture records nothing on macOS

macOS requires Screen Recording permission for the terminal running OpenScene. Grant it in System Settings and restart the app. Full-screen capture, and microphone or system-audio mix in the recorder, are not available yet.

No models in the picker

Only connected providers show models. Connect one in Settings → Providers, then use Settings → Models to choose which of its models appear. With nothing connected, run a local Ollama model instead — see Install and run.

The agent cannot see my footage

watchProjectVideo hands sampled frames to the model as images, which requires a vision-capable model. A text-only local model can still edit the timeline but cannot answer questions about what is on screen.

A generation provider is listed but unavailable

Providers without a real adapter stay visible and honestly unavailable rather than pretending to work. Speech runs on ElevenLabs or OpenAI; video on Google Veo or OpenAI Sora. Sora reference images are not supported in this build.

The agent stopped and is waiting

That is the approval gate, not a hang. Anything that writes to your project or starts a job asks first — see The Edit Agent.

Still stuck

Reproduce from a clean build with npm run typecheck, npm test, and npm run build, then open an issue at github.com/Theorvane/openscene/issues with your platform, Node version, and FFmpeg version.