The Guide

What it is

Orb Studio is a desktop app for making videos and live streams of a glowing, audio-reactive orb that speaks with any voice — yours, a recording, or a voice transformed through Voispark.

The modes, at a glance

• Studio — drop in an MP3/WAV and render the orb speaking it to an MP4. See your first video.
• Live — the orb reacts to your microphone in real time; record and render takes.
• Record — a screen-recording studio, with a no-AI manual lane and an AI producer lane. See Manual Recording Studio and AI producer.
• Voice Lab — transform a recording's voice through Voispark, then use it elsewhere.
• Agent — a managed content factory that researches, writes, voices and renders clips on a schedule.
• Assets — the shared library of video, image, audio and music the whole app draws on.
• Editor — a multi-track timeline for cutting everything together into a finished video.
• Renders — every finished MP4 you've produced.

Where things live

Finished videos land in your output folder — ~/Movies/Orb Studio by default on a fresh install. Change it any time in Settings → Output. Every API key you enter lives in Settings (voice, music) or Agent → Settings (writing).

Nothing is required to start. Every feature that needs a key just stays dormant until you add one — see Bring your own keys.

Getting back here

Reopen this Guide from the ? button in the top bar at any time. If you skipped setup or want to revisit it — a short tour plus your Voice, Writing and Music keys — use Run setup wizard again at the bottom of this sidebar. It's the same six-step wizard that can appear on first launch, and it never overwrites a key you've already entered.

The fastest path to a finished video

This takes about three minutes and needs no API keys.

1. Open the Studio tab.
2. Drop an MP3 or WAV onto the window — the dropzone reads 'Drop an MP3 — the orb speaks it.'
3. Click the wand icon, Auto-configure orb. It analyzes the audio and shapes the orb's color, motion and sensitivity to match it.
4. Adjust anything you like by hand in the inspector on the right — color, glow, particles, background.
5. Click Render MP4, pick a size and frame rate, and confirm.

The render runs in the background. When it finishes, the file is in your output folder and also appears in the Renders tab, ready to play or reveal in Finder.

Want the orb to say something you type, instead of an uploaded file?

That isn't what Studio does — Studio always plays back an audio file you provide. If you want narration written and spoken for you automatically, see Agent, which writes a script, voices it, and renders the orb on a schedule.

Bring your own keys

Orb Studio ships with no API keys built in. Voice and music keys live in settings.json and are shared by every brand on this install; writing (LLM) keys live in a per-brand agent.json, so each brand can run on its own account. Either way, a key is stored only inside the app's local data folder, and is never sent anywhere except the provider it belongs to.

What each service powers

• Voice changing (Voice Lab, Agent narration) — Voispark. See Voispark setup.
• Writing (Agent scripts, Posts, editor AI, demo director) — Straico, OpenRouter, Anthropic, or OpenAI; pick one or more. See LLM setup.
• Music generation (Agent music beds, Assets → Generate music) — VoiSpark Music, a Finetuning.ai account. See Music setup.
• Vision (Demo Browser autopilot) — Anthropic specifically; the other writing providers don't expose the computer-use tool it needs.

Every key is optional

Nothing stops working if a key is missing — the features that need it simply stay dormant until you add one. Studio, Live, Record's manual lane, the Editor and Renders all work with zero keys configured. The only non-key requirement anywhere in the app is ffmpeg, needed for the final MP4 encode — see ffmpeg.

Rolling a shared key set out to a team? See Team key import.

What Studio is for

Studio turns a pre-recorded MP3 or WAV into a finished video of the orb reacting to it. Use it when you already have a voice track — a podcast clip, a voiceover, anything — and want the orb performing it.

Loading audio

Drop a file onto the window, or click the dropzone to browse for one. The waveform appears with transport controls so you can scrub and preview before rendering.

Shaping the orb

Every visual property — core color, glow, particle behavior, background, sensitivity — is adjustable in the inspector. Two ways to set it:

• Click the wand (Auto-configure orb) to analyze the loaded audio and choose values that match its energy and pacing.
• Adjust any slider or color by hand, before or after using the wand.

The orb's overall style is also switchable in the inspector; each brand has its own default style, so a fresh brand already looks like itself from the first frame.

