Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
docs: captions, translation and transcription over MCP and in the CLI
EtienneLescot733a6a4f43b0
diff --git a/skills/openscreen-demo/SKILL.md b/skills/openscreen-demo/SKILL.mdindex 3918a420b..073270e0b 100644--- a/skills/openscreen-demo/SKILL.md+++ b/skills/openscreen-demo/SKILL.md@@ -88,6 +88,12 @@ Use the document tools, always with the `projectId`. Read the project first with- **Hide what is private:** an email address, a token or a name that shows on screen gets `addAnnotation` with `type: "blur"` over the span it is visible. Its x, y, width and height are percent of the recording's picture, not of the frame, so it stays on what it hides when a zoom moves the picture. Check it with `getFrames`.- **Music or a voiceover:** `importMedia` with the file's absolute path adds it to the project's media, then `addAudio` plays it over a span. `removeMedia` takes back a file the timeline no longer uses.- **Name:** `setProjectInfo` renames the project, if the `title` given to `stopRecording` no longer fits.+- **Captions, for a narrated take** (recorded with `microphone`):+ 1. `transcribe` with the `projectId`. Whisper runs on this machine and can take a minute; a take has no transcript before this.+ 2. `setCaptionSettings` with `enabled: true` and a `style`, plus `anchorV`, `insetY` or `maxWordsPerLine` if the callouts need room.+ 3. To caption in another language: `getCaptionTranslationUnits` with the `language`, translate each unit yourself as a whole phrase, store them with `putCaptionTranslation`, then `setCaptionSettings` with that `language`.+ 4. `getCaptions` reads it all back. The export burns the captions in.+ A misheard name is fixed with `setWordText` (or `setVocabulary`, then `transcribe` again with the `language`), a flubbed phrase cut with `getTranscriptWords` and `removeWords`.- **Undo:** `restoreCheckpoint` with the `checkpointId` takes the project back to the raw take in one step. It also puts back the take's own pointer track, undoing any `setPointerTrack` made since.- **Open in the app:** while OpenScreen is running, your edits go through it, so a project the user has open in its editor changes there live and they can undo each edit. If an edit is refused as "open in the OpenScreen editor", the app did not answer: retry once, then ask the user to close the project there or restart OpenScreen.@@ -137,5 +143,6 @@ Only to a pull request the user asked for a video on, or one you open for them i- **`The recording did not start`:** the window title did not match, or capture is not permitted. Check `listSources` and the permissions in step 1.- **Recording, exporting or an edit refused, naming *MCP edits*:** you are connected to the server in the app, which records, exports and edits only once the user allows it. Ask them to turn on *MCP edits* under *AI settings* → *MCP server*.- **No cursor in the video:** the app was driven by a script. See step 4.+- **`transcribe` fails with `no-audio`:** the take was recorded with neither `microphone` nor `systemAudio`. Record again with one of them.- **No zoom on an early click:** the first 2.5 s stay wide on purpose. Start the first action after that.- **`unknown flag: --attach`:** `gh` is older than 2.99.0. See step 8.diff --git a/technical-documentation/architecture/mcp-server.md b/technical-documentation/architecture/mcp-server.mdindex e8ebb85f1..18425581b 100644--- a/technical-documentation/architecture/mcp-server.md+++ b/technical-documentation/architecture/mcp-server.md@@ -12,7 +12,7 @@ The same tools are served over two transports, by two different processes:| Edits, recording, export | Off until the user turns on **MCP edits** | Always allowed || Project open in the editor | Edited live through the editor, one undo step per call | The same while the app runs: the call is forwarded to it. With no app answering, refused ([the marker](#the-open-in-editor-marker)) || Other projects | Read from and saved to their file, a checkpoint first | Same |-| Tools | `listProjects`, the agent's tools, the project tools (`setProjectInfo`, `importMedia`, `removeMedia`), the checkpoint tools, and the media tools: `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo`, `getFrames`, `createProject` | The same |+| Tools | `listProjects`, the agent's tools, `transcribe`, the project tools (`setProjectInfo`, `importMedia`, `removeMedia`), the checkpoint tools, and the media tools: `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo`, `getFrames`, `createProject` | The same || A take | Recorded by the app's recording bar, as its Record button records; the editor opens it ([below](#the-media-tools)) | Recorded by a hidden runner of its own process, and made a project there || Checkpoints | In the app's memory, shared with forwarded `openscreen mcp` calls, lost when the app quits | In the app's while it runs; otherwise in this process's, lost when it exits, which it does when the client disconnects |@@ -29,16 +29,18 @@ The same tools are served over two transports, by two different processes:| [`electron/mcp/app-channel.ts`](../../electron/mcp/app-channel.ts) | The local channel `openscreen mcp` forwards its document calls through to the running app. See [`openscreen mcp` and the running app](#openscreen-mcp-and-the-running-app). || [`electron/mcp/mcp-controller.ts`](../../electron/mcp/mcp-controller.ts) | In-app server lifecycle: start when enabled, restart on a port or token change, status for the settings UI. || [`electron/mcp/mcp-settings-store.ts`](../../electron/mcp/mcp-settings-store.ts) | `mcp-server.json` (enabled, port, allowEdits) and `mcp-token.enc` (bearer token, `safeStorage`). |-| [`src/lib/ai-edition/store/mcpDocumentHost.ts`](../../src/lib/ai-edition/store/mcpDocumentHost.ts) | Renderer side: answers snapshot / apply requests from the project store. Mounted by `NewEditorShell`. |+| [`src/lib/ai-edition/store/mcpDocumentHost.ts`](../../src/lib/ai-edition/store/mcpDocumentHost.ts) | Renderer side: answers snapshot / apply requests from the project store, and transcribe requests through the editor's transcription queue. Mounted by `NewEditorShell`. |+| [`electron/ai-edition/caption-tools.ts`](../../electron/ai-edition/caption-tools.ts) | The caption and vocabulary tools, routed there by `executeAgentTool`. || [`src/components/ai-edition/McpServerSettings.tsx`](../../src/components/ai-edition/McpServerSettings.tsx) | The settings section: server toggle, the **MCP edits** toggle, port, token, copyable `claude mcp add` / `codex mcp add` commands. |## One tool surface, two agentsNothing about the tools is reimplemented. The server registers `TOOL_ARG_SCHEMAS` (names and zod schemas) and `TOOL_DESCRIPTIONS`, and builds its `instructions` around `buildSystemPrompt`, all exported from [`deep-agent/service.ts`](../../electron/ai-edition/deep-agent/service.ts), where `buildTools` builds the in-app agent from the same table. Every call goes through `runDocumentTool`, the function the in-app agent's `documentTool` also calls: the cursor-telemetry read the zoom tools need (for `addAutoZooms`, the timeline wand's plan, `collectAutoZoomSuggestionsForDocument`, over every take on the timeline), then `executeAgentTool`.-So a tool added to the agent appears over MCP with no further work, and the MCP test asserts the listed tools equal `listProjects`, then `OPENSCREEN_TOOL_NAMES`, then the three project tools, then the two checkpoint tools, then the [media tools](#the-media-tools). What the server adds:+So a tool added to the agent appears over MCP with no further work, and the MCP test asserts the listed tools equal `listProjects`, then `OPENSCREEN_TOOL_NAMES`, then the three project tools, then the two checkpoint tools, then the [media tools](#the-media-tools). The caption tools are agent tools like the others (`getCaptions`, `setCaptionSettings`, `getCaptionTranslationUnits`, `putCaptionTranslation`, `removeCaptionTranslation`, `setVocabulary`): the caller translates the captions with its own model and stores them with `putCaptionTranslation`, so neither agent needs the app's provider for it. What the server adds:- **`listProjects`**, a tool of its own: every project's id, title, `updatedAt`, asset count, and `open` for the one in an editor (this process's, or the app's seen through the marker).+- **`transcribe`**, registered where `McpToolDeps.transcribe` is wired (both transports, by `registerIpcHandlers`), see [Transcription](#transcription).- **An optional `projectId` on every agent tool and both checkpoint tools**, added to its schema with `.extend()` at registration and stripped again before the call reaches the executor, which never sees it. See [Which project a call acts on](#which-project-a-call-acts-on).- **`createCheckpoint` / `restoreCheckpoint`**, see [Checkpoints](#checkpoints).- **The project tools**, see [The project and its media](#the-project-and-its-media).@@ -124,7 +126,7 @@ A client chains several edits in one turn, and each is its own undo step, so rev- **A project that is not open cannot be edited without one.** Ctrl+Z cannot reach an edit to it, so a write there is refused until a checkpoint of that project is in memory, and the client is told to call `createCheckpoint` first. Over stdio that is every project. `stopRecording` creates one for each new take and returns its id.- **They cover the cursor sidecar.** `setPointerTrack` rewrites `<video>.cursor.json`. Before the runner writes a sidecar, it keeps the file's previous content (or its absence) in every checkpoint of that project that has none for it yet; a restore writes those back, and deletes a sidecar the take never had. A restore is itself such a write, so each checkpoint gets back its own state whatever order they are restored in.- A restore is a write: refused while **MCP edits** is off, and refused when the checkpoint belongs to another project than the one the call acts on. That message names the checkpoint's `projectId`: restoring a closed project's checkpoint takes it explicitly.-- It discards every edit since the checkpoint, the user's included. The tool description says so.+- It discards every edit since the checkpoint, the user's included. The tool description says so. A transcript an asset gained since the checkpoint is kept, where the checkpoint had none for it: it is the media read, not an edit (`keepTranscriptsMadeSince`).- **Lifetime.** Checkpoints live in the runner's memory, the 20 most recent. In the app that is one runner (`createToolRunner`, built in `registerIpcHandlers`), shared by the in-app server and every forwarded `openscreen mcp` call; a restart of the in-app server keeps them, and they are lost when the app quits. An `openscreen mcp` with no app answering keeps its own, lost when the process exits, which it does when the client disconnects. The unknown-checkpoint message says which. The in-app agent does not need them: its whole turn is a single apply.## The project and its media@@ -137,6 +139,18 @@ Three tools of the runner's own ([`project-tools.ts`](../../electron/mcp/project**Deleting a project is left out on purpose.** It cannot be undone, no checkpoint holds a deleted file, and nothing an agent makes needs it. The user deletes projects in the app.+## Transcription++`transcribe` runs the on-device Whisper on one asset and stores its transcript, which `getTranscriptWords`, `removeWords` and the captions read. A take from `stopRecording` has none until it runs; the editor makes one on its own when it opens a project.++- **Outside the queue.** Whisper takes minutes, so the runner does not hold its queue for it: other calls go on, and only the landing is queued, as a `RunnerEdit` on the project as it is by then (`applyTranscriptionResult`: the transcript replaced, the word corrections that still match carried over, a remembered failure cleared, as the editor's queue lands one).+- **The project open in an editor of this process** goes to that editor's own queue (`McpDocumentHost.transcribe` → `ensureTranscript`): a job already queued or running for the asset is waited for, never doubled. The host waits up to an hour, and answers at once when the editor goes away.+- **Any other project** runs `SttManager.transcribe` in this process with the asset's path and the project's vocabulary as Whisper's prompt, one MCP transcription at a time. No runner window is needed: the engine and its ffmpeg decode already live in the main process. The renderer's own decode, the editor's fallback for an install with no ffmpeg, is not available there.+- **Without `language`** a transcript already there is returned unchanged; with one (or `auto`) the asset is transcribed again.+- **Failures** are classified as the editor classifies them (`classifyTranscriptionError`), and a deterministic one (no audio, unreadable codec) is remembered on the asset (`withTranscriptionFailure`).+- **No checkpoint is needed** on a closed project, since `restoreCheckpoint` keeps the transcript anyway.+- **Forwarded** from `openscreen mcp` to the app like every tool, with a 65-minute timeout instead of 90 s, and never run again locally after a lost answer. With no app, `openscreen mcp` transcribes in its own process and stops the Whisper helper before it exits.+## The media tools`createMediaTools` builds the tools that make a video around the edits, once per server, and `createOpenScreenMcpServer` registers them. Both servers serve the same seven, from the same code. Their state (the take running, the export running, each take's start time, each project's last export) lives in what `createMediaTools` returns, so the in-app server, which builds a fresh `McpServer` per request, keeps it across requests and across a restart of its port. They share the runner the document tools use: the app's one runner in the app, the routed one of `stdio-server.ts` over stdio, so their document calls go to the app while it runs.@@ -167,7 +181,7 @@ The stdio server (`openscreen mcp`, [`stdio-server.ts`](../../electron/mcp/stdio- **Discovery.** Once listening, the app writes `<userData>/mcp-app.json` (`{ pid, endpoint, token }`, mode 0600) and removes it as it quits. `openscreen mcp` shares that userData and reads the file on each call it is not connected for: the app starting or quitting mid-session is picked up on the next call. A file whose pid is dead, or whose endpoint does not answer within 3 s, is a crashed app's and is ignored.- **Trust.** Every connection must first send the token from that file, or it is dropped. Node cannot set a named pipe's DACL, and the default one lets any user open it read-only; the token, in a file inside the user's profile, is what limits the channel to the current user. Any process of that user can connect, which grants nothing new: it could run `openscreen mcp` itself. So calls over the channel edit as `openscreen mcp` always did, whatever the in-app server's **MCP server** and **MCP edits** switches say: those guard the HTTP port, a door a web page or another tool could knock on.- **Fallback.** With no app, or one that does not answer, the calls run in the CLI process on the files, as before. The project a live app's editor holds is then still refused (#1138): the app's `.open-in-editor.json` marker says so, and the refusal asks to retry, close the project, or restart or update OpenScreen.-- **Never twice.** A call the app received but did not answer within 90 s, or whose connection dropped, is not run again locally unless it is a read: the client is told the outcome is unknown and to re-read. The connection is dropped, so a hung app does not hold later calls.+- **Never twice.** A call the app received but did not answer within 90 s (65 minutes for `transcribe`), or whose connection dropped, is not run again locally unless it is a read: the client is told the outcome is unknown and to re-read. The connection is dropped, so a hung app does not hold later calls.- **Checkpoints do not cross over.** One made while the app answered lives in the app and is gone once it quits; one made while no app was reachable (before the call was sent) lives in the CLI process and is unknown to the app. A `createCheckpoint` the app received but never answered creates none here: it gets the unknown-outcome error like any other write. Either way the restore says the checkpoint is unknown, and an edit to a closed project asks for a new one.## Transport and security@@ -214,3 +228,4 @@ codex mcp add openscreen -- "<executable>" mcp- **An editor that stops answering looks closed.** A snapshot unanswered for 30 s reads as "no project open", so an edit naming the project that editor holds would go to its file, and the editor's next save would drop it. It takes a renderer hung for 30 s.- **No project deletion**, on purpose ([above](#the-project-and-its-media)).- **An imported recording comes without its camera.** The editor's import links the webcam an OpenScreen recording was made with (`find-recording-camera`); `importMedia` and `createProject` do not, so the camera of a recording imported over MCP is not in the project.+- **A transcription reports no progress.** `transcribe` answers once Whisper is done, which can outlast a client's own tool timeout on a long recording. In the app, the editor cancelling its own run (a regenerate in another language) also stops an MCP run of the same engine, which then reports a failure.diff --git a/technical-documentation/architecture/transcription-and-captions.md b/technical-documentation/architecture/transcription-and-captions.mdindex ecd8f90ee..a39171c6d 100644--- a/technical-documentation/architecture/transcription-and-captions.md+++ b/technical-documentation/architecture/transcription-and-captions.md@@ -883,7 +883,8 @@ sync.### Legacy caption annotations-Documents produced by an older "generate captions" flow carry caption text+Documents produced by an older "generate captions" flow, or by+`openscreen captions` before it wrote the transcript, carry caption textas real `annotations[]` entries with `annotationSource === "auto-caption"`([`src/components/ai-edition/CaptionsPane.tsx:96-99`](../../src/components/ai-edition/CaptionsPane.tsx:96)).They would now render *on top of* the derived layer, so the Captions pane@@ -892,6 +893,23 @@ filters them off the document — gated on the user's confirmation, sinceit deletes data([`src/components/ai-edition/CaptionsPane.tsx:154-161`](../../src/components/ai-edition/CaptionsPane.tsx:154)).+### Transcription outside the editor++Two callers run the pipeline with no editor open, and both land the result+as the editor's queue does (`applyTranscriptionResult`, word corrections+carried over):++- **`openscreen captions`** (`src/cli/captionProject.ts`) transcribes the+ primary asset in its runner window through `transcribeAsset` (or keeps the+ transcript the project has), clears the legacy caption annotations and turns+ the captions on with `--min-words` / `--max-words` as `minWordsPerLine` /+ `maxWordsPerLine`. The project is written back in the editor's own format.+- **The MCP `transcribe` tool** calls `SttManager.transcribe` in the main+ process and builds the transcript with the same converter the renderer uses+ (`transcription/fromStt.ts`). On the project an editor holds, it asks that+ editor's queue instead, so a run already under way is waited for. See+ [mcp-server.md](mcp-server.md#transcription).+## Known gaps- **Language selector.** The "Regenerate as" picker offers `"auto"` plusdiff --git a/website/docs/ai-editing.md b/website/docs/ai-editing.mdindex 7e76f2ca9..e5188ac3d 100644--- a/website/docs/ai-editing.md+++ b/website/docs/ai-editing.md@@ -41,7 +41,7 @@ The ChatGPT and GitHub Copilot sign-in options were **removed in 1.8.0**. They w## Using the agent-Describe the edit in plain language — "cut the dead air in the intro", "zoom in when I open the terminal". The agent works through real, undoable timeline operations, not a re-render: it can add and adjust trims, zooms, speed regions, annotations (text, arrows, and blurs that hide private details on screen), imported audio tracks with their fades, and Full Camera segments, add automatic zooms on your clicks, edit a clip's in/out points and crop, place another source's footage, duplicate, reorder or remove clips, and read the transcript to find what you're referring to. It also sets the look of the video: background, padding, rounded corners, shadow, device frame, format, the camera layout, the cursor and the master volume.+Describe the edit in plain language — "cut the dead air in the intro", "zoom in when I open the terminal". The agent works through real, undoable timeline operations, not a re-render: it can add and adjust trims, zooms, speed regions, annotations (text, arrows, and blurs that hide private details on screen), imported audio tracks with their fades, and Full Camera segments, add automatic zooms on your clicks, edit a clip's in/out points and crop, place another source's footage, duplicate, reorder or remove clips, and read the transcript to find what you're referring to. It also sets the look of the video: background, padding, rounded corners, shadow, device frame, format, the camera layout, the cursor and the master volume. It can also turn the [captions](./captions.md) on, style and place them, and translate them into another language itself.The panel around it:@@ -57,7 +57,7 @@ The **Smart cuts** entry (marked *With AI*) in the timeline's auto-enhance menu## What else uses your provider-[Caption translation](./captions.md#translation) is a single text-transform call against the same model — it doesn't run the agent loop and can't touch your document. Transcription and caption rendering stay entirely on-device either way.+[Caption translation](./captions.md#translation) is a single text-transform call against the same model — it doesn't run the agent loop and can't touch your document. Asked in the chat, the agent translates the captions itself instead, into the same translation layer. Transcription and caption rendering stay entirely on-device either way.## Using Claude Code, Codex or another MCP client@@ -67,7 +67,7 @@ If you already use an AI coding agent such as Claude Code or Codex, it can drive2. Copy the **Claude Code** or **Codex** command shown there and run it in a terminal. The Claude Code command carries the access token. Codex reads it from the `OPENSCREEN_MCP_TOKEN` environment variable instead: set that in the shell you start Codex from.3. Ask your agent for the edit, on the project open in the OpenScreen editor or on any other project in your list.-The tools are the ones the built-in agent uses, plus the ones that record, export and look at a video ([below](#letting-an-agent-make-the-whole-video)). They act on the project open in the editor unless the client names another one: it can list every project and read or edit any of them. It can also create a project, empty or from a video file, rename one, and add a video or audio file to a project's media or remove one. Deleting a project is not among the tools: that stays yours to do in the app. MCP clients can only **read** until you also turn on **MCP edits** in the MCP server section: until then every edit, recording, export and new project they try is refused. This switch is separate from the built-in agent's **Agent edits**, and it starts off. Once on, each edit is saved as it lands:+The tools are the ones the built-in agent uses, plus the ones that record, export and look at a video ([below](#letting-an-agent-make-the-whole-video)), and `transcribe`, which runs the on-device Whisper on a project's media as the editor does when it opens a project. A client translates the captions with its own model, so caption translation needs no provider in OpenScreen. The tools act on the project open in the editor unless the client names another one: it can list every project and read or edit any of them. It can also create a project, empty or from a video file, rename one, and add a video or audio file to a project's media or remove one. Deleting a project is not among the tools: that stays yours to do in the app. MCP clients can only **read** until you also turn on **MCP edits** in the MCP server section: until then every edit, recording, export and new project they try is refused. This switch is separate from the built-in agent's **Agent edits**, and it starts off. Once on, each edit is saved as it lands:- **On the project open in the editor**, an edit is undone with `Ctrl/Cmd + Z`. Clients are told to save a checkpoint before a series of edits, so you can ask them to put the project back as it was in a single step, which `Ctrl/Cmd + Z` can itself undo.- **On any other project**, an edit is saved to its file, where `Ctrl/Cmd + Z` cannot reach it. A client must save a checkpoint of that project before its first edit, and putting the project back from it is the only undo.@@ -98,5 +98,6 @@ The executable on each system is listed in [Running the CLI](./cli.md#running-th- **No port, no token, no setting.** The agent starts the process itself, with your rights, as it would run `openscreen record`. So it can record your screen and edit without the **MCP edits** switch.- **Each take becomes a new project** in your project list, zoomed on its clicks as a recording made in the app is: clicks close in time and on screen share one zoom, and the first seconds and the end stay on the whole screen. Every edit the agent makes is saved to the project's file. Its undo is the checkpoint the agent takes, which lasts until the agent's session ends. Only the 20 most recent checkpoints are kept, so an older one can be gone sooner.- **While OpenScreen is running, the agent works through it.** An edit to the project open in the editor appears there at once, and `Ctrl/Cmd + Z` undoes it. The agent's checkpoints then last until OpenScreen quits. If the app does not answer, edits to that project are refused, since the editor would save its own copy over them.+- **A take has no transcript until the agent asks for one.** It calls `transcribe` before it cuts words or turns the captions on. Whisper runs on your machine, in OpenScreen when it is open.- **A take driven by a script** (Playwright, for example) never moves the screen pointer. The agent hands OpenScreen its own log of the actions with `setPointerTrack`, and the video gets a cursor and its zooms all the same.- **The `openscreen-demo` skill** teaches an agent the whole job, from the storyboard to the finished video. It then attaches the video to a pull request, so reviewers watch the change in place, or drafts a post on X that it publishes only once you say yes. Add it with `npx skills add getopenscreen/openscreen --skill openscreen-demo`. The recipe is [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).diff --git a/website/docs/cli.md b/website/docs/cli.mdindex ec375387f..26d0f19c9 100644--- a/website/docs/cli.md+++ b/website/docs/cli.md@@ -157,7 +157,7 @@ MP4 exports from the CLI are always **H.264**, at 60 fps unless `--fps` says oth### `openscreen captions`-Transcribes the project's audio on your machine with Whisper, then writes caption annotations into the project file. Nothing is uploaded, and the language is detected automatically. The first run downloads the Whisper model once, about 264 MB, as the desktop app does.+Transcribes the project's audio on your machine with Whisper, then turns the project's captions on, as the editor's Captions pane does. Nothing is uploaded, and the language is detected automatically. The first run downloads the Whisper model once, about 264 MB, as the desktop app does.```bashopenscreen captions demo.openscreen --min-words 2 --max-words 7@@ -165,7 +165,8 @@ openscreen export demo.openscreen -o demo.mp4 # captions are burned into the v```- `--min-words` and `--max-words` set the words per caption. Each takes 1 to 12, the range the editor offers. Defaults: 2 and 7.-- Running it again replaces the captions it added before. Annotations you added yourself are kept.+- The captions are the transcript drawn on the video, so in the editor you restyle, correct and translate them like any others. Running it again keeps the transcript and only sets the words per caption.+- The project is saved in the editor's own format. A script that edits the project JSON as shown [below](#example-an-automated-product-demo) does it before `captions`, and `pack` does not read that format yet.- The project's screen video must have an audio track, for example from `record --mic`.- Captions are burned into the export. There is no subtitle file output. See [Captions](./captions.md).@@ -241,10 +242,7 @@ A script or a coding agent can produce a captioned, zoomed demo without opening# 1. Record 20 seconds of one window, with narration from the microphoneopenscreen record --window "MyProduct" --mic --duration 20 --project demo.openscreen --json-# 2. Caption the narration on this machine-openscreen captions demo.openscreen --json--# 3. Add a manual zoom and a text label by editing the project JSON+# 2. Add a manual zoom and a text label by editing the project JSONnode -e 'const fs = require("fs");const p = JSON.parse(fs.readFileSync("demo.openscreen", "utf8"));@@ -257,11 +255,14 @@ node -e 'fs.writeFileSync("demo.openscreen", JSON.stringify(p, null, 2));'+# 3. Caption the narration on this machine (this saves the project in the editor's format)+openscreen captions demo.openscreen --json+# 4. Render, with automatic zooms added on the recorded clicksopenscreen export demo.openscreen -o demo.mp4 --auto-zoom --json```-In step 3, `depth` runs from 1 to 6 (1.25× to 5×; 3 is 1.8×), and `cx` and `cy` place the zoom center as fractions of the frame.+In step 2, `depth` runs from 1 to 6 (1.25× to 5×; 3 is 1.8×), and `cx` and `cy` place the zoom center as fractions of the frame.To narrate with a text-to-speech engine instead, record without `--mic` and mix the voiceover in at export. Any engine that writes mp3, wav or m4a works; macOS `say` is shown: