# nikhilcherry/kinetix architecture

> Architecture diagram of the GitHub repository nikhilcherry/kinetix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhilcherry/kinetix
- Repository: https://github.com/nikhilcherry/kinetix

## Overview

Kinetix turns a reel author’s beat-synchronized HTML scenes and soundtrack into a checked, rendered video. The documented path runs from scene and audio authoring through the seek-time runtime, HyperFrames bridge and render, with captions, effects and poster generation as supporting branches. Several CLI orchestration details and the poster implementation were not sampled, so those relationships rely on README documentation rather than inspected source.

Main entry points: [`template/index.html`](https://github.com/nikhilcherry/kinetix/blob/main/template/index.html) (Reel scenes), [`music/hits.py`](https://github.com/nikhilcherry/kinetix/blob/main/music/hits.py) (Beat-grid mixer), [`runtime/kinetix.js`](https://github.com/nikhilcherry/kinetix/blob/main/runtime/kinetix.js) (Timeline runtime), [`bridge/hf-bridge.js`](https://github.com/nikhilcherry/kinetix/blob/main/bridge/hf-bridge.js) (HyperFrames bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Reel Authoring"]
  node_starter["Starter page<br/>[index.html]"]
  node_reel["Reel scenes<br/>[index.html]"]
end

subgraph group_audio["Soundtrack and Voice"]
  node_musicgen["MusicGen beds<br/>[hypebeat.py]"]
  node_synth["Synth soundtrack<br/>[music.py]"]
  node_beatmix["Beat-grid mixer<br/>[hits.py]"]
  node_bedfile["Audio bed"]
  node_mixfile["Mixed soundtrack"]
  node_sarvam["Sarvam TTS"]
  node_voice["Voice clips"]
end

subgraph group_render["Scene and Render"]
  node_runtime["Timeline runtime<br/>[kinetix.js]"]
  node_bridge["HyperFrames bridge<br/>[hf-bridge.js]"]
  node_hyperframes["HyperFrames check/render"]
  node_mp4["Rendered MP4"]
end

subgraph group_enhance["Captions and Effects"]
  node_captions["Word-timed captions<br/>[captions.py]"]
  node_captiondata["Caption data"]
  node_fx["Remotion effects<br/>[Root.tsx]"]
  node_overlay["Overlay compositing<br/>[overlay.sh]"]
  node_poster["Poster frame<br/>[poster.sh]"]
end

subgraph group_assistant["AI Authoring"]
  node_skill["Claude skill<br/>[SKILL.md]"]
end

node_author(("Reel author"))

node_author -->|"creates with"| node_starter
node_author -->|"writes scenes"| node_reel
node_author -->|"can invoke"| node_skill
node_skill -->|"plans and writes"| node_reel
node_musicgen -->|"generates"| node_bedfile
node_synth -->|"uses"| node_beatmix
node_bedfile -->|"loads"| node_beatmix
node_beatmix -->|"writes"| node_mixfile
node_sarvam -.->|"generates"| node_voice
node_voice -->|"provides clips"| node_captions
node_captions -->|"writes timings"| node_captiondata
node_captiondata -->|"renders pages"| node_runtime
node_reel -->|"defines scenes"| node_runtime
node_runtime -->|"registers timeline"| node_bridge
node_bridge -->|"enables check/render"| node_hyperframes
node_hyperframes -->|"renders"| node_mp4
node_fx -->|"renders effects for"| node_overlay
node_overlay -->|"composites onto"| node_mp4
node_hyperframes -.->|"feeds frame selection"| node_poster
node_mixfile -->|"provides soundtrack"| node_hyperframes

click node_starter "https://github.com/nikhilcherry/kinetix/blob/main/template/index.html"
click node_reel "https://github.com/nikhilcherry/kinetix/blob/main/template/index.html"
click node_skill "https://github.com/nikhilcherry/kinetix/blob/main/skill/kinetix/SKILL.md"
click node_musicgen "https://github.com/nikhilcherry/kinetix/blob/main/music/hypebeat.py"
click node_synth "https://github.com/nikhilcherry/kinetix/blob/main/template/music.py"
click node_beatmix "https://github.com/nikhilcherry/kinetix/blob/main/music/hits.py"
click node_captions "https://github.com/nikhilcherry/kinetix/blob/main/captions/captions.py"
click node_runtime "https://github.com/nikhilcherry/kinetix/blob/main/runtime/kinetix.js"
click node_bridge "https://github.com/nikhilcherry/kinetix/blob/main/bridge/hf-bridge.js"
click node_fx "https://github.com/nikhilcherry/kinetix/blob/main/fx/src/Root.tsx"
click node_overlay "https://github.com/nikhilcherry/kinetix/blob/main/tools/overlay.sh"
click node_poster "https://github.com/nikhilcherry/kinetix/blob/main/tools/poster.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_starter,node_reel toneBlue
class node_musicgen,node_synth,node_beatmix,node_bedfile,node_mixfile,node_sarvam,node_voice toneAmber
class node_runtime,node_bridge,node_hyperframes,node_mp4 toneMint
class node_captions,node_captiondata,node_fx,node_overlay,node_poster toneRose
class node_skill,node_author toneIndigo
```

## Components

### Reel Authoring

- [Starter page](https://github.com/nikhilcherry/kinetix/blob/main/template/index.html): `template/index.html`
- [Reel scenes](https://github.com/nikhilcherry/kinetix/blob/main/template/index.html): `template/index.html`

### Soundtrack and Voice

- [MusicGen beds](https://github.com/nikhilcherry/kinetix/blob/main/music/hypebeat.py): `music/hypebeat.py`
- [Synth soundtrack](https://github.com/nikhilcherry/kinetix/blob/main/template/music.py): `template/music.py`
- [Beat-grid mixer](https://github.com/nikhilcherry/kinetix/blob/main/music/hits.py): `music/hits.py`
- **Audio bed**
- **Mixed soundtrack**
- **Sarvam TTS**
- **Voice clips**

### Scene and Render

- [Timeline runtime](https://github.com/nikhilcherry/kinetix/blob/main/runtime/kinetix.js): `runtime/kinetix.js`
- [HyperFrames bridge](https://github.com/nikhilcherry/kinetix/blob/main/bridge/hf-bridge.js): `bridge/hf-bridge.js`
- **HyperFrames check/render**
- **Rendered MP4**

### Captions and Effects

- [Word-timed captions](https://github.com/nikhilcherry/kinetix/blob/main/captions/captions.py): `captions/captions.py`
- **Caption data**
- [Remotion effects](https://github.com/nikhilcherry/kinetix/blob/main/fx/src/Root.tsx): `fx/src/Root.tsx`
- [Overlay compositing](https://github.com/nikhilcherry/kinetix/blob/main/tools/overlay.sh): `tools/overlay.sh`
- [Poster frame](https://github.com/nikhilcherry/kinetix/blob/main/tools/poster.sh): `tools/poster.sh`

### AI Authoring

- [Claude skill](https://github.com/nikhilcherry/kinetix/blob/main/skill/kinetix/SKILL.md): `skill/kinetix/SKILL.md`

### Other components

- **Reel author**

## Connections

- Reel author → Starter page: creates with (evidence: `README.md`)
- Reel author → Reel scenes: writes scenes (evidence: `README.md`)
- Reel author → Claude skill: can invoke (evidence: `README.md`)
- Claude skill → Reel scenes: plans and writes (evidence: `README.md`)
- MusicGen beds → Audio bed: generates (evidence: `README.md`)
- Synth soundtrack → Beat-grid mixer: uses (evidence: `template/music.py`)
- Audio bed → Beat-grid mixer: loads (evidence: `README.md`)
- Beat-grid mixer → Mixed soundtrack: writes (evidence: `README.md`)
- Sarvam TTS → Voice clips: generates
- Voice clips → Word-timed captions: provides clips (evidence: `captions/captions.py`)
- Word-timed captions → Caption data: writes timings (evidence: `captions/captions.py`)
- Caption data → Timeline runtime: renders pages (evidence: `runtime/kinetix.js`)
- Reel scenes → Timeline runtime: defines scenes (evidence: `README.md`)
- Timeline runtime → HyperFrames bridge: registers timeline (evidence: `runtime/kinetix.js`)
- HyperFrames bridge → HyperFrames check/render: enables check/render (evidence: `README.md`)
- HyperFrames check/render → Rendered MP4: renders (evidence: `README.md`)
- Remotion effects → Overlay compositing: renders effects for (evidence: `README.md`)
- Overlay compositing → Rendered MP4: composites onto (evidence: `README.md`)
- HyperFrames check/render → Poster frame: feeds frame selection (evidence: `README.md`)
- Mixed soundtrack → HyperFrames check/render: provides soundtrack (evidence: `README.md`)
