jianying-draft-subtitles

JianYing Subtitles

Subtitle timing comes from measured speech or explicit external subtitles, and is not replaced by shot cut points or manual time estimation.

When to use

• The user explicitly requests the CapCut capability corresponding to the title of this skill and accepts handling it through the unified Rust jianying CLI.
• The user needs auditable planning, execution, or verification evidence, rather than only a conceptual answer.
• When the requirement is not yet clear, first route to jianying-draft-use ; this skill should not be used to handle other editors, general video knowledge Q&A, or speculative execution lacking the necessary materials.

Capability boundaries

• ✅ Can do: Generate a deterministic plan based on real paths and probe results; when capability is supported , execute operations in this domain; output the actually achieved evidence level.
• ⚠️ Requires conditions: Writes must use an isolated copy; costs, external services, and native application actions must have precise approval; playback or export conclusions must have corresponding runtime evidence.
• ❌ Out of scope: Do not automatically install or upgrade the CLI, do not generate Python draft scripts, do not call external headless checkout, do not overwrite source drafts, and do not fabricate resource IDs, media facts, or success states.

Step 1 — Establish the factual baseline

Record the user's goal, absolute paths, host platform, target deliverables, and allowed side effects; when information is insufficient, first provide a read-only diagnostic plan and list the missing facts item by item.

Step 2 — Handshake capabilities

Run version, doctor, and capabilities checks. A satisfying version does not mean the capability is available;partial、external_dependency or missing states must enter the degraded path.

Step 3 — Validate inputs

Probe media, drafts, configuration, or task status; reject nonexistent paths, out-of-range times, unknown schemas, mismatched hashes, and approvals that cannot be bound to a target.

Step 4 — Form a deterministic plan

Write the operations, parameters, output paths, risk levels, confirmation points, and expected evidence into the plan. Order multiple tasks as "read-only facts → reversible writes → external/native actions".

Step 5 — Execute or stop before the gate

Execute only supported and authorized steps. When output is ambiguous, times out, or partially succeeds, retain the task ID, audit logs, and artifacts, and do not automatically retry.

Step 6 — Verify and deliver

Run structural validation, then append cold reopen, playback, or native export evidence according to the goal; report the actual level, failed fields, recoverable actions, and unverified items.

Rules

• The material duration, dimensions, streams, hashes, and draft version in the plan must come from tool output.
• Approval must be bound to the command, parameters, target, validity period, and budget; if any field changes, re-confirm.
• User data is processed only within local target paths and the declared external Provider boundaries; unrelated credentials must not be collected, uploaded, or recorded.
• When current evidence is insufficient, use UNVERIFIED、BLOCKED or AMBIGUOUS, and it is forbidden to fill in results with inference.

Gotchas

1. Treating version as capability: Always check the specific capability; do not execute directly just because the CLI version is new enough.
2. Treating structural validation as final-cut acceptance: project verify Only proves the structural layer; playback and native export require independent evidence.
3. Directly modifying the source draft: First create an isolated copy and record the input hash; any in-place overwrite request must be stopped and changed to a new output.
4. Automatically retry ambiguous cases: First query the task, audit, and external artifacts; only after confirming no side effects occurred may the user approve a retry.
5. Filling in resources or times from memory: Resource IDs come from the catalog, and times come from probe/ASR/project data; if unobtainable, explicitly block.
6. Vaguely asking for more information: First provide an executable read-only plan, then explicitly list the gaps such as paths, delivery level, or authorization.

Verification checklist

• CLI identity, version, and capability are recorded.
• All input paths, media facts, and hashes are reviewable.
• The write target is isolated from the source draft, and confirmation points are precisely bound.
• Failure and ambiguous paths retain the task ID, logs, and recovery suggestions.
• The final wording is consistent with the actual evidence level.

Run contract

• Trigger conditions: the user needs SRT/ASS import and export, subtitle additions and modifications, styling, translation, or subtitle verification.
• Required capability:captions.import、captions.style、captions.verify。
• Minimum CLI version:1.6.0；captions.verify When supported is not reached, you must not claim that a cold reopen is complete.
• Default risk:reversible_write。
• Input facts: target draft/isolated output, subtitle file encoding and format, time base, language, style, and safe area.
• Confirmation points: writing to an existing draft, online/paid translation, and overwriting export files each require separate confirmation.
• Success evidence:cold_reopen; structural import only proves structural.
• Prohibited actions: do not generate Python draft scripts, do not call external headless checkout, and do not manually estimate times, create overlapping subtitles, or treat structural verification as playback verification.

Workflow

1. captions list/get Read the current state.
2. Before import, parse SRT/ASS and reject negative times, end times earlier than start times, and unexpected overlaps.
3. Use captions import-srt or captions import-ass to write an isolated copy.
4. Use captions add/set/style/translate for local modifications; for translation, prefer offline by_id/by_text mapping.
5. captions export-srt/export-ass perform a round-trip check, then execute project verify。
6. When real acceptance is required, cold reopen the draft to check fonts, line breaks, safe area, and synchronization.

When generating subtitles from TTS or narration, cues use the detected final audio artifact as the time fact; script text length, planned duration, and research sample parameters cannot replace actual audio timing. Local rework keeps cue IDs and unmodified intervals stable.

For command selection, styling, and recovery, see references/workflow.md. For isolated editing Jobs, see examples/minimal-job.json。

Progressive materials

• On first execution, load normal path to obtain the end-to-end sequence.
• When encountering failures or unknown states, load failure recovery and error recovery table。
• When the user requests privilege escalation, overwriting, or automatic retry, load boundary refusal。
• Before delivery, complete each item of the verification checklist, and do not claim completion based only on a plan or file existence.