# Workflows

> The five jobs agents do most with Brollss, step by step: import a video, edit it end to end, add scenes, add captions and audio, review an edit.

Web page: https://brollss.com/mcp/workflows. All MCP pages: https://brollss.com/llms.txt (index) and https://brollss.com/mcp/llms-full.txt (everything in one file).

Each workflow below is a skill of the plugin. An agent on a bare connection can follow the same steps.

## Import a video from your computer

> Ask: "Import ~/Videos/talk.mp4 into Brollss and tell me when the transcript is ready."

1. Pick one source. A file on the user's device, or a direct link to a media file. A page that plays a video, such as a YouTube page, is not a media file. One file per project.
2. Call `import_media`. For a file, declare it in `add_media`, keyed by its file name: `{"talk.mp4": {"content_type": "video/mp4", "file_size": 734003200}}`, with the exact size in bytes. For a link, pass `url` as the user gave it.
3. `import_media` answers at once with `job_id`, `project_id` and `project_url`. Show `project_url` to the user.
4. For a file, `PUT` its raw bytes to `upload_urls[<file name>].upload_url` with `Content-Type: application/octet-stream`. No form, no encoding, exactly `file_size` bytes. The address works once. If the upload fails, call `report_upload_status` with `status: "failed"`.
5. Call `wait_for_job` with `job_id` and `wait_seconds: 20`, and again until it answers `done: true`. After each call, tell the user `progress.label` and `progress.percent`.
6. An answer with `timed_out: true` means the import is still running. Call `wait_for_job` again on the same `job_id`. Never import again: that makes a second project.
7. When the job is done, read the project with `get_project_state` and tell the user what was created. A project you just imported is the user's own copy: edit it directly.

A refusal for the number of projects or the file size is the limit the Brollss app applies. Say which one and stop. A `path` on the machine works only with a Brollss server running locally; the hosted server refuses it.

## Make a full edit

> Ask: "Make a publishable edit of my latest Brollss project: tighter, a strong hook, scenes where they help, captions and music."

### Before the first write

1. Find the project with `list_projects`. Copies often share a name: tell them apart by `createdAt`. Never guess an id.
2. Unless the user named the project to edit in place, or you imported it in this session, call `clone_project` and work on the copy.
3. Call `get_editing_guide` with the `projectId`: it carries the way of working and the user's standing instructions. Read the style guide that fits the video with `style`.
4. Call `get_project_state` and keep its `editRevision`.
5. Read the whole video before the first cut: `transcript_outline`, then `read_transcript` passage by passage. Word keys such as `12:4` come from these reads.

### The edit

1. **Cuts.** `find_hesitations` lists fillers, repeats and false starts. Cut what stops the flow with `strike_words`, keep the best take of a retake, cut whole tangents. Read the `fallout` of each cut and fix what fell with it. `set_silences` shortens long pauses.
2. **Hook.** Open on the strongest sentence with `move_passage` and no `beforeKey`. Whole sentences, 3 to 15 seconds.
3. **Count the visuals.** `check_edit` and its `rubric` say how many visuals the video lacks and where the longest stretch without one is.
4. **Scenes.** Draw that many new scenes (see [Add scenes](#scenes)), then fix the ones already there.
5. **Zooms.** `add_zoom` on a punchline, held over the whole sentence. When the speaker points at the screen, read the zone on `look_at_source` and pass it as `zone`.
6. **Marks.** Where the speaker says "here" or "this button", `add_marker` circles, underlines or boxes the zone.
7. **Captions, music, sound effects.** See [Captions and audio](#captions-and-audio).
8. **Finish.** `check_edit`, fix what it lists, then `look_at_montage` on every scene and zoom, on the first 5 seconds and on the last 5. Run `check_edit` again.

The edit is finished when the request is met and `check_edit` lists no point, or when each point kept has its reason in one line of the report. Report what changed with montage times, and what was skipped and why.

## Add scenes

> Ask: "Add a scene that shows the three steps the speaker lists at 1:20."

1. Once per session, read `get_scene_contract`: the page rules, the recipes and the grading grid. `get_scene_examples` gives graded example pages.
2. Pick a whole idea, with `fromKey` and `toKey` from the transcript.
3. `list_layouts` for that moment: which layouts hold, and the box of each. `P1` fills the frame, `P9` is transparent over the video, the others keep the speaker beside the scene.
4. `get_scene_brief` gives the beats in seconds, the content box, the face and the measured rules. If `range` says the moment is too short, use the `toKey` it proposes.
5. Write the whole page. No network, GSAP core only, images inline as `data:`. At most 3 MB with images, 600 KB without.
6. `measure_scene` films the page over the real video and lists what is broken, with distances in pixels. Fix everything at once and measure again. Two or three measures make a scene.
7. `insert_scene` with the same arguments and page, then `look_at_montage` at that moment.

To change a scene already there, read it with `get_scene`. `set_scene_text` changes the words of a template, `set_duration` its length, `move_broll` its anchor, `apply_layout` its layout, `set_layout` tunes that layout (the speaker's share and side, where the scene sits, the speaker's card: place, size, shape, angle, framing, how it comes in), `set_broll_pip` puts the speaker in a window over it. A new look is a new page: `measure_scene`, then `insert_scene` with its `brollId`.

## Captions, music and sound effects

> Ask: "Caption the key sentences, put calm music under the voice, and add a whoosh on each scene."

- **Captions.** `get_captions` gives the track, its style and the catalogue. `set_captions` covers the whole video or chosen `ranges`; `add_caption` captions one short passage. A style the user chose stays unless the user asks to change the look (`lookAsked: true`).
- **Music.** `list_music` gives the track ids, `set_music` sets one. Leave `volume` out: the level starts where the app's mixer starts. `duck` sets how much the music drops under the voice: `subtle`, `normal` or `strong`.
- **Sound effects.** `list_sfx` lists the library and what is placed. `add_sfx` rides on the visual on screen at that moment; `remove_sfx` takes one out. One effect per scene entrance or key element.
- **Mix.** `check_audio` measures the music and the effects against the voice, in dB. Music sits well 15 to 25 dB under the voice. Fix what it reports, then run it again.

## Review an edit

> Ask: "Review my Brollss edit and list what to fix before I publish."

1. `get_project_state`: length, cuts, scenes, zooms, captions, music.
2. `check_edit`: the `timeline` (what gets in each other's way), the `scenes` (each scene's pace) and the `rubric` (hook, retakes left, zooms, music), with the visual density as a note, never a point to fix.
3. `check_audio`: the music and the effects against the voice.
4. `look_at_montage` on the first and last 5 seconds, every scene and zoom, and every moment `check_edit` names.
5. Report one line per finding: the montage time, what is wrong, the tool that fixes it. Then the verdict. This review writes nothing.