Rendering

Render MP4 opens a dialog for size (720p / 1080p / 4K / Square / Vertical), frame rate (30/60fps) and bitrate. Rendering captures canvas frames and program audio in real time, then ffmpeg encodes the result to H.264/AAC with fast-start for instant web playback.

Studio's auto-configure is a one-shot analysis, not a live reaction. If you want the orb to react to a live microphone instead of a file, that's Live.

What Live is for

Live drives the orb from your microphone in real time instead of a pre-recorded file — pick an input and the orb reacts as you speak.

Using it

1. Choose your microphone.
2. Speak — the orb pulses and glows to match your voice, live, on screen.
3. Record a take when you want to keep what you're doing. Recording captures the orb's performance and your microphone audio together.

After recording

A recorded take can be rendered straight to MP4, the same way Studio renders a loaded file. Or send it to Voice Lab first if you want to transform the voice before rendering — Voispark's voice changer works on recordings, not on the live signal itself.

Where Live fits

Live is the fastest way to get a natural, off-the-cuff performance out of the orb. If you'd rather have a script written and voiced for you automatically, that's the Agent. If you want to capture your screen with a presenter orb on top, that's Record.

The Studio lane

Inside Record, a lane switch at the top swaps between Studio (this lane — no AI, just you; not to be confused with the separate top-level Studio tab, which plays back an audio file) and AI producer (see AI producer).

Setting up a profile

An inline wizard walks you through, in order:

1. Source — screen, a specific window, your camera, or the built-in Demo Browser.
2. Camera bubble style.
3. Microphone.
4. Keep your own voice, or swap it after the fact.
5. Logo and lower-third branding.
6. Intro/outro title cards.
7. Extras — countdown, teleprompter, a max duration, and keep-awake.

Finish the wizard and it saves as a named, reusable profile — set it up once, reuse it for every future recording.

Recording and finishing

Recording bakes a live composite of everything — camera bubble, branding, title cards — so you see exactly what you'll get while you record. When you stop, you have two paths:

• Quick export — optional mic enhancement and AI voice swap, then straight to MP4.
• Open in Editor — the same take becomes a fully editable multi-track project, with the camera bubble, branding and title cards as separate, still-adjustable clips.

Every raw layer is kept regardless of which path you take first, so you can always open the same take in the Editor later.

The AI producer lane

The other lane under Record (switch at the top; see Manual Recording Studio for the human-first lane) is an agentic screen-recording studio. Record your screen, a window, or the built-in Demo Browser, with a presenter orb on top — then let the app do the editing work.

Polish and Auto-Director

• Polish — a one-click pass that cuts silences, removes filler words, and can swap in a different voice.
• Auto-Director — camera zooms, click callouts, captions and chapter cards, added automatically, landing in an editable Editor project.

Site research

Point it at a web app and it studies the site: crawling same-site pages up to five links deep, and distilling the pitch, pricing, integrations and the product's own terminology into a knowledge pack. Facts also flow into the Agent's knowledge base, so demos speak the product's real plan names and claims instead of guessing.

Autopilot and full auto

• Autopilot explores a site off-camera first, then performs the same path on-camera with a synthetic cursor.
• Create demo (full auto) goes all the way: give it a goal and a URL, and it produces a narrated, captioned MP4 with an SRT file, chapters and a thumbnail.

Claude can also drive any of this directly through the bundled MCP bridge — turn it on in Settings → Local agent control.

This lane needs an LLM key, and Anthropic specifically for autopilot's vision agent — see LLM setup.

What Voice Lab does

Voice Lab sends a recording — a take from Live or Record, or a file you upload — through the Voispark voice changer, and gives you back the same performance in a different voice. Browse ElevenLabs and Cartesia enhanced voices, transform, and A/B compare the result against the original before committing.

It is not real-time

The Voispark API is an upload → transform → download pipeline. It applies to recordings, not to a live microphone signal — there's no way to hear your voice changed as you speak.

The intended workflow

1. Record a take, in Live or Record, or upload an existing file.
2. Transform it in Voice Lab.
3. Use the transformed result in Studio, or render it straight to MP4 from Voice Lab itself.

Needs a key

