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.

It opens on the Start tab. On the left is the Content Agent, a chat that makes product commercials for you and asks you before every step that spends or ships (Commercials with the Content Agent). On the right is a quick orb video that needs nothing at all: type a sentence and the orb speaks it. Everything else in the app is optional until you want it.

The modes, at a glance

• Start — where the app opens. Chat with the Content Agent to make a commercial, or type a sentence and the orb speaks it — the quick video needs no key, no account and no file. See Commercials with the Content Agent and your first video.
• Studio — drop in an MP3/WAV and render the orb speaking it to an MP4.
• 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, with a thumbnail, an in-app preview, and where each one came from.

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. The Start tab lists which of them are set up and which are not, with a button on each gap, so you never have to find out by watching something fail.

When something goes wrong

The ! button in the top bar opens Activity: everything the app has told you went wrong this session, in full, and it does not clear itself after a few seconds the way a toast does. Anything that names a place in the app — *"Agent → API providers"* — carries a button that goes there and scrolls the exact control into view.

Setup, and getting back to it

First launch opens a short setup flow: a tour, then who this studio is for (a brand name, colour and orb style), then your Voice, Writing and Music keys. Every step has a "Skip this step" button — nothing in it is required, and skipping a step never blocks the next one.

You do not have to finish it in one sitting. Start carries a Finish setting up button that reopens the flow at the first step you have not settled, and says what is still outstanding. Once everything is configured it reads Run setup again.

Closing the flow is safe. Anything you have typed is saved as you leave — the same fill-only rule finishing uses, so an empty field never clears a key you already had — and the flow is marked *deferred*, not finished, so it stays on offer. It will not pop up by itself again.

