# dancan254/voiceover-video-skill architecture

> Architecture diagram of the GitHub repository dancan254/voiceover-video-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dancan254/voiceover-video-skill
- Repository: https://github.com/dancan254/voiceover-video-skill

## Overview

voiceover-video is an agent-orchestrated, local pipeline for turning a recording—or an agent-written script—into an edited vertical video. The principal workflow transcribes and proofreads speech, builds word-timed captions, plans and approves shots, sources credited media, authors themed scenes, renders and reviews frames, then synthesizes sound and encodes the final video. Script-mode voices and aligns character dialogue instead of transcribing an input recording. The README documents additional features such as face-cam bookends and alternate formats; sampled source confirms only selected implementation details, so uncertain internal wiring is omitted.

Main entry points: [`skills/voiceover-video/scripts/render.js`](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render.js) (Frame renderer), [`skills/voiceover-video/scripts/mix-encode.sh`](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/mix-encode.sh) (Mix and encode), [`skills/voiceover-video/scripts/find_media.py`](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/find_media.py) (Media search and fetch), [`skills/voiceover-video/templates/kinetic.html`](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/templates/kinetic.html) (Scene composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow and speech"]
  node_skill["Workflow instructions<br/>[SKILL.md]"]
  node_recording["Voice recording"]
  node_transcribe["Local transcription<br/>[transcribe.py]"]
  node_scriptvoice["Script voiceover<br/>[speak.py]"]
  node_captions["Caption preparation<br/>[build_captions.py]"]
end

subgraph group_media["Media and scenes"]
  node_shotplan["Approved shot plan<br/>[shot-list.md]"]
  node_mediafind["Media search and fetch<br/>[find_media.py]"]
  node_media_sources["Media providers"]
  node_credits["Media credits<br/>[find_media.py]"]
  node_scene["Scene composition<br/>[kinetic.html]"]
  node_brand["Brand configuration<br/>[init_brand.py]"]
  node_template["Theme template fill<br/>[fill_template.py]"]
end

subgraph group_render["Rendering and review"]
  node_renderer["Frame renderer<br/>[render.js]"]
  node_contact["Contact sheet review<br/>[contact-sheet.sh]"]
  node_frames["Frame encoding<br/>[render-frames.sh]"]
end

subgraph group_audio["Sound and delivery"]
  node_cues["Timeline sound cues<br/>[render.js]"]
  node_synth["Sound synthesis<br/>[synth_audio.py]"]
  node_mix["Mix and encode<br/>[mix-encode.sh]"]
  node_video["Finished video"]
end

node_user(("Creator"))
node_agent(("Shell-capable agent"))

node_user -->|"requests video"| node_agent
node_agent -->|"follows workflow"| node_skill
node_user -->|"provides recording"| node_recording
node_recording -->|"transcribes locally"| node_transcribe
node_transcribe -->|"writes word timings"| node_captions
node_agent -->|"proofreads and builds"| node_captions
node_agent -.->|"voices script"| node_scriptvoice
node_scriptvoice -.->|"writes aligned words"| node_captions
node_agent -->|"authors and approves"| node_shotplan
node_agent -->|"searches and fetches"| node_mediafind
node_mediafind -->|"queries providers"| node_media_sources
node_mediafind -->|"records attribution"| node_credits
node_agent -->|"authors scenes"| node_scene
node_user -.->|"sets brand"| node_brand
node_brand -->|"provides configuration"| node_template
node_template -->|"fills composition"| node_scene
node_renderer -->|"loads composition"| node_scene
node_scene -->|"provides timeline"| node_renderer
node_renderer -->|"renders review stills"| node_contact
node_agent -->|"reviews and revises"| node_contact
node_renderer -->|"extracts cues"| node_cues
node_cues -->|"supplies timeline cues"| node_synth
node_renderer -->|"renders frames"| node_frames
node_frames -->|"provides rendered video"| node_mix
node_synth -->|"provides sound beds"| node_mix
node_recording -->|"supplies voice audio"| node_mix
node_mediafind -.->|"supplies extracted clip audio"| node_mix
node_mix -->|"encodes final video"| node_video
node_video -->|"delivers result"| node_user

click node_skill "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/SKILL.md"
click node_transcribe "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/transcribe.py"
click node_scriptvoice "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/speak.py"
click node_captions "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/build_captions.py"
click node_shotplan "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/examples/kafka-vs-rabbitmq/shot-list.md"
click node_mediafind "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/find_media.py"
click node_credits "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/find_media.py"
click node_scene "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/templates/kinetic.html"
click node_brand "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/init_brand.py"
click node_template "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/fill_template.py"
click node_renderer "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render.js"
click node_contact "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/contact-sheet.sh"
click node_frames "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render-frames.sh"
click node_cues "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render.js"
click node_synth "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/synth_audio.py"
click node_mix "https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/mix-encode.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_recording,node_transcribe,node_scriptvoice,node_captions toneBlue
class node_shotplan,node_mediafind,node_media_sources,node_credits,node_scene,node_brand,node_template toneAmber
class node_renderer,node_contact,node_frames toneMint
class node_cues,node_synth,node_mix,node_video toneRose
class node_user,node_agent toneIndigo
```

## Components

### Workflow and speech

- [Workflow instructions](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/SKILL.md): `skills/voiceover-video/SKILL.md`
- **Voice recording**
- [Local transcription](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/transcribe.py): `skills/voiceover-video/scripts/transcribe.py`
- [Script voiceover](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/speak.py): `skills/voiceover-video/scripts/speak.py`
- [Caption preparation](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/build_captions.py): `skills/voiceover-video/scripts/build_captions.py`

### Media and scenes

- [Approved shot plan](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/examples/kafka-vs-rabbitmq/shot-list.md): `skills/voiceover-video/examples/kafka-vs-rabbitmq/shot-list.md`
- [Media search and fetch](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/find_media.py): `skills/voiceover-video/scripts/find_media.py`
- **Media providers**
- [Media credits](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/find_media.py): `skills/voiceover-video/scripts/find_media.py`
- [Scene composition](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/templates/kinetic.html): `skills/voiceover-video/templates/kinetic.html`
- [Brand configuration](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/init_brand.py): `skills/voiceover-video/scripts/init_brand.py`
- [Theme template fill](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/fill_template.py): `skills/voiceover-video/scripts/fill_template.py`

### Rendering and review

- [Frame renderer](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render.js): `skills/voiceover-video/scripts/render.js`
- [Contact sheet review](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/contact-sheet.sh): `skills/voiceover-video/scripts/contact-sheet.sh`
- [Frame encoding](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render-frames.sh): `skills/voiceover-video/scripts/render-frames.sh`

### Sound and delivery

- [Timeline sound cues](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/render.js): `skills/voiceover-video/scripts/render.js`
- [Sound synthesis](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/synth_audio.py): `skills/voiceover-video/scripts/synth_audio.py`
- [Mix and encode](https://github.com/dancan254/voiceover-video-skill/blob/main/skills/voiceover-video/scripts/mix-encode.sh): `skills/voiceover-video/scripts/mix-encode.sh`
- **Finished video**

### Other components

- **Creator**
- **Shell-capable agent**

## Connections

- Creator → Shell-capable agent: requests video
- Shell-capable agent → Workflow instructions: follows workflow
- Creator → Voice recording: provides recording
- Voice recording → Local transcription: transcribes locally
- Local transcription → Caption preparation: writes word timings
- Shell-capable agent → Caption preparation: proofreads and builds
- Shell-capable agent → Script voiceover: voices script
- Script voiceover → Caption preparation: writes aligned words
- Shell-capable agent → Approved shot plan: authors and approves
- Shell-capable agent → Media search and fetch: searches and fetches
- Media search and fetch → Media providers: queries providers
- Media search and fetch → Media credits: records attribution
- Shell-capable agent → Scene composition: authors scenes
- Creator → Brand configuration: sets brand
- Brand configuration → Theme template fill: provides configuration
- Theme template fill → Scene composition: fills composition
- Frame renderer → Scene composition: loads composition
- Scene composition → Frame renderer: provides timeline
- Frame renderer → Contact sheet review: renders review stills
- Shell-capable agent → Contact sheet review: reviews and revises
- Frame renderer → Timeline sound cues: extracts cues
- Timeline sound cues → Sound synthesis: supplies timeline cues
- Frame renderer → Frame encoding: renders frames
- Frame encoding → Mix and encode: provides rendered video
- Sound synthesis → Mix and encode: provides sound beds
- Voice recording → Mix and encode: supplies voice audio
- Media search and fetch → Mix and encode: supplies extracted clip audio
- Mix and encode → Finished video: encodes final video
- Finished video → Creator: delivers result