Workflows

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