Entering a key does not disqualify you from the brand half, or the other way round — they are one flow. The deeper Brand Setup Wizard (read a client's website, draft the brief, file the product facts) is still separate, and is offered from the Agent tab and from the first-run card.

Getting back here

Reopen this Guide from the ? button in the top bar at any time. Run setup wizard again at the bottom of this sidebar does the same thing as Start's button, and it never overwrites a key you've already entered.

From nothing to a finished video

This is the path the app opens on, and it needs no API key and no audio file of your own.

1. You are already on the Start tab — it is where Orb Studio opens.
2. Type a sentence into the box under 'Make your first orb video'.
3. Pick a voice from the dropdown beside it. It already defaults to one of the seventeen offline voices that ship with the app — they run on this computer, need no key and no account. See Local voices.
4. Click Speak it. The orb's narration appears as a small audio player underneath, so you can hear it before committing to a render.
5. Click Render orb video, 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.

Speak it and Render orb video stay clickable even when something is missing — click either one and the line beside it says what it still needs, rather than leaving you with a greyed-out button and no explanation.

What's set up, and what isn't

Under the hero, Start lists the six things the app can use — Voice, Writing model, Video encoder, Asset library, Brand brief, Music — and says plainly which are ready. Nothing there is required to make the video above; the list exists so you never have to discover a missing key by watching something fail four minutes in.

Each gap carries a button that takes you to the exact control that closes it, and scrolls it into view. Come back to Start afterwards and the row flips to Ready.

The chip in the top bar reads Free · offline voices until you connect a Voispark account, at which point it shows your plan and remaining credits. It never goes blank: no account is a state, not an error.

Pick up where you left off

Under the hero, Start shows a card for each thing you already have — a recording profile, a stocked asset library. Each card opens the *lane* that works, not just the tab it lives in, so a card never lands you on a screen you cannot act on. On a fresh install there are no cards yet; they appear as you make things.

Already have an audio file?

Then Studio is the shorter route: drop an MP3 or WAV onto the window, click the wand icon for Auto-configure orb (it shapes color, motion and sensitivity to match the audio), adjust anything you like in the inspector, and click Render MP4. See Studio.

Want the narration written for you as well as spoken?

See Agent, which researches, writes, voices and renders clips 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.

Where to check what you have

The Start tab's "What's set up" list is the single answer: one row per capability (Voice, Writing model, Video encoder, Asset library, Brand brief, Music), each either Ready or carrying a button that opens the setting that fixes it.

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.

Half-configured installs

Having one key does not mean the app thinks you are done. Voice, writing and music are tracked separately: an install with a Voispark key but no writing model still shows the writing gap on Start, and still offers the Writing step. Only an install with all three is treated as fully set up — which is why an existing machine is never nagged to "set up" what already works.

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.

Takes are saved as you record them

Every take is written to disk the moment you stop recording and registered in your asset library, so it survives a reload — including the reload that happens when you switch brands. Each row says Saved once it is on disk.

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.

Ending with a file

The polish sheet offers two endings: Export MP4 now hands you a finished file straight away, and Compose into Editor opens an editable project instead — which it tells you, so "where is my video?" never comes up. Both name what they produced, with a Reveal button.

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.

Ask for it in plain words

The Content Agent is the chat on Start. It runs Orb Studio for you, using the same tools Claude uses when it is connected. You don't need Claude: it works with the writing model you set in Agent → API providers. It has three modes — Create, Research and Assets — and you can steer it precisely with / presets, @ agents and # skills: see Presets, researchers and skills.

• Commercials. "Make a 60-second product spot", "Make the music more hip-hop", "Re-voice line w4". See Commercials with the Content Agent.
• Demo videos. "Make a demo of the form builder." The reliable way is to record yourself clicking through the product. The agent then writes and voices a narration, trims the dead air and exports the video. It can also record a demo by itself from a goal and a website.
• Editing. "Make my latest project vertical", "Cut every pause longer than a second", "Export it".
• Your library. It can find clips, cut a long recording into tagged clips, rename and describe assets, and import a file.
• Brands and websites. It can switch brand, create one, study a product's website, or tell you what it knows about one.
• Voice and music. It can voice a script, free on this Mac or with a cloud voice, and generate, analyse or audition music.

You approve anything that costs or records

Anything that spends credits or quota, or records your screen, appears as a Needs your OK card. The card says what will happen and what it may cost. Nothing runs until you click Do it, and Not now means it doesn't run at all. The agent can never approve for you.

See what it is doing

• Each reply lists the tools it used, with a tick, or a red mark and the reason if one failed.
• Long work runs in the background with its own card: what it is doing and for how long. When it finishes, the card shows what it made: a video plays right there, and every file has Open and Show in Finder. The agent takes the next step on its own, for example export after composing.
• The Work panel (the Work button above the chat) lists everything in one place: Needs you, Working on, Failed or stopped, and Done. The badge beside it tells you, from any tab, when something needs you or failed.
• Log, on every card and Work row, shows what happened in order: each stage, what it spent, and the exact reason anything failed. Copy puts it on your clipboard.
• When something fails, its card says why in one sentence, with Try again. If Orb Studio closed while something was running, it says Stopped part-way: a commercial offers Continue, which keeps everything already finished, and any other job offers Try again.

Several chats at once

Every conversation is kept. The chat's name at the top left opens your chats: the newest first, each with its last message.

• New chat (the + button) starts a fresh chat. The one you were in stays in the list, and anything it was doing keeps going.
• Chats run on their own. Start a commercial in one chat, then switch and research in another. Results always land in the chat that asked for them. The chat button shows a dot when another chat has news, and the list shows which chats are working and how many new messages each has.
• Rename or delete a chat with the buttons on its row. Deleting removes the conversation from the list; the videos, Board items and files it made stay.

Where the results go

Finished videos land in your Renders tab, including delivered commercials, labelled with where they came from. Voiceovers, music and asset packs go into a dated folder under Content Agent in your renders folder.

Claude is optional. To drive Orb Studio from Claude instead, turn on Local agent control and click Connect Claude in Settings. It is the same toolbox either way.

Three modes

The Content Agent on Start has three modes, switched at the top of the chat:

• Create — make videos from presets and from what you have built in the chat.
• Research — trends, competitors, outages, and what works on each platform.
• Assets — scripts, hooks, posts, images, thumbnails, charts, graphics, music and voiceovers.

An empty chat shows that mode's launchpad; the Launchpad button opens it any time.

Type / for a preset

A preset is a type (what the video is for) and a style (how it looks, sounds and talks). Pick one with / — type a few words like "launch hype" — or click a card in the Create launchpad.

• Explain & educate — Product Explainer, Feature Deep-Dive, How-To Tutorial, Data Story.
• Launch & update — Launch Announcement, Product Update, Teaser.
• Compete & convert — Head-to-Head Comparison, Rapid Response, Myth vs Fact, Use-Case Story.
• Social & trends — Scroll-Stopper Ad, Trend Reaction, Point of View.

Styles: Cinematic, Kinetic Type, Clean Minimal, Bold Challenger, Native / Creator, Founder Voice, Data-Driven, Playful, Documentary and Hype Launch. Each sets the writing, the narrator's delivery and the music.

A preset picks the right engine. A 16:9 product film is cut from your real footage by the Commercial Producer. A vertical or square short is a motion video with the orb, kinetic captions and charts. A tutorial is recorded once by you and narrated for you.

The agent turns your ask into a video brief card: the type and style, length, platform, audience, hook, key messages, call to action, music and voice. Edit anything, then click Start production. The card says what starting will spend. Save as preset keeps your settings as your own preset, ready under /.

A comparison names a competitor only with sourced facts from a competitor brief. A Rapid Response acknowledges what happened with empathy and never claims you never fail.

Type @ for an agent

Pull in a specialist with @: Producer, Trend Scout, LinkedIn, X, Instagram and TikTok researchers, Competitive Analyst, Copywriter, Creative Director, Art Director, Composer, Voice Director, Growth Strategist and Editor.

One agent takes the turn. Name two or more and they work as a team: each does its own part, then the first one named pulls it into one answer. Click As a team in the composer to make them work separately instead.

Type # for a skill

Skills reach a part of the studio directly: #script, #hooks, #post, #storyboard, #brief, #image, #thumbnail, #graphic, #graph (a chart), #music, #voice, #trends, #outages, #platform, #competitor and #market.

• Writing skills run at once.
• Images, music and cloud voices open a card that shows the cost. Nothing is spent until you click.
• Charts and graphics are drawn in the app in your brand colours, and saved to your library.

Research

The researchers start from your market profile: your verticals, ideal customers and competitors. If it is empty, the Research launchpad drafts one from your brand brief and website for you to edit and save.

• Trend Scout reads the news, Hacker News, Reddit, live web research and your competitors' status pages. It posts signals with their sources and how fresh they are, plus video ideas with a preset. Make it turns an idea into a brief.
• Outages — while Orb Studio is open, your competitors' public status pages are checked every 20 minutes, for free. A new incident posts an alert with Draft a rapid response.
• Platform researchers (LinkedIn, X, Instagram, TikTok) find what earns engagement with your ideal customers now: topics, formats, hooks, hashtags and who to watch. These platforms give the app no API, so the live part is cited web research, and the card says so.
• Competitive Analyst writes a sourced brief on a competitor for comparisons and rapid responses.

The Board

Everything made in the chat lands on the Board: hooks, scripts, posts, research, images, charts and music. Pin what the next video should use. Every agent reads pinned items, they ride above the composer as Using, and a video brief picks them up: the chosen hook, the pinned script, the research, a competitor's facts.

When the agent asks first

For a big or unclear ask, like a launch campaign, the agent asks up to four quick questions on a card. It lists its recommended option first. Pick answers, type your own, or click Skip — you decide. For multi-step work it shows its Plan above the reply.

What it makes

A finished product commercial, 30 seconds to 3 minutes, built from your brand's own material: the site Orb Studio studied, the footage in your Asset Library, the brand's Agent voice and its logo. You get a web master (−14 LUFS), a broadcast master (−24 LKFS), a 720p preview and a QA report.

The shape follows the length:

• A minute gets two short chapters. It has no montage, and no captured conversation unless you ask for one.
• 90 seconds or more has room for chapters, the conversation and a montage.

Ask the Content Agent

The Content Agent is the chat on the Start screen. Tell it what you want, for example "Make a 3-minute commercial for ChatWisp, for research teams", and it runs the whole thing in Orb Studio, using the writing model you set in Agent → API providers.

Every commercial is a new one

Each request makes a new piece, not a remake:

• Its own angle, for example one person's moment, before and after, or the other side's point of view.
• Its own title, lines and music direction.
• Checked against your brand's earlier commercials. A draft that repeats them is rewritten before you see it.

The script card shows the angle and the music. Want a particular take? Say so, for example "tell it from the customer's side", and the agent passes it on.

Approve the plan, then watch the finished video

Nothing is spent until you approve the spend plan: Voispark characters for the narration, music generations and model calls. You choose how it goes from there:

• Approve and make it (the usual choice). The agent decides the small things itself and stops at the finished video. It fits the script to the length, keeps a take that came out a little unclear, picks the music, and retries a failed quality check once. Each choice shows as a Decided for you line in the chat.
• Approve — I'll check each step. Every checkpoint waits for your click, as below. Changed your mind? Finish it for me on any of its cards hands the small decisions over from there.

Want to decide things yourself after all, say to pick the music? Click I'll check each step on the commercial's newest card. From then on every stop waits for you again.

Each card's header says who has the step: Making it for you while the agent decides it, Needs you when it waits for your click.

It never decides for you anything that costs more than the plan, which website the commercial is about, or the final cut. Once the finished video is in front of you, it decides nothing more: new music you ask for after the review is yours to pick. It also stops and says why if the same step keeps coming back.

The final review lists what was decided for you, each with its way back: Listen to them plays the other music auditions and Use “…” instead · free swaps one in. You can also re-voice a kept take, which costs narration credits, or See what was cut.

Checking each step yourself

Each checkpoint arrives as a card in the chat:

• Script. Every line with its on-screen words, the captured conversation if there is one, and whether it fits the length.

- The script is timed against the music before anything is recorded, so a script that runs long is caught before a credit is spent. - To change a line, say so in the chat and apply the proposed change from its card. - The conversation keeps its real words, so you can only cut from it.

• Music. About 60 seconds of each candidate under your actual picture, at the cut's tempo, just as it will be in the commercial. Pick one. If none lines up with the cut exactly, Use the closest tracks · free stretches the nearest ones onto it, and the review notes any beat that lands a little off. Tracks that missed only the exact timing can be heard too with Hear N more close fits · free. New options are generated at the cut's own tempo and use music quota, and a round that made nothing usable is never offered as the main button again.
• Final cut. The preview, the QA checks and both masters, with buttons to open them or show them in Finder.

One thread per commercial

Every card names its commercial, its length and preset, and shows where it is: Script · Voice · Picture · Music · Mix · Check · Ready. Once a step is answered, its card folds to one line saying what was chosen. Click the line to see it again.

Long stages, like narration, rendering and music, run in the background, and the chat shows their progress. The Work panel lists what needs you, with the commercial, its step and the chat it lives in. Open takes you to its card. Something that has waited more than a week can be Set aside: it leaves the count but is never deleted, and Bring back returns it.

When it runs long

If a script runs longer than the commercial, the agent proposes a cut right away, and you apply it with one click.

• What it can cut: single lines, a whole chapter, the montage or the captured conversation.
• What it shows: the new timing, and anything that would be recorded again.
• Cuts cost nothing. Every other line keeps its recording.
• What it never cuts: the lines that say the product's name, the call to action or the turn line at the end of the open. They can only be reworded.

Want a different cut? Say it, for example "keep the analysis chapter, cut the montage and c3 instead". The agent checks your cut against the timing before you apply it. Make it fit on the card asks for a fresh proposal.

Changing it afterwards

Ask in the chat:

• "Swap in audition B" changes the music only. The picture is untouched, down to the byte.
• "Make the music more hip-hop" generates new candidates, which uses music quota, so you confirm it on a card.
• "Drop the sound effects" re-mixes the audio only.
• "Re-voice line w4" or "re-voice the interview" re-renders only the frames that change.

With Claude instead

Claude can drive the same producer: turn on Settings → Local agent control, click Connect Claude, and ask Claude for a commercial. It's the same pipeline, with the same approvals.

What leaves your machine

Video never leaves your machine. By default, the director sends small stills to your LLM provider's vision model so it can frame shots well. They're cropped to the product's own pixels, with no browser bar, support banner or account email. Ask for the local mode to send no images at all. On a Mac, Orb Studio then reads the footage's on-screen text on your machine instead; framing is a little less precise, and on Windows shots are centred without rings. Narration text goes to Voispark and music prompts to VoiSpark Music.

Where the files are

Each commercial is a folder under the brand's commercials folder: the masters and preview are in renders, the auditions in music/auditions, and the QA report and transition contact sheets in qa.

It needs an LLM key (LLM setup), a Voispark key (Voispark setup) and a music key (Music generation setup), plus product footage in the Asset Library.

What it does

The Newsroom checks your market on a schedule and turns what it finds into sourced posts about your product. Its Editions and alerts arrive in the pinned Newsroom chat on the Start screen, and the Today block at the top of Start's side column sums up the morning. Nothing is ever posted for you: you copy a post, then mark it with I posted it.

Levels

• Off: nothing new runs. The free competitor outage watch still checks your competitors' status pages every 20 minutes.
• Free only: a free morning digest of headlines that share words with your product facts (labelled Digest), plus the outage alerts. No model calls.
• Draft: once you approve the plan, the Morning Edition researches the web, shows up to 5 stories and drafts posts for the best 2.

The plan, and your OK

At Draft the Newsroom spends only inside the plan you approve on the plan card: at most 25 web searches and 150 writing calls a week, 8 and 50 a day, 6 of those kept for urgent news. Unattended work never spends before that click, and the chat's model can never approve it.

The plan covers the models it was approved with. If you pick another writing model or research model, or add or remove a research key, drafting waits for your OK again. The Newsroom chat posts the plan card with the reason, the Today block and Settings → Automation say "Drafting is waiting for your OK", and mornings run as the free digest until you approve.

What a click costs

Buttons that spend say so. Draft posts · 1–2 writing calls makes one call, and a second only when the first answer comes back cut off. At Draft, Run it now costs 1 web search and about 4 writing calls; at Off or Free only it runs the free digest. Your own clicks are counted beside the plan and never use it up.

Stories

Stories sit in lanes: Now, Ready, Worth a look, Needs you and Below the line. A story below the line says why it was left there; Bring it back shows it in Worth a look anyway, free. Snooze and Not for us put a story away.

Competitor incidents

The outage watch reads your competitors' own status pages, for free. A new incident becomes an alert card in the Newsroom chat and a story, with Draft a calm post · 1–2 writing calls. Two competitors down at once are two stories.

At Draft, with the plan approved, Rapid Response drafts that calm post for you within a few minutes, from the part of the plan kept for urgent news: at most 2 a day, and one per competitor a day. Ask the Newsroom chat to pause it if you would rather draft them yourself.

Your own routines

Ask in the Newsroom chat, for example: "Every Tuesday morning research survey fatigue and draft a LinkedIn post and a 30 s video." A routine card shows what it will research, what each run costs, how much your weekly plan grows and which of your product facts the topic connects to. Nothing is added until you click Add routine, and that click also approves the plan's new weekly totals. A brand can have up to 8 of its own routines. A routine runs at a set time, every day or on the days you pick (for "every 2 days", pick days of the week instead).

• The chat can pause a routine, also for a set time ("pause it for a week"), and turn back on one that costs nothing. A pause never turns on a routine you switched off. Adding, changing and turning back on a routine that spends are always your click on its card.
• If Orb Studio was closed when a routine was due, the Newsroom chat says so, with Run it now (priced on the button) and Skip.
• A run that finds nothing worth posting says why, and offers Draft an evergreen post on it anyway · 1 writing call.
• When a run would go past this week's plan, nothing runs: the chat shows the run with its cost on the button, and Allow N more this week, which raises this week only.
• Ask for a dry run of a routine: it reads the free sources and does the sums, and spends nothing.

Something shipped?

Something shipped?, in the Newsroom chat's header and the Today block, turns your release notes, or a link to them on your own site, into a drafted post: Draft the posts · 1–2 writing calls, counted with your own clicks. A link on any other site is refused, including another customer's site on a shared host such as vercel.app or github.io.

Make a video from a story

Make 30 s video · free voice · about 14 writing calls · ~6 min makes a short video from a story with the free voice on this Mac. If another video is rendering it waits its turn, and the story says what it waits for ("Queued — after …") with Cancel, which spends nothing. The result lands as Made · review before posting: its checks are shown, but they do not block anything yet. Nothing is posted for you.

While it renders, switching brands offers Stop it and switch, which is never counted as a failed try. Quitting or closing the window asks first: Wait for it quits once the video is done. Restart now for an update waits for it too.

When it runs

Routines run while Orb Studio is open. The Morning Edition runs on weekdays at 07:30. A morning missed while the Mac was asleep or Orb Studio was closed shows in the Today block with Run it now.

On macOS the Newsroom can also keep Orb Studio in the menu bar when you close its window, and open it when you log in. Both are offered on a card, and nothing changes until you confirm. In menu-bar mode, closing the window stops the mic, the camera and any recording, as quitting did; quit from the menu bar's Orb icon. If macOS wants you to allow the login item first, the card says so: System Settings → General → Login Items. A downloaded update installs when you quit from the menu bar, never while the Mac shuts down.

Stopping it

• Pause (Settings → Automation, or the menu bar) stops this brand's routines at once, including one already running.
• Stop all automation in Settings → Automation (the menu bar's Stop all spending) stops every Newsroom routine, every Agent-tab schedule and the automatic site re-study, for every brand, right away. Your own clicks still work.
• The plan card lists what spends outside the plan, such as an Agent-tab schedule that makes videos with no daily limit. Cap it at 2 a day limits your Agent-tab schedules to 2 videos a day; videos you start yourself are not limited.

Notifications

There are no notifications between 22:00 and 07:00, and at most 3 urgent ones per brand a day. Use Send a test in Settings → Automation to check that they reach you. The chat, the badge and the Today block always show the same news. Clicking a notification about another brand switches to that brand, or says why it cannot while something is running.

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.

Settings, without the wall

Agent → Settings opens on Basics — the brief, your research sources, style and length, the active writer, voice, captions and output size. Everything else lives behind Advanced, and the filter box above both reaches inside it: type a word and the setting surfaces, whichever drawer it is in.

While a run is going

A run paused for your approval says so on the panel itself, not only inside the launcher — with a Review now button. Every finished run keeps its script, its settings and, when it wrote one, its publish kit, copyable straight from the run row. A run that failed shows why, in full, in the same place.

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.

Branding

The Brand section of the Agent tab assigns your marks to the three places a video shows them — the corner watermark, the intro card and the end card — each with its own file, animation and background. See Brand marks.

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.

Three places, three marks

Open the Agent tab and switch to Brand. A video shows your brand in three different jobs, and one file is rarely right for all three:

• Corner watermark — small, on screen the whole time. Usually the icon or a compact lockup, not the full horizontal one.
• Intro card — a branded open over the first couple of seconds. Off by default.
• End card — owns the close.

Each slot can take its own file, or say Use the primary mark and follow the one logo you set at the top. Set the primary mark alone and everything behaves like a single logo; override a slot the moment one place needs something different.

Stills, GIFs and video loops

A mark can be a PNG, JPG or WebP, an animated GIF, an animated WebP or APNG, or an MP4/WebM/MOV loop. Animated marks play, and loop for as long as the slot is on screen. Files you pick from disk are copied into the brand, so moving or deleting the original later doesn't un-brand your videos. Anything already in your Asset Library can be assigned straight from there — use that route for video, and for anything over about 12 MB.

What Orb Studio reads out of your logo

Every mark is analyzed when you assign it, and the result drives the rest:

• Polarity — a light mark is staged on a deep wash of its own color; a dark mark gets a high-key tint of it. The end card background is derived from the logo, so it complements the mark instead of fighting it.
• A baked-in background — a logo exported on a solid white (or any flat) background is detected. On the cards that color becomes the card, so the mark never reads as a pasted-on rectangle. In the corner it is keyed out instead, because a white box over live footage is always wrong. You can override either choice.
• Dead margin — a mark with a lot of empty canvas is measured by its ink, so "size" means the size you actually see.
• Colors — the palette is read from the mark. Let the logo's colors lead the video palette raises how far headlines, chart accents and glows drift toward them. At 0 nothing changes; the orb itself is never restyled.
• Contrast — the mark is scored against the background it will sit on. Below about 2.6:1 a contrast plate is drawn behind it automatically.

Notes appear under each slot when a file will cause trouble — a 10:1 lockup used as a corner watermark, a 64px source on a 4K card, no transparency and nothing to key.

Animation

The watermark can hold still, fade, slide in, spring in, breathe, catch a periodic sheen, or pulse on scene changes. The cards can fade up, rise and settle, spring in, push in slowly, take a light sweep across the mark, use the orbiting-arc classic, or split-reveal from the centre line. Position, size, opacity, edge margin and the moment the watermark arrives are all yours.

The preview is the render

Each slot shows a live preview that runs the same painters, over the same media, with the same analysis as the finished video — including your animated GIF actually animating. Switch it between 16:9, 9:16 and 1:1 to check corner placement in each aspect. If the preview looks right, the video is right.

What the Agent is told

The Agent's art director is told which corner the watermark occupies (so it stops staging stats and chart labels underneath it), how long the cards own the head and tail (so no visual is scheduled where a card will cover it), and that the end card already signs off (so the closing line doesn't repeat it). The thumbnail is taken after the intro card, never of it.

Long-form and re-renders

In the long-form AI producer, the intro card plays once at the top and the end card once at the bottom, however many chapters sit in between. Re-render on a past run picks up your current brand marks, so fixing the branding and re-rendering is a valid workflow.

Upgrading from an earlier version: your existing logo becomes the primary mark and every slot inherits it, so nothing has to be set up twice.

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.

Describe what you add

This is the one rule that makes the library work. The Content Agent casts footage from your descriptions — an undescribed clip reaches it as literally "no description", so it either goes unused or lands in the wrong scene.

So imports arrive switched off, and the library asks for a description as soon as they land. You can skip that: the assets stay, badged No description, with a count in the header and a filter chip to find them again. Describing one switches it on.

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.

Two things worth knowing are one click away

Auto-mark sits in the asset drawer's toolbar: point it at a long voiceover recording and it cuts the tour into tagged library clips the Content Agent can cast later. And the hint under the timeline stays put — press ? at any time for all ~35 shortcuts.

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.

Auto-Mark — let the AI do the marking

Save clip's big sibling. Record one long, messy voiceover tour of your product — narrate what's on screen, don't worry about false starts or rambles — drop it on the timeline, select it, and press Auto-mark in the inspector's AI tools. The AI listens to the whole recording, finds every self-contained demonstration, and proposes a clip for each: in and out points snapped into the silences, a name, a description of what's on screen, tags, and a "Use when…" line telling the Agent when to cast it. The mess — retakes, filler, dead air — simply doesn't get a clip.

Review the proposals before anything is cut: edit any field, untick what you don't want, and Create clips. Each one lands in the Asset Library enabled for the Agent, so your next agent-made video can pull real product footage instead of stock. The recording itself is never modified.

Auto-Mark listens with the same local transcription as captions (whisperkit, on your machine — if it's not installed, the app shows the one-line install command) and drafts with your configured LLM provider. With no LLM connected it still splits the recording on silences and lets you write the labels yourself.

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), brand marks 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.

What the key step actually saves

Every provider the key step offers is carried into the new brand: Straico, OpenRouter, Anthropic, OpenAI and Ollama, each with its model setting. Copy from… brings across all of them, not just the one currently in use, so provider fallback still has somewhere to go. Ollama needs no key — choosing it enables the local runtime for the new brand, along with its server address and model.

The brand can only be pinned to a provider it can actually reach. If you pick a provider but leave its key blank, the new brand starts on the app's shipped default instead of being locked to something that would fail on its first run. Template only is the exception — it needs no key by design, so it is always a valid choice. Check a new brand's provider in Agent → Settings if you're not sure which one it landed on.

Builds before 3.9.0 dropped OpenAI and Ollama credentials here: a brand created on either was written out pinned to that provider with no key, and only said so minutes into its first run. If you created a brand that way, open Agent → Settings and re-enter its key — the brand itself is fine.

Switching brands

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

Backing up and moving a brand

A brand can travel to another computer as a single .zip — Mac to Windows, Windows to Mac, or the same kind of machine. Use Back up this brand… in the brand menu (top bar), or Back up… beside any brand in Settings → Brands. You choose where the file is saved.

The backup holds everything stored for that brand:

• The asset library's media, including the clips the agent uses, and your recordings
• The Agent's knowledge base and the sites it has studied
• Chats and the Board
• Presets and the market profile
• Newsroom routines and stories
• Commercial projects, with the voice and music you already paid for
• Brand marks, and the brand's own settings

What it leaves behind: completed videos (they stay where they are, on this computer), Demo Browser sign-ins, and app-wide settings such as the output folder. Recordings and the re-render cache can be left out to make the file smaller.

API keys only travel if you ask. Turn on Include API keys and set a password: the keys are encrypted with it and never written in plain text. You can also include this computer's Voispark and music keys. Without a password, no keys go at all, and you enter them on the new computer in Agent → API providers (see LLM (writing) setup).

Restoring on the new computer

1. Click New brand…, then Build from recovery… at the top of the first step. On a fresh install, the first-run setup has a link to the same place.
2. Drop the .zip onto the window, or choose it. Orb Studio checks every file in it before showing you anything.
3. Review what's coming back: the name and colour (both editable), the brief, voice, writer and every part of the library. If the backup carries keys, enter its password to bring them across — or skip that and add keys later.
4. Press Restore brand. It always becomes a new brand; nothing you already have is changed.

Nothing spends on the new computer until you say so: scheduled jobs come back paused, the Newsroom's weekly plan asks for your approval again, Make it for me is off on commercials, and studied websites wait three days before refreshing. Commercials re-render there for free — the paid voice and music came with the backup. A hidden orb comes back only if that computer has its unlock code.

Many brands from another agent (Hermes, Claude)

With Settings → Local agent control on, an outside AI agent can run your brands for you through the same API: create a configured brand (brief, voice, delivery style, market profile, keys copied from a brand you name — keys never pass through the agent), save repeatable presets per brand, start videos, talk to the chat and follow the Newsroom. Anything that spends waits for your yes, and the Newsroom's plan, level, routines and kill switch stay your clicks.

For Hermes Agent, download the skills and documentation bundle from orbstudio.space↗ — eleven skills, a full manual and an install script. Everything it does, you can still do here without it.

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.

Voices without an account

Seventeen voices run entirely on this computer: sixteen studio voices (the Kokoro model — American and British, female and male) plus Swift, an instant draft voice (Piper). No API key, no account, no credits, no internet after the one-time download.

They appear in every speaking picker — the Start hero, the Voice Lab's "Avatar speaks", the Agent's narration — and the picker defaults to one when no Voispark key is set. The first-run setup flow offers them on its Voice step, beside Voispark.

They do not appear in the Voice Lab's voice-changer grid, and that is deliberate rather than an oversight: changing the voice of an existing recording is a different operation from speaking a script, and the local engine only does the second. If the Agent ever voices a run with a local voice because no cloud voice was available, the run row says so with a Local voice fallback chip.

The one-time download

The first time a local voice speaks, the app downloads the speech engine and the voice pack (about 175 MB total) into its own data folder and verifies both. After that, everything works with the network unplugged. You can also grab the download ahead of time in Settings → Local voices.

What to expect

• Heart is the strongest local voice — it's the default. Bella, Nicole and Emma are close behind; each voice's description carries its quality grade.
• Studio voices render slower than cloud ones on older machines — roughly the length of the clip again on a recent laptop. Swift is near-instant everywhere and is the right pick for quick drafts.
• Local voices speak scripts; they can't do Voice Lab's voice *changing* — that still needs a Voispark voice.
• The expression sliders (stability, style) are Voispark features; on local voices only speed applies.

Removing them

Everything lives in one folder inside the app's data directory (the size shows in Settings → Local voices). Deleting that folder uninstalls the voices; the next use would simply download them again.

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.

• oMLX — omlx.ai↗. Local MLX models on an Apple silicon Mac: private, free, works offline. An alternative to Ollama.

The four cloud providers use plain API-key auth — no OAuth — so a copied key pastes straight in. Ollama and oMLX need no key (oMLX only if you set its server to require one).

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.

oMLX — local on Apple silicon

Install oMLX from omlx.ai↗ (or Homebrew), download a model in its dashboard, then in Agent → Settings → API providers flip Use oMLX on and click Test connection — it lists the models your oMLX server offers. Leave the model field empty to use the first one, or paste a model id from the list. The base URL is http://127.0.0.1:8000 unless you changed oMLX's port. If you set an API key in oMLX, paste the same key in API key (optional). To make it the default writer, pick oMLX as the Active writer.

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 (oMLX, then Ollama last, as the local safety nets), 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.

"… can't start yet — the writing model is not set up"

This is the app refusing before it spends anything, not a failure. An action that needs a writer — an Agent run, queue planning, the Producer, a post, Full auto, a site study — checks first and stops with the reason, rather than starting and dying several minutes later.

Two things count as a working writer: a provider with a key, or Ollama or oMLX switched on (local, keyless). Picking template is the explicit "no model" choice and never counts, even if another provider has a key — the template writer produces placeholder text, so an action that needs real writing refuses instead.

The Start tab's "What's set up" list shows the same verdict, with a button straight to the setting that fixes it.

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.

"Take me there"

When a message names a place in the app — *"Agent → API providers"*, *"Settings → Local voices"* — it now carries a button that goes there and scrolls the exact control into view, marking it for a moment so you can see which one it meant. You never have to go hunting for a setting a message mentioned.

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.

What this is

Orb Studio sends itself a small, anonymous count of which features get used — not what you actually create. It's on by default; turn it off any time in Settings → Privacy — usage analytics.

Exactly what gets sent

A random install id, generated on this computer and never linked to your name, email, or any account (Orb Studio has no account system — see Bring your own keys). Alongside it, each time one of these finishes:

• An Agent, Producer, or Demo Studio video finishes rendering
• A manual Studio/Record recording finishes
• A Live camera session ends
• A Voice Lab transform completes
• An Editor export finishes
• A Post is generated

— just the fact that it happened, plus the app version and your OS (macOS/Windows). That is the complete list. If it ever grows, this article grows with it.

What never gets sent

No filenames, project or brand names, scripts, transcripts, thumbnails, video frames, or any other content — nothing about what's actually in a video or post, only that one got made. No IP address is stored server-side.

If a claim in Does my audio or my keys leave my machine? and this article ever seem to disagree, this article is the accurate one for usage data specifically — that FAQ answer is about API keys and audio going to the providers you configure, which is a separate thing from this.

Offline behavior

Events are written to this computer first and sent in the background whenever the app is online — nothing about producing a video or recording ever waits on the network for this. If you're offline for a long stretch, only your most recent activity is kept once the local queue fills up; older queued events are dropped rather than kept forever.

Turning it off

Settings → Privacy — usage analytics → Share anonymous usage data. Turning it off stops recording immediately and clears anything still queued locally that had not sent yet — nothing left over sneaks out afterward.

Why we collect this

To see which features are actually worth building on next, instead of guessing — total installs, which modes get used and how often, and how many videos get made via the Agent versus filmed manually.

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 for those, and nothing is sent at all for features with no key configured. Separately, Orb Studio also reports anonymous usage counts (which features ran, not what you made) — on by default, can be turned off — see Usage data for the exact, complete list.

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.