Voice Lab needs a Voispark API key — see Voispark setup. Without one, this tab has nothing to work with.

The Camera window

Click the Camera button in the top bar to open a clean, chromeless window that shows only the orb — nothing else from the app. It stays on top of other windows by default (configurable in Settings → Camera window).

Using it in OBS

In OBS: Sources → Window Capture → Orb Camera. For a keyable orb, pick the Broadcast preset in the inspector — it sets a solid chroma-green background — and add a Chroma Key filter on top of the capture in OBS.

Sharing directly

For Zoom, Meet or Teams, you can skip OBS entirely and just share the Camera window itself, the same way you'd share any application window.

No built-in virtual camera

Orb Studio doesn't install a system-level virtual camera driver — macOS requires a signed CoreMediaIO extension for that, which this app doesn't ship. OBS Virtual Camera bridges the gap: capture the Orb Camera window in OBS, click Start Virtual Camera, then select 'OBS Virtual Camera' as your camera inside any meeting app.

Upgrading from an older build? The capture source was renamed from ChatWisp Camera to Orb Camera — re-select it once in OBS's Window Capture source.

What the Agent does

The Agent is a managed content factory. A job researches your brief and whatever sources you've added, writes a roughly 30-second monologue with an LLM, optimizes it for delivery, voices it through Voispark, and renders the orb MP4 — automatically, in a hidden window, start to finish.

Jobs and schedules

Create a job and give it a schedule, or run it on demand. Jobs only run while the app is open — there's no background service outside the app itself.

Deep-dive mode

Deep-dive plans a fresh content angle and one specific product facet on every run, reading back a memory of past clips so it doesn't repeat itself. It deliberately works through your brief's features, capabilities, values and benefits over time, rather than circling the same few ideas.

Casting from your library

The Agent has full visibility into your Asset Library and features whatever clips or images actually match what it's saying. When it finds a strong product moment, it can stage it as a large showcase, with the orb tucked in the corner instead of centered.

Music beds

Set the music bed option to Generate and the Agent composes a fresh instrumental to match each clip's mood, mixed low and ducked under the voice — see Music setup for the account it uses.

Editable projects from runs

Turn on Create an editable Editor project from each run in the Agent's settings and every finished run also lands in the Editor as a ready-made project — the master pre-split at scene cuts, voice and music stems, chapter markers, and an Open in Editor button on the run's history row. See From Agent run to Editor project.

Review

Every run's script, plan and finished video are reviewable from the Agent tab, along with the brand brief and voice settings that drive it.

Writing needs at least one LLM key — see LLM setup.

What the Publisher does

Posts, found inside the Agent tab, is a researcher and writer for blog posts and social posts. Every post is grounded in freshly fetched sources, with inline [n] citations back to them, and hard-capped at 2,800 characters including hashtags.

The writing style

Drafts are written to sound like a sharp human wrote them: cliché-scrubbed, with one bounded self-edit pass against the app's own style rules — not a first-draft LLM ramble.

The flow

1. The Publisher researches and drafts a post.
2. You review and approve it — nothing publishes on its own.
3. Optionally, click Create video: the Agent writes a spoken script that tells the same story as the approved post, and produces a matching orb video, so your written and video content stay aligned instead of drifting apart.

Needs a key

Posts runs on the same LLM providers as the rest of the Agent — see LLM setup.

A run you can re-cut

By default an Agent run delivers a finished MP4 and stops there. Turn on Create an editable Editor project from each run in the Agent's settings and every run also lands as a ready-made project in the Editor — the same video, opened up for re-cutting, with the narration and music as separate stems.

For a single run, override it from the Guided launcher instead: under Deliverables — this run only, the Editor project from this run switch offers Inherit / On / Off, so one special run can produce a project — or skip producing one — without touching the saved setting.

What the project contains

• V1 — the delivered master, pre-split at every scene boundary. Each cut sits exactly where the scene sits in the source, so audio and video stay aligned however you trim, and retiming a scene means dragging a cut that already exists instead of hunting for the right frame.
• A1 — the narration stem, muted. It's also imported into the Asset Library — tagged Agent and Voice, and excluded from future casting — so it outlives the Agent's own short-lived working cache.
• A2 — the music bed, when the run cast or generated one. Muted too, with a fade-out already in place.
• Chapter markers — one per scene, named for the scene, so you can jump straight to the part you want to change.

