SRT A-roll Jianying

Turn an SRT-aligned talking-head video into an editable Jianying Pro draft. Keep semantic analysis separate from deterministic draft generation: analyze and write the plan, then use the bundled aroll-draft CLI to validate and build it.

Locate the runtime

Treat the directory containing this SKILL.md as SKILL_ROOT. Do not assume the current working directory is the skill directory. Run bundled commands as:

uv run --project "$SKILL_ROOT" aroll-draft <command>

For a request to initialize, install dependencies, or set up this Skill for first use, run bash "$SKILL_ROOT/scripts/bootstrap-macos.sh". It changes nothing by default. Before passing --install or --install-homebrew, state which system software would be installed and obtain explicit user approval. After initialization, the script synchronizes the runtime and runs aroll-draft doctor. If the user declines installation, explain the missing prerequisite.

Choose the requested mode

• For installation or environment problems, run doctor and report the failing checks.
• For browser-based work, run preview; the unified local workbench starts with SRT upload, then shows the manual timeline. 移除 SRT detaches the current subtitle and returns to the upload screen without deleting the source, workspace copy, saved plan, or styles. Open 设置 from the timeline to directly edit the last-used aspect without an intermediate orientation dialog. The top switch still selects independent 16:9 and 9:16 styles, subtitles, main-video movement, and sticker gradients. 重置 restores only the active panel from the packaged defaults, not the last saved values.
• For manual arrangement with a known local file, run edit <srt> [--plan <plan>]; it opens the same infinite-canvas workbench with the SRT already loaded. Without --plan, saved timelines live in the Skill's private workspace, not beside the user's media. Click the timeline to add a component through the lightweight popover, or click an existing clip to edit it. Chapter creation requires both a main title and subtitle.
• The workbench's AI 一键生成 action must invoke a real configured model Provider for every density; never substitute the old local heuristic planner. Prefer an available authenticated local CLI on first use (Codex CLI, then WorkBuddy CLI), while allowing OpenAI, Anthropic, and OpenAI-compatible APIs. Keep the active engine collapsed into a simple status row; expose provider changes from its 编辑 button, hide API-only fields for CLI modes, and clearly explain that CLI modes reuse the corresponding Agent login. Read API keys only from the configured environment-variable name and never persist or return the secret. Disclose that this action sends SRT text to the selected Provider while video and styles stay local. If the Provider is unavailable, unauthenticated, times out, or returns invalid data, show a clear error and leave the timeline unchanged. Require dense, balanced (first-use default), or minimal. After any overwrite confirmation, show a blocking mode-specific loading state. Deterministically validate cue references, overlaps, step groups, text length, and density before replacing keyword, statement, and step items; preserve manual chapters, mark the plan unsaved, and never infer new chapters.
• Treat AI 一键生成 as the workbench's primary efficiency feature: it creates the first timeline pass, while the user can refine it before delivery. 生成草稿 must first save that exact current timeline, use a native local-video path rather than upload or copy the media, build in the background with visible status, enforce the Jianying-running guard, require explicit confirmation before replacing a same-name draft, and expose the completed draft in Finder. A blocked build must never look inert: keep the modal open, restore the submit button, and show an in-modal alert above the fields. For jianying_running, explicitly ask the user to fully quit Jianying and retry, and state that the timeline was saved and will not be lost; error toasts must render above modal and loading overlays.
• The timeline legend maps yellow to keyword, orange-red to statement, blue to step, and purple to chapter. Its 后退 / 前进 controls are undo/redo for all component mutations, including AI replacement; 清除所有组件 must confirm first and remain undoable.
• For SRT analysis or draft generation, follow the workflow below.
• For questions about component selection, read references/analysis-rules.md.
• Before writing or repairing a plan, read references/plan-schema.md.
• For installation on Codex, Claude Code, Cursor, or another local Agent, read references/installing-on-agents.md.

Create an enhanced draft

1. Resolve the SRT path and run inspect. Use a same-basename .mp4, .mov, .m4v, or .mkv when present unless the user chooses another video or no video.
2. Resolve the plan source before doing any semantic analysis:
   • Prefer a plan path explicitly named by the user.
   • Otherwise use the saved plan reported by the active workbench's /api/editor only when that workbench SRT has the same content as the requested SRT.
   • Otherwise run aroll-draft plan-path <srt> --kind manual. Use that file when it exists. The command keys the workspace by normalized SRT content, records known source paths, and safely copies a legacy same-directory .enhancement-plan.manual.json into the workspace when needed without deleting the original.
     A saved manual timeline is already user-confirmed. Validate and build it exactly as saved; do not analyze again, rewrite text, replace components, or ask for another content confirmation. Never use an active workbench plan whose SRT does not match the requested SRT.
