Analysing footage
Why an agent needs footage analysed before it can cut by content, how the app analyses everything in the workspace by itself, what the queue shows, what it costs, and what an agent may ask you.
An agent cannot watch or listen to a video. What it knows about a file beyond its length comes from analysing it once: the analysis service reads the file and writes what it found next to it, and the agent reads that. This page explains why that step is required, what it produces, what it costs in credits, and how it runs. Analysis is part of Pro; on Pro the app analyses every file in the workspace by itself, so the footage is ready before the agent sits down, and you never type a command.
Why it is required
The guide every agent reads has one hard rule: never describe, transcribe, time or cut footage from what you think is in it, from its name, from a frame or two, or from anything you produce yourself. A guess about where a sentence ends is wrong by seconds, and a cut made on it wastes your time. So every fact about a file comes from BetterEdits' own analysis: the agent checks media for where each file stands, waits for the ones still on their way, and reads the result with analysis and transcript before it plans a cut.
Footage that has not been analysed is never refused. It plays, cuts and exports as usual; the agent can still cut it by time and look at its frames with contact-sheet --path. It just cannot cut it by what was said, and it has no words to make captions from.
What analysis writes
Analysing a file sends it to the service once and writes its analysis beside it as a hidden file, .clip.mp4.bettereditsanalysis next to clip.mp4, so your folders look the way you left them (⌘⇧. in Finder shows hidden files). It is plain JSON, readable by anything, and holds:
| Section | What it holds |
|---|---|
| Source | The file's facts: length, size, frame rate, the camera when known |
| Summary | What the footage is, in a few sentences |
| Shots and scenes | Every cut in the footage, with what each scene shows |
| People, actions, moments | Who is on screen and when, what happens, the beats worth cutting to |
| On-screen text | Words that appear in the picture, with their timing |
| Speech | Every spoken word with its start and end, the speaker, the language |
| Silences and music | Where nothing is said, where music plays and its beats |
The agent finds footage with library-search: it asks for what happens or is said, in several wordings, and gets the files and the seconds in them that fit, from an index of these documents the app keeps on your Mac (nothing is uploaded for it, and it costs nothing). It then reads the whole document with analysis, one section with --section, or only a stretch of the file with --from and --to; words and events are left out unless asked for. transcript gives the words of a track's clips mapped to timeline time. The app itself reads only the transcript, and only for one thing: captions-generate cuts it into bars. See Captions.
A file and its document move together: copying a file into a video, consolidating a media folder and Export a Copy… copy the document too. Before 0.5.7 the file was visible and named clip.mp4.analyzemedia (and .smartmedia before that); the app still reads those and renames them to the hidden name as it comes across them. If you move or rename a media file in Finder its hidden analysis stays behind, and the app analyses the file again (free while the service still has its copy). A file that already has a document is never analysed again unless the agent asks for a re-run with reanalyze --force.
It happens by itself
On Pro, every media file that enters the workspace is analysed: the files copied into a video, and every file in a library, now and later. Adding the library is your say-so; removing it stops its analysis. This video's files go first, then the libraries newest first, several at a time. There is no switch. Each tile in Sources wears one small dot: green once the file is analysed, dim when it is not, pulsing while it runs, red when the service refused it (the file is over an hour, say). A file is analysed or not; whether the queue is running, paused or waiting for credits is the queue's state, shown once at the top, never per file. Hover it for the reason. A folder tile carries the same dots with numbers. An account without Pro sees none of this.
The queue, in one pill. The same pill sits in three places: the video window's toolbar, the workspace window's foot beside your account, and a library window's bar. It carries the analysis icon, a dot in the queue's colour and a short label: "Analysing 3 of 12", "Paused · 447", "Counting…" while a big library is still being counted, "All analysed", or "Out of credits" in red. Click it for the queue: what analysis is for, Pause, a line with what runs and what it will cost against your balance, then one row per file in up to three groups. Files that were not analysed come first, each with the reason under its name ("Over 1 hour, split it first") and Retry beside it, with Retry all above them; then the files that run and wait, with their state and their credits; then what finished this session. When something goes wrong that is not the file's doing, the app tries the file again by itself, twice, before it counts as failed, and an update of the app tries every failed file once more. While the app is still counting, the line says "Counting footage · 1,240 of 5,000" rather than a number that keeps changing. Clear finished tidies the done rows; History opens your account's statement. Once nothing waits, the queue says "Everything is analysed", or how many files were not, and the pill says "All analysed" or "3 not analysed" with an orange dot. Right-click a row to show the file in Finder. The Sources sidebar shows the same state in one line at its foot, and the selected file's details show its own dot and state. The agent sees the same queue, so what you read there is what it reads.
Only the open workspace. The queue holds this video's files and the workspace's libraries and nothing else. Closing or switching the workspace, opening another video, or removing a library takes their files out of the queue at once, running ones included.
Pause stops anything new from starting; the files running at that moment finish, since a job the service has accepted is charged when done. Resume takes up where it left off, and the app remembers the pause across launches. An agent can ask to pause or resume, and the app puts the question to you with the agent's name; nothing changes until you answer.
Libraries and your ok. Adding a library asks once: the sheet counts the folder's footage ("142 files, 6 h 12 min of video and sound") and says what analysing it will take and what you have ("1,080 credits, and you have 450") before the folder is added. That is the only question. The app then watches the library, and files that land in it later are analysed as they arrive; Pause is how you stop that, and removing the library stops it for good (the workspace window asks before it does). An agent that wants to add a library asks you the same way, in the app, and the folder is added only if you say so.
In the workspace window each library is a card with its name and its counts as dots with numbers: analysed, not analysed, analysing, failed. Click a card to open the library in its window.
A library in a window. Click its card in the workspace window, or right-click its tile in Sources and choose Open in a Window (or use the ⤢ in the breadcrumb), for the whole library at a size that suits thousands of files: the name, the path and the counts at the top with the queue's pill, a strip with the queue's state, Retry failed and Pause, filter pills with the dots and counts (All, Not analysed, Failed, Analysed), the subfolders with their own counts and a breadcrumb into them, and the files grouped by month newest first with their dots. Click a file for its details on the right: the picture on top, with an Open button on hover that opens it in the app that plays it, its facts and its analysis, and an × to close the pane. Double-click a tile to add it to the timeline, or drag it there.
Out of credits
When the balance runs out, the queue waits rather than fails: the pill's dot turns red and reads "Out of credits", the line reads "Waiting for credits · 3 files need 31, you have 6", and a Buy credits button opens the app's own window. Nothing is lost. The queue goes on by itself once the credits land, and the agent, which sees the same hold, relays the link and carries on with the files that are analysed meanwhile.
What it costs
| Kind of file | Credits |
|---|---|
| Video | 3 a minute of the file |
| Audio | 1 a minute |
| An image | 1 |
Length is the file's, rounded up to the minute, never the part on the timeline. A file is paid for once. The queue shows each file's cost before it runs and the credits left after; the agent reports the same ("take-3.mov (4 min, 12 credits): 612 words (en), 41 s.") and the credits left once everything is done. See Pro.
What goes up: for a video, a small proxy at 480 px on the short side and 10 frames a second with its sound in mono, never the original; for audio, the file itself. Files up to an hour long; longer ones are refused. The copy is deleted when the analysis is done. Editing never uploads anything.
The first time
The first session goes like this:
Cut the pauses longer than a second out of take-3 and caption it.
The agent reads the video and sees that take-3.mov has no words, and that this Mac is not signed in. It runs login, which opens the dashboard in your browser, and asks you to approve the sign-in there. You sign up, start the trial (card on file, nothing charged for seven days), and the page says the Mac is connected. The app starts analysing the footage the moment Pro is on; the agent waits for it, says what it found and what is left on the balance, and cuts.
Signed in but without Pro, the agent's commands answer with the link to start the trial or subscribe; the agent relays it and waits for you to say it is done. The credential stays in the app's own settings, never in a workspace; the dashboard lists every linked Mac. account prints the plan and the balance at any time. See Pro.
Progress
An analysis takes a while: a minute of video well under a minute, an hour-long file up to a quarter of an hour. The queue in the app shows it as it goes. Claude Code shows nothing while a tool runs, so the agent asks analyze-status, which waits up to a minute and answers with where each file stands (waiting, making the upload copy, uploading, analysing, done), and keeps asking until the files it needs are done, telling you how it is going about once a minute. Those lines are the progress bar. Nothing analyses a file outside the workspace: the agent brings it in (media-import copies it into the video, media-folders --add asks you to add its folder as a library) and the app analyses it by itself. reanalyze is for the rare case: a file that failed, or one the service read as the wrong kind of thing.