The stems ship muted because the master on V1 already carries the finished voice-and-music mix — leave them alone and the project sounds exactly like the delivered MP4. Unmute a stem, and pull the master clips' volume down, when you want to re-balance the mix, swap the music, or keep just the narration under new visuals.

Opening it

A run that produced a project grows an Open in Editor button — the film icon — on its row in the Agent's history. One click puts the timeline in front of you. And if project creation ever fails, the run itself still succeeds: you keep the finished MP4 either way.

What the Asset Library is

The team's shared media library: drag in videos, images and audio, and every orb render made anywhere in the app registers itself here automatically — you never have to manually import your own output.

Describing and tagging

For each asset, you can write what's happening in it and when to use it — the Agent reads that description when it's deciding what to feature in a clip. Tags (Product Demo, Intro, Outro, Music, Voice, Other, or your own custom tags) give you a second way to organize and filter the library.

Non-destructive editing

Trim, crop and adjust volume right in the library. None of it touches the original file — edits are applied on top, so you can always get back to the source.

Generate music

Generate music composes a royalty-free track from a text description, using VoiSpark Music, and drops it straight into the library ready to use as a bed. See Music setup.

Feeding the Agent

Everything you describe and tag here is what the Agent draws on when it casts clips into a video — a well-described library is what makes its choices feel intentional instead of random.

When a file goes missing

Renders and recordings register here in place — the files stay in your output folder, where they can be moved, tidied or deleted outside the app. A card whose file is gone gets a Missing badge, and an N missing chip appears in the header. Move the file back where it was and the card heals on its own; or relink a recovered copy — hover the card for the Relink button, or just drop the file onto the card. The full lifecycle, including why exports refuse to run with offline media, is in Missing media and relinking.

What the Editor is

A multi-track timeline for cutting library assets, orb renders, titles and music into one finished video — layer video and audio tracks, drag, trim and split clips, and adjust each clip's position, scale, opacity and volume independently.

Projects come from wherever you work: start one from scratch, send a Record take over with every layer intact, or have the Agent deliver each run as a ready-made project.

Chroma key and cross-dissolves

Render the orb with the Broadcast preset's green background (see Camera) and key it over any other clip in the timeline. Overlapping two clips on different tracks, each with a fade, gives you a cross-dissolve.

Titles, fades, undo

Add titles, fade clips in and out, and undo/redo freely — projects autosave as you work, so there's no separate save step to remember.

Brand Kit

The Brand button in the toolbar opens the Brand Kit: the colors every graphic reads — lower thirds, callouts, stats and all the charts — plus a logo watermark you can stamp across the whole timeline as a normal image clip. The kit is saved per brand, so each client's projects pick up that client's colors without any copying — see Brands.

Save clip

Mark an in-point and out-point on the timeline with I and O, then Save clip slices exactly that range straight into the Asset Library — name it, describe it, and set whether the Agent is allowed to use it. This is how one long recording becomes many small, reusable, described assets, without re-rendering each piece by hand.

Exporting

Export runs in real time and produces the same H.264/AAC MP4 format as every other render, landing in your output folder alongside everything else.

When a clip goes offline

A clip whose source file has left the disk shows an offline badge on the timeline, and the preview paints a MEDIA OFFLINE slate instead of black frames. Export refuses to start while any clip is offline — it names the clips that need attention instead of failing anonymously partway through. Select the clip and use the inspector's Relink button, or fix it from the Assets tab — see Missing media and relinking.

One install, many clients

The chip in the top bar names the brand every other control in the app acts on. A brand owns its own agent config and writing (LLM) keys, asset library, Agent's knowledge base, posts, editor projects and recordings, Brand Kit (colors, logo, watermark) and Demo Browser logins — and nothing there leaks between brands. An agency can bill each client against that client's own LLM key.

Voice (Voispark) and Music (VoiSpark Music) keys are the one exception: like the output folder, ffmpeg and the transcription models, they're shared across every brand rather than set per brand — see Bring your own keys.