3. If no saved manual timeline exists, analyze the requested SRT according to references/analysis-rules.md, create keyword, statement, and step items, and do not infer chapters. Run aroll-draft plan-path <srt> --kind auto and write the automatic plan to the returned workspace path. Replacing auto.json for the same SRT content is allowed; never create an automatic plan beside the user's SRT.
4. Run validate-plan and fix all validation errors. When the user explicitly asked to generate a draft, that request authorizes building the validated automatic plan without an intermediate confirmation. If the user asked only for analysis or a proposal, summarize it and stop before building.
5. The build creates a separate editable 全局字幕 track from every SRT cue by default. Do not treat ordinary subtitles as A-roll callouts.
6. Before building, ensure the user has exited Jianying. If Jianying is running, stop and ask them to close it; do not bypass the protection unless explicitly requested.
7. Run build. Do not use --replace unless the user explicitly authorizes replacing that named draft.
8. Report which plan source was used (saved manual timeline or automatic SRT analysis), the generated draft path, whether the main video was linked, added or missing sound effects, and any limitation that still requires manual work.

Use the video during the build whenever practical. Without a video, text, sound effects, and the native gradient sticker can still be generated, but main-video position keyframes cannot be added later automatically.

Preserve these invariants

• Use keyword, statement, and step for overlays. Represent new chapter cards in the root chapters array, not as section highlights. Legacy section highlights remain buildable.
• A chapter may be placed at any millisecond inside the source timeline and must include a main title plus subtitle. It must not bisect an existing enhancement component. It cuts the A-roll and inserts the bundled assets/chapter_placeholder.jpg as a real 2-second photo segment, center-cropped to the active canvas, with centered single-line titles and chapter_transition at its start; do not add a chapter sticker. If it falls inside an SRT cue, split that subtitle around the inserted chapter so text does not remain visible over the chapter card. The builder must shift every later video segment, subtitle, callout, sticker, keyframe, and sound effect by the accumulated chapter duration. Keyframes on split A-roll segments use offsets relative to the original source media, not the target segment start.
• Global subtitles are independent from the three A-roll presets. Keep them enabled unless the user explicitly asks to turn them off; their style is controlled from 时间轴 → 设置 → 全局字幕.
• Each of the four enhancement components has its own optional auto_font_size setting. It may only reduce that component's font size from its configured manual maximum according to the text amount and available width. It must never override position, maximum width, font family, alignment, colors, strokes, user text, or user-authored line breaks.
• Treat highlight density as a ceiling and review signal, never a quota. It is valid for a passage to have no callouts when none materially improve comprehension, memory, or structure.
• Keep callouts non-overlapping; adjacent components may touch or have any nonnegative gap. A multi-step process uses one continuous group_id, sequential step_index values starting at 1, and one sound effect per step. Main-video entry position keyframes stay at the component start and one frame after it; exit keyframes stay at one frame before the component end and exactly at the component end, returning to zero at that end boundary so no exit keyframe spills into the following component.
• Treat step_index and step_total as derived timeline metadata. After a manual delete, move, AI replacement, or save, automatically renumber every still-contiguous multi-step group. If only one member remains, or one group_id has been split by another component, convert the affected entries to standalone step items by removing all grouping fields. The save endpoint must repeat this repair before strict validation so an already-open older workbench can preserve and save its unsaved edits. If saving still fails, 保存并生成 must show the save error inside the build modal rather than silently returning.
• Keep display_text faithful to the SRT and within 24 characters. Do not invent facts or unsupported chapter boundaries.
• Use SRT timing as the source of truth. Do not claim word-level precision when the SRT only provides sentence-level cues.
• When a video is present, draft generation uses its real width and height for the draft canvas and text sizing. The plan canvas is used only when generating without video; native highlight stickers use the resolution-independent logical canvas rule below.
• Express main-video horizontal movement as a percentage of canvas width, defaulting to 25%. Jianying maps native shape coordinates by canvas_width / 720; therefore create highlight gradient shapes in a 720-wide logical canvas with width 504 and height 720 * canvas_height / canvas_width. This yields exactly 70% canvas width, 100% canvas height, and a stable left edge at any resolution.
• The video stays local and is referenced by absolute path; it is not uploaded or copied into the project.
• Keep source folders clean. Manual and automatic plans share ~/.config/srt-aroll-jianying/workspaces/plans/<srt-sha256>/ as manual.json and auto.json; source.json records matching SRT paths and content fingerprint. Prefer manual.json whenever it exists. Only use another location when the user explicitly supplies --plan or a plan path.
• Treat font and sound-effect licensing as the user's responsibility. Do not download or redistribute replacements without permission.
• Current draft registration, native shape sticker, font lookup, and Jianying process protection are supported only on macOS. On Windows, limit work to SRT analysis and browser preview unless the user explicitly accepts an experimental draft.