# mexicat/pdoom-video architecture

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

- Interactive diagram: https://gitdiagram.com/mexicat/pdoom-video
- Repository: https://github.com/mexicat/pdoom-video
- Video tour (about a minute): https://gitdiagram.com/mexicat/pdoom-video/video

## Overview

This repository creates a deterministic, lyric-synchronized music video: audio and lyric analysis produce timing data; the timeline uses those data to schedule illustrated plates; the renderer composes frames for browser preview or offline export. The graph groups related plates rather than listing every scene module. Analysis and rendering links reflect the README and sampled source; unsampled scene internals are represented only at their supported directory path.

Main entry points: [`app/src/engine/engine.ts`](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/engine.ts) (Render engine), [`app/src/engine/scene.ts`](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/scene.ts) (Scene interface), [`app/src/timeline.ts`](https://github.com/mexicat/pdoom-video/blob/main/app/src/timeline.ts) (Scene timeline), [`app/src/main.ts`](https://github.com/mexicat/pdoom-video/blob/main/app/src/main.ts) (Preview and export entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Audio analysis"]
  node_lyrictext["Source lyrics<br/>[lyrics.src.js]"]
  node_align["Lyric alignment<br/>[align.py]"]
  node_analyze["Music analysis<br/>[analyze.py]"]
end

subgraph group_edit["Timing and edit"]
  node_lyricdata["Word timings<br/>[lyrics.json]"]
  node_audiodata["Beat and audio data<br/>[audio.json]"]
  node_timeline["Scene timeline<br/>[timeline.ts]"]
end

subgraph group_render["Frame renderer"]
  node_entry["Preview and export entry<br/>[main.ts]"]
  node_engine["Render engine<br/>[engine.ts]"]
  node_audio["Audio data access<br/>[audio.ts]"]
  node_lyrics["Lyric data access<br/>[lyrics.ts]"]
  node_sceneapi["Scene interface<br/>[scene.ts]"]
  node_gpu["WebGL compositor<br/>[gl.ts]"]
  node_post["Post-processing<br/>[post.ts]"]
  node_hud["Karaoke and HUD<br/>[hud.ts]"]
  node_fonts["Typography<br/>[type.ts]"]
  node_stroke["Stroke fonts<br/>[stroke.ts]"]
  node_renderdriver["Offline render driver<br/>[render.ts]"]
end

subgraph group_plates["Video plates"]
  node_plates1["Opening and prompts"]
  node_plates2["Hooks and rooms"]
  node_plates3["Space and ascent"]
  node_plates4["Turn and paperclips"]
  node_plates5["Fuse and training"]
  node_plates6["Loom and outro"]
end

node_song(("Song audio"))
node_viewer(("Browser viewer"))
node_video["Encoded video"]

node_song -.->|"analyzes vocals"| node_align
node_lyrictext -->|"aligns words"| node_align
node_align -->|"writes timings"| node_lyricdata
node_song -.->|"analyzes stems"| node_analyze
node_analyze -->|"writes beat data"| node_audiodata
node_lyricdata -->|"anchors cuts"| node_timeline
node_audiodata -->|"snaps beats"| node_timeline
node_timeline -->|"builds edit"| node_entry
node_entry -->|"initializes and drives"| node_engine
node_engine -->|"loads audio data"| node_audio
node_engine -->|"loads lyric data"| node_lyrics
node_engine -->|"requests entries"| node_timeline
node_engine -->|"loads and renders"| node_sceneapi
node_sceneapi -->|"implements plates"| node_plates1
node_sceneapi -->|"implements plates"| node_plates2
node_sceneapi -->|"implements plates"| node_plates3
node_sceneapi -->|"implements plates"| node_plates4
node_sceneapi -->|"implements plates"| node_plates5
node_sceneapi -->|"implements plates"| node_plates6
node_engine -->|"composites frames"| node_gpu
node_engine -->|"applies effects"| node_post
node_engine -->|"overlays captions"| node_hud
node_engine -->|"loads fonts"| node_fonts
node_engine -->|"loads stroke fonts"| node_stroke
node_viewer -->|"opens preview"| node_entry
node_renderdriver -->|"drives export mode"| node_entry
node_renderdriver -->|"encodes frames"| node_video

click node_lyrictext "https://github.com/mexicat/pdoom-video/blob/main/lyrics/lyrics.src.js"
click node_align "https://github.com/mexicat/pdoom-video/blob/main/analysis/align.py"
click node_analyze "https://github.com/mexicat/pdoom-video/blob/main/analysis/analyze.py"
click node_lyricdata "https://github.com/mexicat/pdoom-video/blob/main/data/lyrics.json"
click node_audiodata "https://github.com/mexicat/pdoom-video/blob/main/data/audio.json"
click node_timeline "https://github.com/mexicat/pdoom-video/blob/main/app/src/timeline.ts"
click node_entry "https://github.com/mexicat/pdoom-video/blob/main/app/src/main.ts"
click node_engine "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/engine.ts"
click node_audio "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/audio.ts"
click node_lyrics "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/lyrics.ts"
click node_sceneapi "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/scene.ts"
click node_gpu "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/gl.ts"
click node_post "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/post.ts"
click node_hud "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/hud.ts"
click node_fonts "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/type.ts"
click node_stroke "https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/stroke.ts"
click node_plates1 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_plates2 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_plates3 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_plates4 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_plates5 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_plates6 "https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes"
click node_renderdriver "https://github.com/mexicat/pdoom-video/blob/main/app/scripts/render.ts"

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_lyrictext,node_align,node_analyze,node_viewer toneBlue
class node_lyricdata,node_audiodata,node_timeline toneAmber
class node_entry,node_engine,node_audio,node_lyrics,node_sceneapi,node_gpu,node_post,node_hud,node_fonts,node_stroke,node_renderdriver toneMint
class node_plates1,node_plates2,node_plates3,node_plates4,node_plates5,node_plates6 toneRose
class node_song,node_video toneIndigo
```

## Components

### Audio analysis

- [Source lyrics](https://github.com/mexicat/pdoom-video/blob/main/lyrics/lyrics.src.js): `lyrics/lyrics.src.js`
- [Lyric alignment](https://github.com/mexicat/pdoom-video/blob/main/analysis/align.py): `analysis/align.py`
- [Music analysis](https://github.com/mexicat/pdoom-video/blob/main/analysis/analyze.py): `analysis/analyze.py`

### Timing and edit

- [Word timings](https://github.com/mexicat/pdoom-video/blob/main/data/lyrics.json): `data/lyrics.json`
- [Beat and audio data](https://github.com/mexicat/pdoom-video/blob/main/data/audio.json): `data/audio.json`
- [Scene timeline](https://github.com/mexicat/pdoom-video/blob/main/app/src/timeline.ts): `app/src/timeline.ts`

### Frame renderer

- [Preview and export entry](https://github.com/mexicat/pdoom-video/blob/main/app/src/main.ts): `app/src/main.ts`
- [Render engine](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/engine.ts): `app/src/engine/engine.ts`
- [Audio data access](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/audio.ts): `app/src/engine/audio.ts`
- [Lyric data access](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/lyrics.ts): `app/src/engine/lyrics.ts`
- [Scene interface](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/scene.ts): `app/src/engine/scene.ts`
- [WebGL compositor](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/gl.ts): `app/src/engine/gl.ts`
- [Post-processing](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/post.ts): `app/src/engine/post.ts`
- [Karaoke and HUD](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/hud.ts): `app/src/engine/hud.ts`
- [Typography](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/type.ts): `app/src/engine/type.ts`
- [Stroke fonts](https://github.com/mexicat/pdoom-video/blob/main/app/src/engine/stroke.ts): `app/src/engine/stroke.ts`
- [Offline render driver](https://github.com/mexicat/pdoom-video/blob/main/app/scripts/render.ts): `app/scripts/render.ts`

### Video plates

- [Opening and prompts](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`
- [Hooks and rooms](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`
- [Space and ascent](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`
- [Turn and paperclips](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`
- [Fuse and training](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`
- [Loom and outro](https://github.com/mexicat/pdoom-video/tree/main/app/src/scenes): `app/src/scenes`

### Other components

- **Song audio**
- **Browser viewer**
- **Encoded video**

## Connections

- Song audio → Lyric alignment: analyzes vocals
- Source lyrics → Lyric alignment: aligns words
- Lyric alignment → Word timings: writes timings
- Song audio → Music analysis: analyzes stems
- Music analysis → Beat and audio data: writes beat data
- Word timings → Scene timeline: anchors cuts
- Beat and audio data → Scene timeline: snaps beats
- Scene timeline → Preview and export entry: builds edit
- Preview and export entry → Render engine: initializes and drives
- Render engine → Audio data access: loads audio data
- Render engine → Lyric data access: loads lyric data
- Render engine → Scene timeline: requests entries
- Render engine → Scene interface: loads and renders
- Scene interface → Opening and prompts: implements plates
- Scene interface → Hooks and rooms: implements plates
- Scene interface → Space and ascent: implements plates
- Scene interface → Turn and paperclips: implements plates
- Scene interface → Fuse and training: implements plates
- Scene interface → Loom and outro: implements plates
- Render engine → WebGL compositor: composites frames
- Render engine → Post-processing: applies effects
- Render engine → Karaoke and HUD: overlays captions
- Render engine → Typography: loads fonts
- Render engine → Stroke fonts: loads stroke fonts
- Browser viewer → Preview and export entry: opens preview
- Offline render driver → Preview and export entry: drives export mode
- Offline render driver → Encoded video: encodes frames