Troubleshooting Zella

Quick answer: On the Mac, most issues are one of three things - a permission (relaunch after turning on Screen Recording), a dark room (webcams run at a lower frame rate in low light), or watching the preview instead of the exported file (the file is exact frame-by-frame; the preview is tuned for smooth scrubbing, not perfect accuracy). On iPhone, the usual snags are the one-time caption-model download, translation needing iOS 18, and knowing which two features touch the network. Find your symptom below for the exact fix.

Sections 25.1 to 25.5 cover the Mac app; On iPhone covers the phone. This chapter is sorted by symptom, so you can jump straight to your problem and its fix.

25.1 Recording problems

The screen is black in my recording. Screen Recording permission is off, or you turned it on partway through a session. Open System Settings ▸ Privacy & Security ▸ Screen Recording, turn on Zella, then quit and reopen Zella. The permission only takes effect on a fresh start.

There’s no audio. Microphone permission is off, or the wrong input is picked. Check Privacy & Security ▸ Microphone. If you use a USB mic (like a Yeti), make sure it’s the one selected, and not a leftover duplicate (a ghost device - an old copy of the mic that’s still listed). Reopen Zella if you just changed it.

My camera bubble is black or very choppy. Either Camera permission is off (Privacy & Security ▸ Camera), or - far more often - the room is dark. Webcams slow down their frame rate in low light so they can still get a bright enough picture. Add some light and it recovers. Your audio and sync aren’t affected.

The Start Recording button does nothing. The Setup panel is a floating window that doesn’t take over focus, so clicking its button may not register. Use the keyboard shortcut ⌘⇧R instead.

The recording feels like about 1 fps even with good light (screen capture). To keep files small, Zella skips frames that didn’t change. A screen that’s holding still (static) honestly produces very few frames - the video still plays correctly, because each frame stays on screen until the next one. Move something on screen (or your cursor) and the frame count goes up. Judge a recording by whether it plays smoothly and stays in sync, not by the raw frame count. (fps means frames per second - how many still pictures make up each second of video.)

The app froze at the start of recording. This almost always means you’re running a debug build with a developer tool called Metal API Validation turned on and the Xcode debugger attached. Run the normal release app instead (not under the debugger). For everyday use, just open Zella from your Applications folder.

My Mac went to sleep and the recording got cut off. Don’t put the display to sleep by hand while recording. Zella tells the Mac to keep the display awake, but a forced sleep can still end the recording on some graphics chips. Keep the display awake the whole time.

25.2 Audio / video sync

Audio seems slightly out of sync in the editor. The preview is tuned to scrub smoothly, so it can look a little off on some graphics chips. The exported file, though, is exact frame by frame. Export the file and check it (clap once and step through the frames around the clap) before assuming the recording is off. The file is almost always perfect.

My camera audio is ahead of or behind my lips. Zella lines this up automatically while you record, even in the tricky case of a camera bubble over a blurred or AI-removed background. If you still see it off, make a note of which background style you used and record again. Also double-check that you’re judging the exported file, not the preview.

25.3 Editor & tools

Generate Captions or Remove Fillers found nothing. The clip needs spoken words in the audio, and Speech Recognition permission has to be on (Privacy & Security ▸ Speech Recognition). Also, Apple’s speech engine often won’t pick up plain “um” and “uh” sounds, so those may not show up as things you can remove - cut them by hand.

The luma scope (Effects) looks empty. The luma scope is a graph that shows how bright the current frame is. Move the playhead so the preview shows a frame, then click the scope’s refresh button. The scope reads the frame the playhead is sitting on.

My silence removal + transitions exported at the full length. Using heavy silence or ripple removal together with transitions in the same project is a known rough spot in how transitions export (each one works fine on its own). Workaround: do your big cuts or your transitions, not both. If you truly need both, check the length of the exported file. Otherwise, export the cuts version without transitions.

A transform keyframe disappears across a transition. This is a known limitation - keyframes get dropped inside a transition, because the transition takes over that stretch of the timeline. It won’t crash. Just place the keyframed move a little bit 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 just shows a blank frame. Press 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 used to need the still to carry its own audio track. Current Zella adds a silent track for you, so these projects export fine. Update to the latest version. When you play it back on a Mac, the audio sounds normal.

The export has audio I can’t hear in another player. Exports with overlays can hold more than one audio track. On a Mac, QuickTime and AVPlayer blend those tracks together when you play the file. If a non-Apple player only plays the first track, export again, or combine the audio into one track using another app. (Combining everything into a single track automatically is on our to-do list.)

I cancelled an export - is there a broken file? No. Cancelling is clean - Zella doesn’t leave a half-finished file behind. Just export again when you’re ready.

25.5 Stability & recovery

Zella crashed, or I force-quit it. Open it again. If a recovery prompt shows up, accept it to rescue the unfinished recording or project. Projects are saved safely (each save either fully finishes or doesn’t happen at all), so you’ll reopen to the last good version.

