Troubleshooting Zella

Quick answer: Most Zella issues are one of three things — a permission (relaunch after granting Screen Recording), a dark room (webcams drop fps in low light), or watching the preview instead of the exported file (the file is frame-accurate; the preview is decode-optimized). Find your symptom below for the exact fix.

Most issues come down to a permission, a dark room, or watching the preview instead of the file. This chapter is organized by symptom so you can jump straight to the fix.

25.1 Recording problems

The screen is black in my recording. Screen Recording permission is off, or was granted mid-session. Open System Settings ▸ Privacy & Security ▸ Screen Recording, enable Zella, then quit and relaunch Zella (the permission only applies to a fresh launch).

There’s no audio. Microphone permission is off, or the wrong input is selected. Check Privacy & Security ▸ Microphone. If you use a USB mic (e.g. Yeti), make sure it’s the selected input and not a duplicate/ghost device. Relaunch if you just changed it.

My camera bubble is black / very choppy. Either Camera permission is off (Privacy & Security ▸ Camera), or — far more often — the room is dark. Webcams drop their frame rate in low light to expose properly. Add light and it recovers. Audio and sync are unaffected.

The Start Recording button does nothing. The Setup panel is a floating, non-activating window; use the keyboard shortcut ⌘⇧R instead.

The recording feels like ~1 fps even with good light (screen capture). Zella drops unchanged frames to keep files small. A static screen legitimately produces few frames — the video still plays correctly (each frame holds until the next). Move something on screen (or your cursor) and the frame count climbs. Judge a recording by whether it plays smoothly and stays in sync, not by raw frame count.

The app froze at the start of recording. This is almost always running a debug build with Metal API Validation + the Xcode debugger attached. Run the release app normally (not under the debugger). For everyday use, just launch Zella from Applications.

My Mac slept and the recording got cut off. Don’t manually sleep the display mid-recording. Zella holds a “prevent display sleep” assertion, but a forced sleep on some GPUs ends the capture. Keep the display awake for the duration.

25.2 Audio / video sync

Audio seems slightly out of sync in the editor. The preview is decode-optimized for smooth scrubbing and can look marginally off on some GPUs. The exported file is frame-accurate. Export and check the file (step around a clap/transient) before assuming the recording is off — the file is almost always perfect.

My camera audio leads/lags my lips. Zella calibrates this at record time, including the hard case of a bubble over a blurred/AI-removed background. If you still see an offset, note the background style you used and re-record; also confirm you’re judging the file, not the preview.

25.3 Editor & tools

Generate Captions / Remove Fillers found nothing. The clip needs spoken audio, and Speech Recognition permission must be on (Privacy & Security ▸ Speech Recognition). Also note Apple’s engine often won’t transcribe pure “um”/“uh,” so those may not appear as removable tokens (cut them by hand).

The luma scope (Effects) looks empty. Move the playhead so the preview renders a frame, then use the scope’s refresh control. The scope reads the source frame at the playhead.

My silence removal + transitions exported at the full length. Combining heavy silence/ripple removal with transitions in the same project is a known edge in the transition export path (each works alone). Workaround: do major cuts or transitions, and if you need both, verify the exported duration; otherwise export the cuts version without transitions.

A transform keyframe disappears across a transition. Known limitation — keyframes are dropped under a transition (the transition compositor owns that segment). It won’t crash. Place the keyframed move a beat away from the transition.

I deleted all my clips and the timeline is empty. That’s fine — Zella won’t crash on an empty timeline; it shows a held/blank frame. Undo (⌘Z) to bring your clip back.

25.4 Export

My image + audio project wouldn’t export (older versions). A still image plus an audio overlay needed the still to carry an audio track; current Zella adds a silent track automatically so these projects export. Update to the latest build. On macOS playback the audio is heard normally.

The export has audio I can’t hear in another player. Overlay exports can contain multiple audio tracks; macOS QuickTime/AVPlayer mix them at playback. If a non-Apple player only plays the first track, re-export, or flatten the audio in an external tool. (A single-track mix-down is on the roadmap.)

I cancelled an export — is there a broken file? No. Cancelling is clean; no half file or lock is left behind. Re-export when ready.

25.5 Stability & recovery

Zella crashed / I force-quit. Relaunch. If a recovery prompt appears, accept it to rescue the unfinished recording/project. Projects are written atomically, so you’ll reopen to the last good state.

The app feels wedged after a weird session. Choose Quit from the Zella menu and relaunch from Applications. Autosave + recovery make this safe.

25.6 Frequently asked questions

Is there a subscription? No. Zella is a native app you run locally.

Does my footage go to the cloud? No. Recording, transcription, editing, and export all happen on your Mac.

Apple Silicon vs. Intel? Both are supported. A few extras (Vision face/saliency auto-track) are Apple-Silicon only and disable themselves on Intel — no crash.

Where are my recordings? In your output folder (default ~/Desktop/Zella), named Zella_<date>_<time>.mp4. Change the folder in the Setup panel.

Can I edit a video I didn’t record in Zella? Yes — drag any video file into the editor / onto the app, or add it via the Clip Browser.

What macOS do I need? macOS 14 (Sonoma) or later.

➡ Continue to 26. Glossary.

Pro tips & gotchas

• A re-prompt for Screen Recording after an update is normal — re-grant once and relaunch.
• If the camera delivers no frames, launch Zella normally (via its icon), not from a script — macOS won’t show the camera prompt otherwise.
• Wrong mic recorded? Set the input in the Setup panel before the take and watch the preview.
• A webcam in a dark room legitimately drops to ~1 fps while it exposes — add light for smooth motion.