Upgrading from an older build? Two things that used to be shared moved into the brand: the Brand Kit — each brand's kit starts as a copy of your old shared one, so nothing looks different until you restyle a brand — and Demo Browser logins, which now live in a per-brand browser session that site research shares. Expect to sign in once per brand the first time each brand opens the Demo Browser.

Creating a new brand

New brand… opens the Brand Setup Wizard — a different flow from the app's first-run setup:

1. Name, color and logo.
2. The client's website — Study the site crawls it and drafts the brand brief for you.
3. Review and edit the brief and its sources.
4. Narration voice and delivery style.
5. API keys — copy the ones you're already using, enter new ones, or start empty.
6. Review, then create.

Nothing is written to disk until that final step, so cancelling partway through leaves no trace. If the site crawl hasn't finished by the time you create the brand, it hands off and keeps running in the background — the brief fills itself in once it's done.

Switching brands

Switching brands reloads the window. A removed brand is moved to brands/_trash, never deleted outright.

New brand… is available from the brand switcher (top bar) or Settings → Brands. It's separate from Run setup wizard again in this Guide's sidebar, which redoes this install's first-run Voice/Writing/Music setup rather than creating a new brand.

What it powers

Voispark powers every voice transformation in the app: Voice Lab's voice changer, and the voices the Agent uses to narrate its clips. It gives you access to ElevenLabs and Cartesia's enhanced voice catalogs through one account.

Getting a key

Sign up at voispark.com↗. The free tier includes 15,000 credits a month; Pro is $9.90/mo for more. Copy the API key from your account.

Entering it

Paste it into Settings → Voispark API, or on the Voice step if you're going through the first-run Setup Wizard. Either place lets you confirm it works before moving on — Test connection in Settings, Test key in the wizard — and a successful test also shows your current plan and remaining credits.

One key for every brand

Unlike writing keys, Voispark isn't set per brand — enter it once and every brand on this install uses it, the same way they all share one output folder. See Brands for what is and isn't shared.

Base URL

The base URL field defaults to https://api.voispark.com/api and almost never needs to change — leave it alone unless Voispark tells you otherwise.

Five providers, pick one or more

The Agent's writing — scripts, Posts, editor AI, the demo director — runs on an LLM you configure per brand, in Agent → Settings → API providers:

• Straico — straico.com↗. Coin-based: one balance spends across many models.
• OpenRouter — openrouter.ai/keys↗. Pay-as-you-go; one key reaches Claude, GPT, Gemini and more.
• Anthropic — platform.claude.com↗. Direct access to Claude, and the only one of the four that exposes the computer-use tool Autopilot needs.
• OpenAI — platform.openai.com↗. Direct access to GPT.

• Ollama — ollama.com↗. Local models on your own machine: private, free, no key, works offline.

The four cloud providers use plain API-key auth — no OAuth — so a copied key pastes straight in. Ollama needs no key at all.

Ollama — local and free

Install the Ollama app from ollama.com↗, pull at least one model (for example, run ollama pull llama3.3 in a terminal), then flip Use Ollama on — in the setup wizard's Writing step or in Agent → Settings → API providers. Leave the model field empty to use the first installed model, or name a specific one. The base URL only changes if you run Ollama somewhere other than the default http://127.0.0.1:11434.

Local models write scripts and posts fully offline, but two features still need the cloud: live-web research (a browsing model via OpenRouter/Straico) and Autopilot's vision agent (Anthropic's computer-use tool).

Primary and fallback

Pick an Active writer — the provider that runs by default. Turn on provider fallback and, if the active writer fails, the app automatically tries the other configured providers (Ollama last, as the local safety net), instead of failing the whole run. Even with no key configured anywhere, a job still won't hard-fail — it drops to a basic templated script rather than an error, though real writing quality needs a real provider.

Per brand

Every brand keeps its own set of keys and its own active-writer choice — see Brands. Nothing is shared between brands unless you copy the keys yourself.

Model defaults

Each provider has a default model, editable in the same section — useful if you want to point a provider at a cheaper or newer model without switching providers entirely.

Autopilot's vision agent specifically needs the Anthropic key, even if your active writer is something else — the other three don't expose the computer-use tool it drives on.

What it powers

