finish-talking-head

Voiceover final video

This is chengfeng-videocut 's second business entry point. It consumes the already-reviewed basic material package and produces:

source_cut.mp4 + subtitles.srt
               |
               v
      storyboard / animation / timeline
               |
               v
        final.mp4 + verification.json

0. Perform a Runtime precheck first every time

PLUGIN_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"
ENSURE="$PLUGIN_ROOT/scripts/ensure-runtime.cjs"
VC="$PLUGIN_ROOT/scripts/videocut-cli.cjs"

node "$ENSURE" --install-if-missing --json

The precheck is an internal step of this Skill, not a third Skill. If missing, prompt once and install; if it fails, stop. Neither the precheck nor the headless generation stage may open Studio. For the detailed protocol, see Runtime and product contract。

1. Check the basic material package

node "$VC" workflow get "$jobDir" --json

The following must all exist and pass the product check:

• source_cut.mp4: the actual post-cut video, including an audio stream;
• subtitles.srt: standardized subtitles rebuilt based on the post-cut video;
• the same projectId as the current revision.

If missing, switch to $cut-talking-head to complete the prerequisite editing, then resume this Skill with the same projectId . Do not add a new "voiceover workbench" master control entry point, and do not create a second project.

2. Read the project configuration

The aspect ratio, animation style, and additional requirements must come from the current project state; do not read mutable global defaults shared by all projects. When the user has not yet chosen, ask only for the necessary information that would materially change the final video.

{
  "aspectRatio": "4:3",
  "animationStyle": "xiaohei",
  "requirements": "保留真实产品操作画面"
}

After the user confirms the configuration, execute with the latest revision start-final. Re-read the revision at every step; do not reuse old values consecutively.

3. Storyboard candidates → review

First read storyboard rules. Segment by subtitle semantics, bind candidate segments to a stable wordIds, then publish through product validation:

node "$VC" artifact put "$jobDir" \
  --type visual-plan \
  --file "$visualPlanProposal" \
  --expected-project-revision "$latestProjectRevision" \
  --expected-artifact-revision "$latestArtifactRevisionOrNone" \
  --json

Only after the status enters storyboard_review_readydo you start or reuse the product service and open Studio. After the user saves the review result, call show_workflow_confirmation; when the card returns continue_finish_storyboard , revalidate the revision, then execute confirm-storyboard。

4. Animation candidates → review

First read animation rules; when an HTML module is needed, then read animation module contract。

• Animations must be bound to specific voiceover sentences and cues.
• For real product operations, screenshots, and result pages, prioritize real materials.
• When there is no animation, submit empty modules and an explicit reason; do not fabricate placeholder modules.
• HTML must support restoring a deterministic state after seeking to any time.

After publishing animation-manifest , wait for animation_review_ready, and review in the same Studio. Only after the card returns continue_finish_animation do you execute confirm-animation。

5. Timeline candidates → review

First read timeline and export. The final timeline only consumes post-cut time, real subtitles, and reviewed modules:

node "$VC" artifact put "$jobDir" \
  --type timeline \
  --file "$timelineProposal" \
  --expected-project-revision "$latestProjectRevision" \
  --expected-artifact-revision "$latestArtifactRevisionOrNone" \
  --json

After the status enters timeline_review_ready , review in the same Studio. Only when the card returns continue_finish_timeline and the revision is still consistent do you execute confirm-timeline。

6. Product export and acceptance

The final export must be completed by Runtime itself; the Skill does not carry a renderer, nor does it pass old Skill script paths:

node "$VC" workflow get "$jobDir" --json
node "$VC" render run "$jobDir" \
  --expected-revision "$latestRevision" \
  --confirmed \
  --json

If the current Runtime returns missing_renderer, clearly report that this is a Runtime version gap and stop. It is forbidden to sneak the old export_final_video.cjs, a standalone preview service, or direct FFmpeg export back into the Skill.

Report completion only when all of the following conditions are met:

• renders/final.mp4 exists, and both the video stream and audio stream can be decoded;
• The resolution matches the project aspect ratio;
• The duration and timeline are within tolerance;
• Keyframes have no black bars, occlusion, wrong footage, or ghost subtitles;
• renders/verification.json 's passed=true。

Confirmation and recovery rules

candidate saved
      |
      v
*_review_ready ----> 打开同一个 Studio ----> 用户保存
      |                                      |
      |                         MCP App 回传 action + revision
      |                                      |
      +<-------- revision mismatch ----------+
      |             停止并核对
      v
confirmed transition

• The card does not directly perform any destructive action.
• return_finish_* returns to the corresponding review view;pause_workflow stops after saving.
• revision_conflict must re-read the state and must not silently overwrite.
• "Can play preview" does not equal "final cut has been exported".