name: talking-head
version: "2.0"
description: >
  End-to-end talking-head video pipeline. Takes raw footage of a person speaking,
  transcribes it, makes edit decisions, generates subtitles, mixes audio,
  and composes the final output.
category: talking_head
stability: beta
default_checkpoint_policy: guided

extensions:
  custom_scripts: true
  custom_playbooks: true
  custom_skills: true
  custom_tools: false

required_skills:
  - pipelines/talking-head/executive-producer
  - pipelines/talking-head/idea-director
  - pipelines/talking-head/script-director
  - pipelines/talking-head/scene-director
  - pipelines/talking-head/asset-director
  - pipelines/talking-head/edit-director
  - pipelines/talking-head/compose-director
  - pipelines/talking-head/publish-director
  - meta/reviewer
  - meta/checkpoint-protocol

orchestration:
  mode: executive-producer
  skill: pipelines/talking-head/executive-producer
  budget_default_usd: 0.50
  max_revisions_per_stage: 3
  max_send_backs: 3

compatible_playbooks:
  recommended:
    - clean-professional
  also_works: []
  custom_allowed: true

stages:
  - name: idea
    skill: pipelines/talking-head/idea-director
    produces:
      - brief
      - decision_log
    tools_available: []
    checkpoint_required: true
    human_approval_default: true
    review_focus:
      - Brief accurately reflects footage content
      - Target platform is appropriate
      - Duration target is realistic
    success_criteria:
      - Schema-valid brief artifact
      - Brief references the provided raw footage

  - name: script
    skill: pipelines/talking-head/script-director
    required_artifacts_in:
      - brief
    optional_artifacts_in:
      - source_media_review
    produces:
      - script
    required_tools:
      - transcriber      # speech-to-text
    optional_tools: []
    tools_available:
      - transcriber
    checkpoint_required: true
    human_approval_default: true
    review_focus:
      - Transcription accuracy (spot-check key sections)
      - Section boundaries align with topic changes
      - Timestamps match actual speech
    success_criteria:
      - Schema-valid script artifact
      - Script sections have valid timestamps from transcript data

  - name: scene_plan
    skill: pipelines/talking-head/scene-director
    required_artifacts_in:
      - script
    optional_artifacts_in:
      - brief
    produces:
      - scene_plan
    required_tools: []
    optional_tools:
      - frame_sampler    # representative frame extraction
      - face_tracker     # face position analysis for reframing decisions
      - silence_cutter   # silence detection for jump cut planning
    tools_available:
      - frame_sampler
      - face_tracker
      - silence_cutter
    checkpoint_required: true
    human_approval_default: true
    review_focus:
      - Scenes cover full footage duration
      - Enhancement opportunities identified
      - Overlay scenes are feasible
    success_criteria:
      - Schema-valid scene_plan artifact
      - Scenes cover the full duration of the raw footage

  - name: assets
    skill: pipelines/talking-head/asset-director
    required_artifacts_in:
      - scene_plan
    optional_artifacts_in:
      - script
    produces:
      - asset_manifest
    required_tools:
      - subtitle_gen     # captions
    optional_tools:
      - audio_mixer      # audio prep
      - image_selector
    tools_available:
      - subtitle_gen
      - audio_mixer
      - image_selector
    checkpoint_required: true
    human_approval_default: false
    review_focus:
      - Subtitle file exists and matches transcript timing
      - Audio extracted and normalized
      - All asset paths resolve to existing files
    success_criteria:
      - Schema-valid asset_manifest artifact
      - All referenced asset files exist on disk

  - name: edit
    skill: pipelines/talking-head/edit-director
    required_artifacts_in:
      - scene_plan
      - asset_manifest
    optional_artifacts_in:
      - script
    produces:
      - edit_decisions
    optional_tools:
      - silence_cutter   # auto jump cuts on silent segments
      - video_trimmer    # speed control (0.5x–2x), cut, concat
    tools_available:
      - silence_cutter
      - video_trimmer
    checkpoint_required: true
    human_approval_default: false
    review_focus:
      - Cuts reference valid source files
      - Subtitles enabled with proper styling
      - Audio configuration is complete
    success_criteria:
      - Schema-valid edit_decisions artifact
      - All cuts reference valid source files
      - Timestamps are within source duration bounds

  - name: compose
    skill: pipelines/talking-head/compose-director
    required_artifacts_in:
      - edit_decisions
      - asset_manifest
    optional_artifacts_in:
      - scene_plan
    produces:
      - render_report
      - final_review
    required_tools:
      - video_compose    # rendering
      - audio_mixer      # audio layering + segmented music
    optional_tools:
      - face_enhance     # face enhancement
      - eye_enhance      # eye brightening, dark circle removal
      - color_grade      # color correction
      - audio_enhance    # audio cleanup
      - auto_reframe     # aspect ratio conversion with face tracking
      - face_tracker     # face position data for reframing
      - silence_cutter   # auto jump cuts
      - video_trimmer    # speed control (0.5x–2x)
      - remotion_caption_burn  # animated word-by-word captions via Remotion
      - showcase_card    # letterboxed showcase cards with typography
      - video_stitch     # multi-clip assembly with transitions
      - visual_qa        # frame extraction + quality validation
    tools_available:
      - video_compose
      - audio_mixer
      - face_enhance
      - eye_enhance
      - color_grade
      - audio_enhance
      - auto_reframe
      - face_tracker
      - silence_cutter
      - video_trimmer
      - remotion_caption_burn
      - showcase_card
      - video_stitch
      - visual_qa
    checkpoint_required: true
    human_approval_default: false
    review_focus:
      - Output video exists and is playable
      - Subtitles are synced with speech
      - Audio is clear with balanced levels
    success_criteria:
      - Schema-valid render_report artifact
      - Output video file exists and is playable

  - name: publish
    skill: pipelines/talking-head/publish-director
    required_artifacts_in:
      - render_report
      - final_review
    produces:
      - publish_log
    tools_available: []
    checkpoint_required: true
    human_approval_default: true
    review_focus:
      - Metadata is complete and compelling
      - Export package is structured correctly
    success_criteria:
      - Schema-valid publish_log artifact
      - Export package or publish URLs are present