VoiSpark Music generates royalty-free instrumental tracks: the Agent's music beds, and Generate music in the Asset Library.

Getting a key

It runs on a Finetuning.ai account. Sign up at finetuning.ai↗ and copy the API key from your account — it looks like ft_live_….

Entering it

Paste it into Settings → Music generation, or on the Music step of the first-run Setup Wizard. The base URL defaults to https://pub.finetuning.ai/v1. Testing it confirms the key works and shows your tier and remaining generations.

One key for every brand

Like Voispark, this key is set once for the whole install rather than per brand — see Brands.

About Suno and Udio

You may have heard of Suno or Udio for AI music. Neither has a public, self-serve API — any 'Suno API' offered by a third party is unofficial, and using one carries a real terms-of-service risk. Orb Studio doesn't integrate with either for that reason. VoiSpark Music is the supported path.

Rolling keys out to a team

If your team already shares a set of API keys, you don't have to re-type them on every machine. Drop a file named import-keys.json into the app's data folder before first launch, or any time after:

• macOS: ~/Library/Application Support/Orb Studio/
• Windows: %APPDATA%\Orb Studio\

The next time Orb Studio starts, it imports whatever keys are in that file — but only into fields that are still empty. A key you've already entered yourself is never overwritten. Once it's applied, the file is renamed import-keys.json.imported so it can't be re-applied by accident.

Doing it manually, mid-session

You don't have to restart the app for this: Settings → Import keys file… does exactly the same import from a file you pick, on demand.

This only ever fills gaps — it's safe to re-import the same team file on a fresh install without worrying about it clobbering a key someone already set by hand.

What ffmpeg is for

Orb Studio captures video and audio in real time on its own, but the final step — transcoding that capture to a streaming-ready H.264/AAC MP4 — is done by ffmpeg. It's the only piece of the pipeline that isn't bundled in.

Without it

Everything else still works. Studio, Live, Record, Voice Lab and the Editor all run normally; only the very last conversion to MP4 fails until ffmpeg is installed.

Installing it

On macOS, with Homebrew:

brew install ffmpeg

On Windows, with winget:

winget install ffmpeg

ffmpeg needs to be on your system PATH — a normal package-manager install handles that for you.

Checking status

Settings → Output shows a status dot and the detected path. If it's red, click Re-check after installing — no restart needed. The first-run Setup Wizard checks the same thing on its last step, so you may already have seen this status once.

Test connection fails

Work through these in order:

1. Whitespace. A trailing space or newline from copy-paste is the single most common cause — re-copy the key and paste it fresh.
2. The right key in the right field. Voice keys go in Settings; writing keys go in Agent → Settings, per provider. A Voispark key pasted into an LLM field, or vice versa, fails cleanly but confusingly.
3. Quota or billing. Check the provider's own dashboard — a key can be valid and still fail if the account is out of credits or billing has lapsed.
4. The current brand. LLM keys are per brand — see Brands. A key that works in one brand doesn't automatically apply to another.

Which feature reads which key

• Voice Lab and Agent narration → Voispark, in Settings.
• Agent scripts, Posts, editor AI, demo director → whichever LLM provider is active, in Agent → Settings.
• Autopilot's vision agent → Anthropic specifically.
• Music beds and Generate music → the Finetuning.ai key, in Settings.

Fallback behavior

If provider fallback is on and your active writer fails mid-run, the app automatically tries the other LLM providers that have keys configured before giving up. If every configured provider fails, the run stops and the error tells you which providers it tried.

See LLM setup and Voispark setup for where each key is entered.

What the Missing badge means

An asset is a library row plus a file on disk — and for renders and recordings, that file lives in your output folder, where things get delivered, tidied and deleted outside the app. When a file is no longer where the app last saw it, the asset is marked Missing: its card in Assets gets a badge and a hatched overlay, an N missing chip appears in the Assets header, and any Editor clip that uses it shows an offline badge with a MEDIA OFFLINE slate in the preview instead of black frames.

Nothing else is lost. The row, its description, tags and edits — and every timeline that references it — all survive; the app just can't find the file right now.

The easiest fix: put the file back