Since Mac 1.0, recordings are crash-safe while they happen: camera recordings on every Mac, and all recordings on Apple Silicon, are written in one-second checkpoints - a crash or power loss mid-take loses at most the final second, and the relaunch offers the rescued take ready to edit.

The app feels stuck after a strange session. Choose Quit from the Zella menu, then open it again from your Applications folder. Autosave and recovery make this safe to do.

On iPhone

I can’t find Zella in the App Store. Zella for iPhone is coming to the App Store and isn’t downloadable yet. When the listing goes live it will be a free download. The Mac app is coming to the Mac App Store, and your Pro unlock carries over automatically because Pro is a Universal Purchase.

Captions asked to download something. That’s the verbatim on-device Whisper model, about 145 MB, fetched once the first time you transcribe. After that, transcription is fully offline. It’s a one-time download, not a per-video one.

I’m offline and captions still worked, but the “um”s survived. That’s the fallback path working as designed. If the Whisper model hasn’t downloaded yet, Zella falls back to Apple’s on-device recognizer, so captions still appear - but that transcript is cleaned, so plain “um” and “uh” may not be there to cut. Trim them by hand, or run the transcription again once the model has downloaded. Full detail in on-device AI.

The translate option isn’t showing. On-device caption translation needs iOS 18 or later. On older versions the option simply isn’t offered and everything else still works. Also generate your captions first - translation rewrites an existing caption track, so there’s nothing to translate without one.

Translation says it needs a language model. iOS fetches each language’s offline model once. Grab it in Settings › Translate, then come back - after that it’s instant and offline. If a language pair isn’t supported on your device, Zella says so plainly rather than silently doing nothing. See captions & titles.

Auto B-Roll is asking for a key. Only the optional real-stock-footage path needs one. The default Add cutaways generates gradient cutaway cards on-device with no key, no account and no network. A free Pexels or Pixabay key is only for the optional path, and it’s kept in the device Keychain. See Auto B-Roll.

The AI Assistant won’t respond. It needs a free language-model provider key, which stays on the device, and a network connection for the prompt itself. Only your typed prompt is sent - your video never leaves the phone.

I got a call mid-recording. Did I lose the take? No. Recording on iPhone is segmented and crash-safe - the footage is written as it goes, so everything up to the interruption is safe. The same applies to a low battery or the app being backgrounded. See recording on iPhone.

Text Behind Subject did nothing useful. It relies on the on-device subject cutout, so it needs a clear subject in frame - it shines on talking-head shots.

Which features on the phone use the internet? Three, all opt-in: the optional stock-footage b-roll (only a keyword leaves) and the AI Assistant (only your typed prompt leaves). Everything else - Auto-Polish, captions, translation, Make Vertical, background removal, cutaway cards, colour and export - runs entirely on the device.

25.6 Frequently asked questions

Is there a subscription? No. Zella is an app you install and run right on your device. Pro is a one-time $89 Universal Purchase covering Mac and iPhone together.

Does the free tier watermark my video? No - never, on any device or tier. Free exports are always clean. The only free ceilings are 2 minutes and 1080p, and 1080p is free forever.

Does my footage go to the cloud? No. Recording, transcribing, editing, and exporting all happen on your own device - Mac or iPhone.

Apple Silicon vs. Intel? Both work. Even the Vision-powered auto-track that follows a face runs on both: Apple Silicon takes the fast path, and Intel runs it on the CPU, which is slower but fully supported.

Where are my recordings? In your output folder (by default ~/Desktop/Zella), named Zella_<date>_<time>.mp4. You can 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 or onto the app, or add it through the Clip Browser.

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

What iOS do I need? iOS 18 or later, on iPhone. Zella is an iPhone app: it installs and runs on iPad too, in iPhone compatibility mode, but it is not laid out for the bigger screen yet.

➡ Continue to 26. Glossary.

Pro tips & gotchas

• Being asked for Screen Recording permission again after an update is normal - just grant it once and reopen the app.
• If the camera shows no video at all, open Zella normally by clicking its icon, not from a script - otherwise macOS won’t show the camera permission prompt.
• Recorded with the wrong mic? Pick the right input in the Setup panel before you start, and keep an eye on the preview.
• A webcam in a dark room really does slow to about 1 fps while it works to get a bright picture - add light for smooth motion.
• On the phone, a download prompt during captions is normal - it’s the one-time verbatim transcription model, and everything is offline afterwards.

Still stuck?

If nothing above fixed it, ask in the Zella Community on Facebook. It is the main support channel: members and the team answer there daily, and because it is public you can search it first - most problems have been hit by someone else already. Post your device, your macOS or iOS version, and a screenshot if you have one.

For anything private, like a purchase or a receipt, email support@zellahq.com instead. Full detail on both routes is on the support page.

Related: Install & permissions → · Projects & recovery → · Export → · On-device AI on iPhone → · Recording on iPhone →