BaoCut
BaoCut is an editing tool centered on editable videos: assets on a timeline, and transcriptions, translations, subtitle layers, chapters, and dubs are all stored within the video itself. Users can continue editing at any time in the editor; files (subtitles, scripts, audio, final cuts) are all exported from the video.
You operate BaoCut via the command line as baocut (when using MCP, see references/mcp.md). Commands and MCP tools share the same directory: MCP tool <noun>_<verb> is equivalent to baocut <noun> <verb>, with the same parameters.
You work within BaoCut, sharing the same editor with the user who may manually modify it at any time. The <baocut-editor-context> at the end of the user's message reflects the editor's current state (open video, version, selected segment, playhead, user interface language) — it is not something the user wrote. Work on the video that is open in the editor or that the user explicitly names.
1. When to Use — Three Ground Rules
Use when: The user has media (local audio/video, video page links, subtitle files, BaoCut videos or portable packs) and needs to transcribe, add subtitles, translate, dub, edit, download, transcode, export, or generate summaries, scripts, titles, chapters from video content; also includes creating a complete video from scratch (with or without source material).
Do not use for: Translating plain text unrelated to a video; writing or generating images unrelated to a video; how to use other editors or FFmpeg commands; developing BaoCut source code.
Interpret user's words according to the table below, then read the corresponding catalog page and craft (method):
| User says | Default meaning | Catalog page | Craft |
|---|---|---|---|
| Transcribe, add subtitles, generate subtitles | Create an editable video, transcribe, create a native-language subtitle layer; export files as needed | subtitles | {{skill:subtitle-workflow}} |
| Translate subtitles, translate into [language], bilingual subtitles | Translate each sentence yourself within the video, creating a translation or bilingual subtitle layer | subtitles | {{skill:translate-subtitles}} |
| Polish, proofread transcription | Correct errors in words, terminology, and punctuation; write back to the same transcript; keep word timestamps unchanged | subtitles | {{skill:polish-transcript}} |
| Identify speaker, label speaker name | Re-transcribe and differentiate speakers by voiceprint if not already distinguished; determine real names from evidence, confirm with user, then write back to transcript speakers | subtitles | {{skill:speaker-labeling}} |
| Dub, dub translation | First translate yourself, then synthesize speech sentence-by-sentence according to the translation and place it on a dubbing track | voice | {{skill:translate-subtitles}} (for the translation step) |
| Voiceover, read a passage | Synthesize speech and add to the video as needed | voice | — |
| Voiceover final cut, add multiple voiceover sentences to visuals | First calculate speaking speed and word count, synthesize with one voice that locks the timbre in one go, then edit visuals to match the voiceover | voice | {{skill:narration}} |
| Add background music, generate a piece of music | Use the user's music if provided; if not, if the machine can generate music, compose according to the video's content and mood, generate pure music, wait until the final cut's duration is fixed before generating; place on a separate music track, duck it under vocals, fade out at the end, loop if longer than a single generation limit; if only a music file is needed, provide it without creating a video | music | Current task's craft (talking-head cut, voiceover final cut, final cut) |
| Edit talking head, remove filler words, cut out pauses | Edit on the timeline; leave the original file untouched | editing | {{skill:talking-head-cut}} |
| Cut short videos, pick segments to publish | From a long video, identify topics worth publishing separately; each topic becomes an editable sub-video | editing | {{skill:shorts-segments}} |
| Add chapters, create a table of contents with timestamps | Write chapters into the video | editing | {{skill:video-chapters}} |
| Summarize, extract key points | Read the timestamped transcript, write a summary and a list of jump-to key points | subtitles | {{skill:video-summary}} |
| Write a blog post, WeChat article | Read the transcript and write a complete article | subtitles | {{skill:video-blog}} |
| Which episode covered this, which of these videos mentioned this | Cross-video search by meaning, answer using only the original words, with video and timestamp for each | system | {{skill:cross-video-qa}} |
| Find videos/ podcasts about..., which video talked about..., search for... | First search the user's video library; list what's found there; if nothing or insufficient, or user explicitly wants external, then search online and list separately | system | {{skill:cross-video-qa}} |
| Create a title, write a description | Title candidates and description, every sentence substantiated by the video | subtitles | {{skill:titles-and-description}} |
| Create thumbnail, big text for thumbnail | Title and thumbnail copy candidates; once selected, generate thumbnail image according to aspect ratio and import as candidate asset | media | {{skill:cover-and-title}} |
| Download this link | Create a new video and import; only download as a file if the user explicitly says so | media | — |
| Compress, transcode, merge, extract audio | File-to-file operations; leave original files untouched | media | — |
| Grab a few frames, look at visuals | Grab frames at given timestamps as images for review | media | — |
| Generate images, create illustrations, draw pictures | First check which service for image generation is available, then generate based on where the image will go: for video, import as candidate asset; for articles/presentations, save to working directory | media | Current task's craft (thumbnail, B-roll, voiceover final cut, final cut storyboard, article/presentation illustrations) |
| View final cut visuals, subtitle positions, drag in the editor, let me see in the editor | Open the web editor directly to this video; give the user a review link; text and timeline modifications still go via commands | web | — |
| Export, export final cut, export SRT | Export subtitles, script, audio, or final cut from the video | export | — | | Create a new empty video, put assets into it | Create a new video, import assets, and place them on the timeline | media | — | | Pack, portable pack, open a .baocut file | Export a portable pack, or open a portable pack as a new video | export, media | — | | Create a video from a template, create a video from scratch | After a briefing, write style and storyboard plan, create each shot using assets, generated images, or code visuals, add voiceover, mix audio, and export | media, voice | {{skill:video-production}} | | Create an educational, explainer, or teaching video, explain a concept, news, or paper | First determine the visual foundation in a combined entry, verify sources, find the explanation from the audience's questions, select a subject that can explain the topic, then follow the final cut process; for versions in another language or aspect ratio, wait until the main version is confirmed | media, voice | {{skill:explainer-video}}, {{skill:video-production}} | | Take a news story, event, rumor, person, or product story to search for assets, cut original audio, add voiceover, and edit into a video; insert such a clip into another final cut | Search the video library and online for real footage and original audio from people involved; after voiceover is ready, cut visuals to match the timestamps of the speech; overlay tweets, quotes, and dates as cards on screen; keep visuals constantly moving | media, voice | {{skill:clip-montage}} | | Create a video of a certain type but not clearly specified | First ask about the topic, goal, audience, and available materials, then begin | workflows | {{skill:video-production}} | | For a project with command-line access and segmented voiceover: run scripts for dubbing, alignment, packaging, placing on timeline, creating subtitles, overlaying live footage, measuring visual coverage | Copy existing scripts, write a plan (config, voiceover script, scene code, live footage shot list), run in order, redo only one segment when changed; scripts do not prescribe video format. Without command-line access: hand the finalized segments, live footage, and cards as a plan to {{tool:edits_assemble}} to place at once | voice, media, editing | {{skill:production-scripts}} | | Add lower thirds, keywords, large numbers, annotations, branded bumpers — motion graphics | Write a self-contained HTML page per rules, package as a code package, import, and place on the timeline aligned with voiceover | media | {{skill:motion-graphics}} | | Turn audio into a video, add visuals and waveform to a podcast | Create an editable video: choose background, title, waveform, and subtitle colors as a set based on content; background can be HTML; use only built-in elements for waveform; handle transcription, polishing, and subtitles per corresponding methods | workflows, editing | {{skill:subtitle-workflow}}, {{skill:polish-transcript}}; read {{skill:motion-graphics}} for HTML background as needed | | Make an MV or lyric video for a song; have lyrics, script, or dialogue and need to sync to audio | Take only timestamps from transcription; use the user's original text and write it back to the transcript; create bilingual subtitle layers as needed; visuals follow the final cut process | workflows, subtitles | {{skill:polish-transcript}}, {{skill:video-production}} | | Draw entire shots or segments with code: sentence-by-sentence visuals, character animations, Canvas or SVG scenes | Visuals are a pure function of time; package per segment into a code package and import; generate character and scene background sets first, then animate them in code | media | {{skill:video-production}} (code scenes) |
| Create slides, presentations, presentation pages | Write a deck in the working directory; after validation, produce cards in a thread; user previews, edits, and annotates in a functional area | media | {{skill:slides}} | | Create designs: UI, web pages, posters, charts/infographics, diagrams, prototypes | Write a design file (one file per artboard) in the working directory; after validation, produce cards in a thread; user previews, edits, and annotates in a functional area | media | {{skill:design}} | | Build a design system, organize brand tokens and components | Write a design system directory in the working directory; can be organized from a code repository or design tool; design files can use it | — | {{skill:design-system}} | | Write reports, proposals, plans, letters, manuals, or other documents; or implement comments from document reviews | Use the docs tool to create a collaborative document in the working directory; first send the skeleton, then fill section by section; produce cards in a thread; user edits and comments in a functional area | media | {{skill:docs}} |
Three Ground Rules
Every subsequent page's validation checks against these three rules:
| Rule | Meaning | Typical violation |
|---|---|---|
| Fidelity | Do not change the speaker's meaning or stance; translation is faithful; do not modify the user's original media; editing scope is on the timeline, not by pre-cutting files; do text work yourself, do not fabricate timestamps | Forcing a half-sentence to match a beginning; estimating word-level timestamps from sentence-level ones |
| Watchability | Cut points fall between words; keep breaths; subtitles are readable and avoid faces and platform UI; background music is under vocals; visual changes follow information changes; the beginning of a publishable piece is understandable with sound off (most mobile viewers start on mute) | Cutting all pauses to zero; subtitles covering the lower third; the hook being only audible |
| Meets requirements | Aspect ratio, duration, final cut language, and deliverables follow user confirmation; duration is a target, not a quota; do not pad with fills, loops, or speed changes; do not shorten by omitting necessary information | Repeating footage to fill 60 seconds |
2. Starting
Proceed in order. Details in references/start.md:
- Find the CLI:
baocutis on the PATH; if not, use the path from environment variableBAOCUT_CLI; if neither, ask the user to install BaoCut or tell you the location. Do not download it yourself. baocut version: Check if the CLI and Runtime interface versions match. If they don't (exit code 3), tell the user which one needs updating. Do not bypass or adapt to old parameters.baocut status: What the machine can do now: default service for each capability and availability, local model packages, external tools (yt-dlp, ffmpeg), with remediation commands for any missing.- Read one catalog page per task (Section 3).
Do not manually start the Runtime: if a command needing to connect to the Runtime cannot find it, the Runtime will automatically start in the background (result shows runtime.started: true). The CLI-started Runtime exits after a period of inactivity. No need to stop it after a task; only use baocut runtime stop when the user asks, and it only stops the one the CLI started.
Tools are already connected; no startup needed. Before using transcription, voice synthesis, image generation, or music generation, first use {{tool:models_capabilities}} to check available services and limits; then read one catalog page per task (Section 3).
3. Capability Catalog and Reading Discipline
| Page | Area in BaoCut | Covers |
|---|---|---|
| media | Videos, assets, downloads & transcoding | Downloading from links, transcoding & merging, grabbing frames, importing assets, creating new videos, opening portable packs, generating images; evidence hierarchy for viewing a video |
| subtitles | Scripts, translations & subtitle layers | Transcription, polishing and writing back, translating yourself, creating subtitle layers, translating with text models, reading scripts to write summaries & articles |
| editing | Timeline modifications | Transactional edits, versions, operation families and lookup, pre-checks, undo; talking-head cutting, chapters, text & elements |
| voice | Dubbing & speech synthesis | Translating for dubbing, voiceover, voice timbres; separate writing for "how to say" vs "what to say" |
| music | Music & music generation | Sources for background music, local music generation & style descriptions, looping or segmenting for long videos, music track & voice ducking, licensing |
| export | Export | Subtitles, scripts, audio, final cuts, portable packs, project files; video & audio parameters; pre-delivery checks |
| models | Model capabilities | Capability queries, local model package installation & checking, what to do when capability is not configured or needs authorization |
| system | Tasks, index & local machine | Viewing, canceling, and rerunning tasks; Space search, projects, user library, skill index; runtime environment & admin commands |
| web | Web editor | Opening a video's editor in a browser: viewing composited visuals, playback, drag-and-drop adjustments; giving the user a long-lived review link; accessing links & sessions |
Also: End-to-end methods in workflows;
Startup & version in start; output, exit codes, long tasks & large results in conventions; MCP usage in mcp; all built-in crafts of BaoCut listed at the end of this section.
Error objects, version conflicts, and generic handling of waiting for tasks in conventions; catalog pages and crafts are retrieved by ID using {{tool:skills_read}}; the skill index attached to this guide at session start lists open ones. Do not read crafts not in the index (user turned them off); follow this guide.
Reading discipline:
- Only open the page you need; read a page only once per task and reuse it afterward. If you already know which pages to read, read them all before beginning work.
- For multi-stage crafts, only read the parts needed for the current stage; fetch its
references/only when needed.
- For command parameters, use
baocut help <command>orbaocut spec <name>; for fields of an operation inedits apply, usebaocut edits ops <operation>orbaocut spec edits.<operation>. Do not pull the entire catalog or read full--help.
- For parameters, see the tool description; for fields of an operation in
edits_apply, use {{tool:edits_ops}} to look up only that operation, not the whole list.
- When a task belongs to a specific craft, read it before starting and follow its method; when continuing the same task across turns, also follow that method — do not switch to your own approach midway.
Built-in Skills
BaoCut's built-in crafts (methods). The table in Section 1 maps user speech to one of these; for tasks not in the table, read the one-sentence description to determine which craft to use, opening it for details only when necessary.
| Craft | Name | One-sentence description |
|---|---|---|
| {{skill:subtitle-workflow}} | Transcription & Subtitles | From a link or local audio/video, create an editable video, transcribe, polish, translate as needed, add subtitle layers, then export as needed |
| {{skill:polish-transcript}} | Polish Transcript | Fix typos and mis-hearings, unify terminology and punctuation, write back to the same transcript, keep word timestamps unchanged |
| {{skill:speaker-labeling}} | Speaker Labeling | Differentiate speakers by voiceprint, determine real names from evidence in the script and sources, write back to the transcript speakers |
| {{skill:translate-subtitles}} | Translate Subtitles | Translate each sentence yourself into a translation within the video, create a translation or bilingual subtitle layer; also used to update outdated translations |
| {{skill:video-summary}} | Video Summary | Pick the two or three most important things to explain thoroughly, plus a list of key points with video timestamps |
| {{skill:video-blog}} | Write Blog Article | Write a complete article from the video that is understandable without watching the video, with both author and audience perspectives |
| {{skill:titles-and-description}} | Create Titles & Descriptions | Title candidates and video description (explanation, chapters, tags), every sentence substantiated by the video |
| {{skill:cover-and-title}} | Thumbnail & Title | Title and thumbnail copy candidates; user selects, then generate thumbnail image by aspect ratio and import as candidate asset |
| {{skill:cross-video-qa}} | Cross-Video Q&A | Search across multiple videos by meaning to find where something is discussed, answer using only original words, each with video and timestamp |
| {{skill:video-chapters}} | Chapters | Section at natural topic transitions, each with a title and a one-sentence summary, write into the video chapters |
| {{skill:talking-head-cut}} | Talking Head Cut | Remove filler words, long pauses, and botched takes, tighten rhythm, add emphasis, B-roll, vertical framing, and music ducking as needed |
| {{skill:shorts-segments}} | Short Video Segments | From a long video, identify topics publishable independently; each topic cut from hook to finish, built as an editable sub-video |
| {{skill:narration}} | Voiceover Final Cut | Write script based on measured speaking speed, synthesize with one voice in one go, measure duration, redo only不合格 sentences, then edit visuals to match |
| {{skill:explainer-video}} | Explainer Video | Turn a concept, news, or material into an expository video that someone without background can understand and retell: find the explanation from the audience's questions, select a subject that can explain the topic, keep visuals moving, produce versions in other languages or aspect ratios as needed |
| {{skill:clip-montage}} | Narration Montage | Take a news story, event, or anecdote, search for assets from online and video library, cut original audio, add voiceover, edit into a video with constantly moving visuals, overlay tweets and quotes as cards; any topic |
| {{skill:video-production}} | From Brief to Final Cut | Create a complete final cut from scratch: style and storyboard plan, produce each shot, add voiceover, mix audio, export |
| {{skill:production-scripts}} | Production Scripts | With command-line access, use ready-made scripts for segment-by-segment voiceover, alignment, packaging code scenes, placing on timeline, creating subtitles, overlaying live footage, measuring visual coverage; scripts do not prescribe video format |
| {{skill:motion-graphics}} | Motion Graphics | Use self-contained HTML to customize audio/video backgrounds and titles, or create lower thirds, keywords, large numbers, annotations, and branded bumpers; import and place on timeline |
These pages are copies of built-in skills as released with this skill; baocut skills read <id> retrieves the current version on this machine (including user-added skills); when different, use the latter.
4. Orchestration
- Do single-step tasks directly: If the user only wants a small thing (export an SRT, grab three frames, change a title), just do that — don't apply a full workflow.
- Placeholder brackets: Items in the user's message shaped like "[target language]" are placeholders from quick-start or templates left for the user to fill, but not filled. Ask before starting — do not guess, and do not copy them into the output.
- Fixed-flow tasks: For transcription, download, dubbing, transcoding, and export, use top-level verbs ({{tool:transcribe}}, {{tool:download}}, {{tool:dub}}, {{tool:transcode}}, {{tool:export}}) to submit the entire workflow in one step — do not break it into sub-steps.
- Multi-step tasks — you are the director: First write a plan (deliverables, steps, which tool or craft per step), execute step by step, reading results before proceeding.
- Write operations and GPU-heavy tasks (transcription, synthesis, music generation, final cut export) are done by you; only one at a time on this machine. Sub-agents only deliver files and conclusions — do not let them modify videos or submit tasks.
- Continuing across rounds: First read the video's current state ({{tool:videos_inspect}}), continue from the step already done, do not repeat completed steps.
- Download and temporary files — check disk first. Before downloading an external video or online asset, or generating large temporary files like intermediate transcoding files, test renders, or test exports, first estimate size from duration and bitrate (1080p video roughly 1–3 GB per hour, ProRes pre-render 1+ GB per minute). Then check available space on the target disk: with shell on macOS/Linux use
df -h <directory>, on Windows use PowerShellGet-PSDrive. If unable to check, ask the user. Prefer non-system disks (macOS/Volumes/<disk>, Windows non-C:, Linux not mounted on/): setoutDirfor downloads, create long videos on that disk (see media "Download from Link"). Follow user-specified paths. If only system disk is available, proceed normally. If free space is less than double the estimate, first coordinate with the user on a location — do not force it onto the system disk. Mention which disk and directory in the reply. For temporary files to be imported into a video, setmanaged; the video will not lack assets even if the original file is deleted afterward. - When user searches for videos or content ("What videos/podcasts are there about...", "Which video talked about...", "Find..."), even if the user doesn't say "my" or "local", first search the user's video library — do not go online immediately. For textual content, use {{tool:space_search_v2}}; for visual features like person appearance, scenes, add
channels: ["visual"]once; for video names, use {{tool:videos_list}}. Answer first with library results (video name and timestamp). If not found, insufficient, or the user clearly wants external content (outside recommendations, breaking news), then search online. List online results in a separate paragraph marked "from web" — do not mix with library results. If the user explicitly asks for online results, search directly. - When searching for content within a video (a specific sentence, topic location, episode, a paragraph for writing): First search, do not read the full transcript. {{tool:space_search_v2}} cross-video by meaning and wording. {{tool:speech_relevant}} for writing material with source IDs. {{tool:space_related_videos}} for videos on similar topics. If result's
effectiveModeislexicalor tool reportsSEMANTIC_UNAVAILABLE, this machine has no usable semantic index: fall back to two or three keywords with {{tool:space_search}}, or read the transcript with {{tool:documents_read}}. Forweakhits, read the original text before using. - When searching for visuals (a specific shot, footage to illustrate or fill in, thumbnail candidates): Also search first: {{tool:space_search_v2}} with
channels: ["visual"]cross-video by visual description. {{tool:videos_match_frames}} in one video to find images matching a text fragment (during writing, pass the citation ID fromspeech_relevantvianear). Results are candidate windows; use {{tool:videos_frames}} to grab frames within the window and review. If tool reportsMODEL_NOT_INSTALLED,INDEX_NOT_READY, etc., no visual index is available: fall back to {{tool:videos_shots}} / {{tool:videos_frames}} to grab frames by shot or time. - When user provides source material (talking head, interview, recording, reference video) and you need to pick content from it: First {{tool:transcribe}}, then {{tool:space_index_status}} on those videos'
videoIdswithwaitSecto wait for semantic indexing. Onceavailable, use it to extract material. Ifavailableis false and source isexcluded(not in semantic index), do not wait; read the transcript directly. Wait at most twice (index building about 8 minutes per hour of video); if still not ready, use built portions for indexed videos and read transcripts for the rest. Do not change semantic index settings on behalf of the user. - When needing to use user-provided materials by visuals (illustration, fill in shots, pick clips; material may not have speech): First use {{tool:space_index_status}} on those videos'
videoIdswithchannel: visualto check visual index. Ifavailableis true and material is notindexed, use {{tool:space_index_build}} with samevideoIdsandchannel: visualto build it — no need to wait for user settings. Visual indexing is slower than speech indexing: don't wait idly — proceed with steps that don't rely on visuals, check again before using, and if still not ready, grab frames by shot. Ifavailableis false (no model package for image reading installed), grab frames by shot directly — do not suggest installing a model package unless the user asks. - Transcription, image generation, and code visuals can be used separately, not just for subtitles, thumbnails, and stickers:
- Transcription is also a timing ruler. When the user already has correct text (lyrics, script, dialogue), treat the recognized words only as alignment clues: take timestamps from transcription, use the user's original text, don't estimate timestamps for unaligned lines. See subtitles "When original text exists."
- Image generation is an asset factory. Draw a character's poses or a set of props on a uniform-color grid, then cut apart. Scene backgrounds without characters/text, then animate them in code. See media "Generate Images." Do not use system emoji for visual elements: cross-platform glyph differences and missing fonts in off-screen rendering.
- Code visuals are not just stickers. Entire shots or segments can be painted with Canvas or SVG by time. Always package as code and import ({{tool:compositions_import}}) — don't render to video files yourself and import. For entire shots, draw everything on one Canvas and import with directive baking ({{tool:compositions_import}}), which is 10-20x faster than per-frame screenshots in a browser. See {{skill:video-production}} code scenes. During the making stage, default to not baking: import with
live: true, place the segment directly on the timeline, and let the editor's real-time layer draw it live for preview and iteration. Once user approves, re-import withreplaceand withoutliveto bake, then export. Currently, the real-time layer only draws code visuals that fill the frame, sit at the bottom, and have only one per frame; transparent cards over live footage cannot be drawn this way — see alternatives in {{skill:video-production}} code scenes section 7. Only render outside BaoCut when the user wants a file directly rendered by code, not an editable video.
- The first frame of the final cut is the thumbnail. When you create or edit a video for publishing (final cut, talking-head cut, short video, voiceover piece, MV), platforms often take the first frame as the thumbnail. Therefore, the frame at 0 seconds must be complete and representative of the video: no black frame, no fade-in from blank, no halfway transition or closed eyes, and do not start the first segment with a fade-in. If there is a title and main visual, put them at 0 seconds.
5. Guidelines for Reference Files
- references/catalog/media.md: Covers downloading from links, transcoding, merging, frame extraction, importing assets, creating new videos, opening portable packs, and generating images. Also includes the evidence hierarchy for examining a video.
- references/catalog/subtitles.md: Covers transcription, polishing and writing back, manual translation, creating subtitle layers, machine translation, and generating summaries/articles from transcripts.
- references/catalog/editing.md: Covers transactional editing, versions, operation families, pre-checks, undo, talking-head cuts, chapters, and text/element manipulation.
- references/catalog/voice.md: Covers dubbing, voiceover, voice timbres, and separating "how to say it" from "what to say."
- references/catalog/music.md: Covers sources for background music, local music generation and style descriptions, looping/segmenting for long videos, music track voice ducking, and licensing.
- references/catalog/export.md: Covers exporting subtitles, scripts, audio, final cuts, portable packs, and project files.
- references/catalog/models.md: Covers model capability queries, installation and checking, and handling when capabilities are not configured or require authorization.
- references/catalog/system.md: Covers task management, search, project management, user library, skill index, and runtime environment/admin commands.
- references/workflows.md: End-to-end workflows for common production scenarios.
Reading discipline for references:
- Only open the page you need; read a page only once per task and reuse it. If you already know which pages to read, read them all before beginning work.
- For multi-stage crafts, only read the parts needed for the current stage; fetch its
references/only when needed. - For command parameters, use
baocut help <command>orbaocut spec <name>on CLI. For agent surfaces, parameters are in the tool description. For specific operations, usebaocut edits ops <operation>on CLI or {{tool:edits_ops}} on agent — do not pull the entire list. - When a task belongs to a specific craft, read it before starting and follow its method; when continuing the same task across turns, also follow that method — do not switch to your own approach midway.
6. Common Patterns
- One-off tasks: Do exactly what the user asks. If they only want an SRT exported, do that. If they want three frames grabbed, do that. Don't invent extra steps.
- Multi-step tasks — plan first: Write a plan (deliverables, steps, each step's tool or craft), execute sequentially, read results before proceeding.
- Write operations and GPU-heavy tasks: Transcription, synthesis, music generation, and final cut export are done by the main agent. Sub-agents only deliver files and conclusions — they do not modify videos or submit tasks.
- Continuing across turns: Read the current state ({{tool:videos_inspect}}) first, continue from the completed step — do not repeat.
- Disk usage check: Before downloading or generating large temporary files, estimate size from duration and bitrate. Check available space with
df -h(macOS/Linux) orGet-PSDrive(PowerShell/Windows). Prefer non-system disks. Mention disk and directory in reply. For temporary files to be imported into a video, setmanaged. - Search behavior: When searching for videos or content, first search the user's video library. Only after that, if necessary or explicitly requested, search online.
- Visual search: Use {{tool:space_search_v2}} with
channels: ["visual"]. Fall back to {{tool:videos_shots}} / {{tool:videos_frames}} when no visual index is available. - First frame is thumbnail: Ensure the frame at 0 seconds is complete and representative. No black frames, no fade-ins from blank.
7. Exports and Deliverables
- Export formats: Depending on the task, the skill exports subtitles (SRT, VTT), scripts, audio (WAV, MP3), final cuts (MP4, MOV), portable packs (BaoCut format), and project files.
- Pre-delivery checklist: Before delivering, verify:
- Duration matches target (not exact match, but reasonable)
- Aspect ratio matches target
- Language matches target
- No black frames or blank sections at start
- Subtitles are readable and not covering critical visuals
- Background music is under vocals
- All requested formats are produced
8. Error Handling and Edge Cases
- Unknown user intent: If the user's request does not match any entry in the table, default to asking clarifying questions about the topic, goal, audience, and available materials.
- Missing capabilities: Before using transcription, voice synthesis, image generation, or music generation, use {{tool:models_capabilities}} to check available services and limits. If unavailable, explain what is not available and suggest alternatives or user action.
- Disk space insufficient: If free space is less than double the estimated file size, coordinate with user for a different location. Do not force onto system disk.
- Semantic index unavailable: If
space_search_v2returnslexicalmode or tool reportsSEMANTIC_UNAVAILABLE, fall back to keyword search or read transcripts directly. - Visual index unavailable: If visual index is not available, fall back to {{tool:videos_shots}} / {{tool:videos_frames}} for frame-level access.
- Version mismatch (CLI only):
baocut versionexit code 3 — tell the user which component needs updating. Do not bypass. - External tool missing (CLI only):
baocut statusshows missing tools (yt-dlp, ffmpeg) with remediation commands. - Portable pack handling: Opening a .baocut file creates a new editable video. The user can then work on it as usual.
- Code scene rendering fallback: When real-time layer cannot render certain code visuals (e.g., transparent cards over live footage), suggest alternative from {{skill:video-production}} code scenes section 7.