If the file still exists, move it back to where it was and the asset heals on its own the next time the app checks — switching back to the app window is enough, or click the N missing chip to re-scan on the spot. No relinking, nothing to redo. Open the card and the banner spells this out, naming the last-seen path for files tracked in your output folder.

Relinking a recovered copy

If the original location is gone for good, point the asset at a new copy instead. Any of these work:

• Hover the missing card in Assets and click Relink, or open the card and use the banner's Relink… button.
• Drop the recovered file straight onto the missing card.
• In the Editor, select the offline clip and use the Relink button in the inspector — or click the missing asset in the drawer, which offers to relink instead of placing it.

Relinking keeps the asset's id, name, description and tags, so every clip in every project that references it heals the moment the relink lands. The replacement has to be the same kind of media — video for video, audio for audio — though the file format can differ. Saved trims and crops re-apply when they still fit the new file; if they don't, they're cleared and the app tells you.

Why export refuses to start

Export checks the whole timeline first and refuses to start while any clip's media is missing — and it names the clips, with a shortcut to the first one. That's deliberate: without the check, a missing video file used to fail the export a minute and a half in without naming a clip, and a missing audio file would export "successfully" with a silent gap where the sound should be. Fix or remove the named clips and export runs normally.

The Agent never casts a ghost

The Agent skips missing media when casting from your library, and re-checks every scene again right before rendering — casting to render can be minutes apart, and a file can vanish in between. A scene whose clip disappeared falls back to a designed visual instead of shipping a black frame.

Recording permissions (macOS)

The first time you record your screen or use a microphone, macOS asks for permission. If you skipped or denied either prompt, grant them manually in System Settings → Privacy & Security:

• Microphone — required for Live and for any recording in Record.
• Screen Recording — required to capture your screen or a window in Record.

After granting a permission there, you may need to quit and reopen Orb Studio for it to take effect.

Opening an unsigned build (macOS)

Orb Studio's builds are unsigned. The first time you open one on a given Mac, Gatekeeper refuses a normal double-click. Instead, right-click the app and choose Open — that gives you an Open option a plain double-click doesn't offer. You only need to do this once per machine.

Opening an unsigned build (Windows)

Windows SmartScreen shows 'Windows protected your PC.' Click More info, then Run anyway. Again, only needed the first time.

Does my audio or my keys leave my machine?

Only to the providers you've configured, and only for the request that needs them — a voice transform goes to Voispark, a script goes to whichever LLM you've set up. Nothing is sent anywhere else, and nothing is sent at all for features with no key configured.

Can I change my voice in real time?

No. Voice changing is upload → transform → download, not live. See Voice Lab for the intended workflow: record a take, transform it, then render.

Can I use the orb as a virtual webcam?

Not directly — Orb Studio doesn't install a virtual camera driver. Bridge it through OBS Virtual Camera instead; see Camera.

Where do my renders go?

Your output folder, set in Settings → Output — ~/Movies/Orb Studio by default on a fresh install.

A clip says Missing — did I lose work?

No. The library entry, its description and tags, and every timeline that uses the clip all survive; only the file has left the disk — usually because something in your output folder was moved or tidied. Put the file back and it heals automatically, or relink a recovered copy. See Missing media and relinking.

Can I use this offline?

Mostly. Studio, Live, Record's manual lane, the Editor and playback all work with no internet connection. With Ollama enabled, the Agent's and Posts' writing runs offline too, on local models. Anything that calls a cloud provider — Voice Lab, narration voices, music generation, live-web research, Autopilot — needs a connection and a key. The final MP4 export needs ffmpeg installed locally, which itself needs no connection once installed. See ffmpeg.

Do brands share API keys?

Partly. Writing (LLM) keys don't — each brand has its own, so an agency can bill every client against that client's own account. Voice (Voispark) and Music (VoiSpark Music) keys do — they're set once for the whole install and shared by every brand, the same way the output folder and ffmpeg are. See Brands. A team key import can seed a fresh install's starting keys too — see Team key import.

Why did the Demo Browser log me out after upgrading?

Demo Browser logins are now kept per brand, so each brand gets its own browser session instead of every brand sharing one. The first time each brand opens the Demo Browser after the upgrade, sign in once — from then on it sticks, per brand. See Brands.