Troubleshooting
Esta página aún no está traducida; aquí tienes la versión en inglés.
Each entry names the symptom, the likely cause and the fix. If you see a message code such as llm-all-failed or qc.loudness, look it up in Messages and error codes.
Messages in the app
Section titled “Messages in the app”When a run stops, the project moves to Needs you with a plain message and what to do. Try again re-runs only the step that failed; finished steps are kept, and a project made on autopilot goes on on autopilot.
| Message | What to do |
|---|---|
| The voice kept leaving out a sentence in scene N: “…” | Reword or split that sentence in the script, then Try again. Tips: Voices |
| The voice could not read scene N, even in two halves: “…” | Same: shorter sentences, simpler wording, a rare word reworded |
| The free voice isn’t downloaded on this computer yet | Download the free voice (about 330 MB; progress in Settings › Advanced › Downloads), then Try again |
| There’s no OpenAI key in Reelfold, so this step couldn’t run | Use the free voice (Apple silicon), or add the key in Settings › AI |
| The visuals need an AI model — Claude Code didn’t answer | Try again (it gets more time), or choose another model in Settings › AI. See AI providers |
| Scene N of M couldn’t be redrawn: … Your video is unchanged | Nothing is lost. Try again redraws only the missing scenes, or Redraw scene N later |
| The script wasn’t written in scenes yet — it was still your notes | Try again: the scenes are drafted from your notes |
| Reelfold couldn’t render this — this is a bug in the app, not a problem with your files | Press Report this problem. It shows the report (no file names, transcripts or keys) and opens it on GitHub for you to post |
| “…” couldn’t be read | The file is damaged or not a video Reelfold can open. Check it still plays, then Try again |
| “…” is on the drive “…”, which isn’t connected | Connect the drive, then Try again |
| Node.js didn’t run / ffmpeg didn’t run | The message names the fix, for example brew reinstall node, or reinstall Reelfold |
A redo of a finished video that stops (new visuals, new vertical versions) never breaks the clip: it stays Ready to post with its old video, and the notice says what stopped.
Setup and engine
Section titled “Setup and engine”ffmpeg not found
Section titled “ffmpeg not found”The engine looks for ffmpeg and ffprobe on your PATH, then falls back to the static-ffmpeg package.
- Install it:
brew install ffmpeg. - Or point at specific binaries:
VSTUDIO_FFMPEG=/path/to/ffmpegandVSTUDIO_FFPROBE=/path/to/ffprobe.
The hardware H.264 encoder doesn’t work
Section titled “The hardware H.264 encoder doesn’t work”VSTUDIO_H264_ENCODER (or persona export.h264_encoder) chooses the encoder: libx264 (default), h264_videotoolbox on macOS, h264_mf on Windows. The engine test-encodes the chosen one once. If it doesn’t work on this machine, everything falls back to libx264 on its own, and a failed hardware encode is re-run with libx264. Nothing to fix unless you want the hardware encoder; then check your ffmpeg build supports it.
Whisper model download is slow, or you’re offline
Section titled “Whisper model download is slow, or you’re offline”The first transcription downloads the model into the Hugging Face cache (~/.cache/huggingface/hub, or $HF_HOME/hub): whisper-large-v3-turbo for mlx-whisper on Apple Silicon, large-v3-turbo for faster-whisper elsewhere.
- Let the first download finish once on a good connection; later runs reuse it.
- To use a model you already have:
VSTUDIO_WHISPER_MLX=/path/to/whisper-large-v3-turbo-mlxorVSTUDIO_WHISPER_FW=/path/to/faster-whisper-large-v3-turbo(a size name such assmallalso works). - Add
HF_HUB_OFFLINE=1so it never touches the network.
“font ‘…’ not found” warning
Section titled ““font ‘…’ not found” warning”A font role (cjk, cjk-bold, serif, mono …) is missing from ~/.cache/video-studio/fonts. Anything drawn with it uses a fallback face, which is why the warning is loud.
- Run
./install.shagain; it downloads the open-licensed fonts. - Or point the role at your own file in
persona.local.yamlunderfonts:. One face of a collection works aspath/to/Fonts.ttc#N.
“model ‘…’ not found” (MediaPipe)
Section titled ““model ‘…’ not found” (MediaPipe)”Face tracking, retouch, cover frame picking and matting use the MediaPipe face landmarker and segmenters. ./install.sh downloads them into ~/.cache/video-studio/models. Run it again if one is missing. Without a model, cover layouts fall back to a centred crop.
The Mac app can’t find the engine
Section titled “The Mac app can’t find the engine”The installed app carries its own engine. If a source build says the engine isn’t running or can’t start, the status line in Settings names it.
- Open Settings › Advanced › Engine. It shows the video engine, the Python and the engine data folder in use.
- Point the video engine at the folder that contains
lib/vstudio, and Python at an interpreter that hasrequirements.txtinstalled, then Restart the engine. - The same can come from the environment:
VSTUDIO_ENGINE_PATHfor the engine andDESK_PYTHONfor Python. The app looks at Settings first, then those variables, then the repo it lives in.
An old cache folder
Section titled “An old cache folder”Everything is cached under $VSTUDIO_CACHE, by default ~/.cache/video-studio. Older builds wrote some of it to ~/.cache/vstudio. That folder is still read but no longer written; delete it once you no longer need it.
AI providers
Section titled “AI providers”“Every AI provider failed” (llm-all-failed)
Section titled ““Every AI provider failed” (llm-all-failed)”The routed provider and all its fallbacks failed. The message lists which ones were tried.
- Check what this Mac has:
python3 -m vstudio.llm auth status, run from the repo’slibfolder, or Settings › AI in the app. - Fix the first failing one (login, key, local server), or add a fallback: in the app, per task; in the persona,
fallback: [codex, ollama]on the route.
A notice like llm-fallback (“Claude Code failed; Codex answered instead”) is not an error. The work was done by the next provider in the chain.
Claude Code login expired
Section titled “Claude Code login expired”The app checks Claude Code with a one-line round trip, because its own status can still say “logged in” after the token expired.
- In the app: Settings › AI › Sign in again. Your browser opens; if it shows a code, paste it into the app.
- In a terminal: run
claude, then/login(orclaude auth login).
The engine never sees your password or token. Nothing is lost when a run stops on an expired login: sign in, run it again, and finished stages are not redone.
“No model” or “didn’t answer” in the chat
Section titled ““No model” or “didn’t answer” in the chat”No model means nothing is connected: sign in, add a key or start a local model in Settings › AI. “The model didn’t answer this time” means one is connected but did not reply in time; Try again gives it more time. If you set a model for Codex, make sure your account can use it; an unsupported model fails every call. Time limits, effort and fallbacks: AI providers.
Batches
Section titled “Batches”A batch is slow
Section titled “A batch is slow”- Run
estimatebefore a large batch. After one pilot on an otherwise idle Mac, estimates use your machine’s measured speed (benchprints the table). - Transcription runs one at a time (whisper owns the GPU); rendering runs a few in parallel. Lower
--concurrency cpu-render=2if your Mac is also busy with other work; raise it only if it isn’t. VSTUDIO_H264_ENCODER=h264_videotoolboxuses the Mac’s hardware encoder for every encode.- Retouching long videos: the
fastpreset is about three times faster thanquality.
The disk is full
Section titled “The disk is full”python3 -m vstudio.batch du --batch <batch> # what uses the spacepython3 -m vstudio.batch clean --batch <batch> # delete regenerable intermediatesclean keeps JSON, covers, sheets and previews. For delivered client batches, cleanup-sources lists source files past their cleanup date (a dry run) and only deletes with the code it printed. Your own recordings outside the batch folder are never deleted.
Captions and cuts
Section titled “Captions and cuts”Names or terms are spelled wrong in captions
Section titled “Names or terms are spelled wrong in captions”Speech recognition writes names by sound.
- Proofreading with entity checks runs before captions are burned: place names are matched to their standard spelling, and your glossary terms are applied the same way everywhere. Run it, don’t skip it.
- Add your own fixes to
persona.local.yaml:subtitles: {term_fixes: [["[Tt]runking", "chunking"]]}(a regex and its replacement). Client batches use the client’s glossary. - Pass key terms to transcription up front (
asr: {prompt: "LangChain, RAG"}). - Fix a single caption in review. A change that adds or drops a spoken word is refused unless a re-hearing of that audio confirms it.
Cleanup cut too much
Section titled “Cleanup cut too much”python -m vstudio.cleanup verify OUTPUTre-transcribes the cut. A lost content word fails with its source and output time.- Keep the edit that covers it: reply
保留 7(or--keep 7) and apply again. - If it keeps happening, use a gentler profile (
gentlekeeps more pause and breath), or add words tocleanup.never_cutin the persona.
In the app, filler cuts that might be real words wait for your yes in the Inbox; answer “keep” for the ones you want.