# gaebalai/study-recoding-pipeline architecture

> Architecture diagram of the GitHub repository gaebalai/study-recoding-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaebalai/study-recoding-pipeline
- Repository: https://github.com/gaebalai/study-recoding-pipeline

## Overview

1. **What this repository is**
   - A minimal two-stage media pipeline: it turns a script JSON into ElevenLabs speech, then uses Remotion to compose and render an MP4.
   - The repository is intentionally split between a **Node.js orchestration layer** and a **Remotion rendering layer**, with generated assets written to `output/` and `remotion/public/audio/`.

2. **Primary end-to-end flow**
   - The canonical path is:
     `examples/sample.json` → `scripts/synthesize.js` → `output/audio/<slug>/*.mp3` → `scripts/make-props.js` → `examples/<slug>.props.json` → Remotion render → `output/videos/<slug>.mp4`
   - This is the main architecture to diagram: input script, audio synthesis, props generation, static asset staging, video rendering, final MP4 output.

3. **Node.js pipeline boundary**
   - `scripts/` contains the pipeline executables that run outside Remotion.
   - `synthesize.js` is the integration point with ElevenLabs and is responsible for producing per-segment MP3 files.
   - `make-props.js` bridges the content model to the Remotion component model by converting the script JSON plus synthesis results into a props file.
   - `render.js` is the top-level orchestrator that loads env vars, coordinates the prior steps, and invokes Remotion rendering.

4. **External service boundary: ElevenLabs**
   - ElevenLabs is the only external SaaS dependency called at runtime.
   - The pipeline depends on API key, voice IDs, model selection, timeout, and retry behavior configured through environment variables and speaker config.
   - Speech synthesis is where cost and reliability concerns live; the repo includes caching and retry controls to reduce repeated API usage.

5. **Audio generation and caching**
   - Synthesized voice is stored under `output/audio/<slug>/`.
   - A per-slug cache file (`.cache.json`) deduplicates calls by hashing the combination of text, voice, model, and voice settings.
   - This makes audio generation idempotent across reruns unless the cache is cleared or forced regeneration is requested.

6. **Remotion project boundary**
   - `remotion/` is a self-contained Remotion app with its own package metadata, TypeScript config, linting, and build/runtime config.
   - `remotion/src/index.ts` and `remotion/src/Root.tsx` are the entry points for the Remotion composition.
   - `remotion/src/StudyVideo.tsx` is the main composition component that consumes props and assembles the final video.

7. **Composition data model**
   - `remotion/src/types.ts` defines the rendering-side types used to describe the script, speakers, and layout data.
   - `remotion/src/speaker-config.json` is a key configuration boundary: it maps logical speaker keys to ElevenLabs voice IDs, model IDs, and voice settings.
   - Environment variables can override parts of this config, but per-speaker settings take precedence where supported.

8. **Static asset staging for rendering**
   - Remotion reads audio as static files, so synthesized MP3s are copied into `remotion/public/audio/`.
   - This is a deliberate boundary between generated audio and the renderer’s asset lookup mechanism.
   - The repository also includes `remotion/public/characters/` for placeholder speaker imagery used in the sample video layouts.

9. **Input examples and layout coverage**
   - `examples/` contains sample script JSON files that illustrate the supported layout types: bullets/code, compare, image, table, and video.
   - These examples are both documentation and test fixtures for the rendering pipeline.
   - `examples/sample-video.json` highlights an extra asset dependency: the user must supply a local clip for embedded video content.

10. **Generated artifacts and cleanliness**
   - `output/` is the primary build output directory for both audio and rendered video.
   - `examples/*.props.json` is generated render input, not source.
   - The README’s cleanup commands show that the system expects these artifacts to be disposable and reproducible from source inputs.

11. **Configuration and execution environment**
   - The repo is Node-based, with the Remotion app requiring a separate install under `remotion/`.
   - `.env.example` and the scripts’ automatic `.env` loading indicate a local-file configuration model rather than a centralized config service.
   - The architecture relies on environment variables to control the runtime behavior of synthesis and render steps without changing source code.

12. **Docs as operational support**
   - `docs/quickstart.md`, `docs/setup.md`, and related authoring templates support the pipeline by defining input format and setup steps.
   - These docs do not add runtime components, but they clarify the contract between the script JSON authoring layer and the rendering pipeline.
   - For an architecture diagram, the docs can be shown as support material around the main flow rather than as executable subsystems.

Main entry points: [`scripts/synthesize.js`](https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/synthesize.js) (Speech synth), [`remotion/src/StudyVideo.tsx`](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/StudyVideo.tsx) (Study video), [`scripts/make-props.js`](https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/make-props.js) (Props builder), [`examples/sample.json`](https://github.com/gaebalai/study-recoding-pipeline/blob/main/examples/sample.json) (Sample script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs & examples"]
  node_examples_sample["Sample script<br/>script input<br/>[sample.json]"]
  node_examples_variants["Layout samples<br/>example scripts"]
  node_docs_support["Authoring docs<br/>[quickstart.md]"]
end

subgraph group_pipeline["Node pipeline"]
  node_scripts_render["Render runner<br/>orchestrator<br/>[render.js]"]
  node_scripts_synthesize["Speech synth<br/>audio pipeline<br/>[synthesize.js]"]
  node_scripts_make_props["Props builder<br/>data bridge<br/>[make-props.js]"]
end

subgraph group_remotion["Remotion app"]
  node_remotion_index["App entry<br/>runtime entry<br/>[index.ts]"]
  node_remotion_root["Root entry<br/>composition boot<br/>[Root.tsx]"]
  node_remotion_studyvideo["Study video<br/>composition<br/>[StudyVideo.tsx]"]
  node_remotion_types["Render types<br/>schema<br/>[types.ts]"]
  node_remotion_speaker_config["Speaker config<br/>voice map"]
  node_remotion_public_audio[("Audio staging<br/>static assets")]
  node_remotion_characters[("Character art<br/>static assets")]
end

subgraph group_outputs["Generated artifacts"]
  node_output_audio[("Synthesis output<br/>generated audio")]
  node_output_videos[("Video output<br/>rendered mp4")]
  node_examples_props["Props file<br/>generated props"]
end

subgraph group_config["Configuration"]
  node_env_example["Env template<br/>runtime config<br/>[.env.example]"]
end

subgraph group_external["External service"]
  node_elevenlabs(("ElevenLabs<br/>speech api"))
end

node_examples_sample -->|"script JSON"| node_scripts_synthesize
node_examples_variants -.->|"input patterns"| node_scripts_make_props
node_docs_support -.->|"authoring guide"| node_examples_sample
node_env_example -->|"env vars"| node_scripts_render
node_env_example -->|"api settings"| node_scripts_synthesize
node_scripts_render -->|"run first"| node_scripts_synthesize
node_scripts_synthesize -->|"speech request"| node_elevenlabs
node_elevenlabs -->|"MP3 files"| node_output_audio
node_output_audio -->|"audio manifest"| node_scripts_make_props
node_examples_sample -->|"content model"| node_scripts_make_props
node_scripts_make_props -->|"write props"| node_examples_props
node_examples_props -->|"render input"| node_remotion_index
node_remotion_index -->|"bootstrap"| node_remotion_root
node_remotion_root -->|"register comp"| node_remotion_studyvideo
node_remotion_speaker_config -->|"voice mapping"| node_remotion_studyvideo
node_remotion_types -.->|"data shapes"| node_remotion_studyvideo
node_remotion_public_audio -->|"static audio"| node_remotion_studyvideo
node_remotion_characters -->|"art assets"| node_remotion_studyvideo
node_scripts_render -->|"final render"| node_output_videos
node_scripts_synthesize -->|"copy audio"| node_remotion_public_audio
node_output_audio -->|"staged assets"| node_remotion_public_audio

click node_examples_sample "https://github.com/gaebalai/study-recoding-pipeline/blob/main/examples/sample.json"
click node_examples_variants "https://github.com/gaebalai/study-recoding-pipeline/blob/main/examples/sample-compare.json"
click node_docs_support "https://github.com/gaebalai/study-recoding-pipeline/blob/main/docs/quickstart.md"
click node_scripts_render "https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/render.js"
click node_scripts_synthesize "https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/synthesize.js"
click node_scripts_make_props "https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/make-props.js"
click node_remotion_index "https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/index.ts"
click node_remotion_root "https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/Root.tsx"
click node_remotion_studyvideo "https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/StudyVideo.tsx"
click node_remotion_types "https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/types.ts"
click node_remotion_speaker_config "https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/speaker-config.json"
click node_remotion_public_audio "https://github.com/gaebalai/study-recoding-pipeline/tree/main/remotion/public"
click node_remotion_characters "https://github.com/gaebalai/study-recoding-pipeline/tree/main/remotion/public/characters"
click node_env_example "https://github.com/gaebalai/study-recoding-pipeline/blob/main/.env.example"

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_examples_sample,node_examples_variants,node_docs_support toneBlue
class node_scripts_render,node_scripts_synthesize,node_scripts_make_props toneAmber
class node_remotion_index,node_remotion_root,node_remotion_studyvideo,node_remotion_types,node_remotion_speaker_config,node_remotion_public_audio,node_remotion_characters toneMint
class node_output_audio,node_output_videos,node_examples_props toneRose
class node_env_example toneIndigo
class node_elevenlabs toneTeal
```

## Components

### Inputs & examples

Source scripts, layout samples, and authoring docs that define the content contract.

- [Sample script](https://github.com/gaebalai/study-recoding-pipeline/blob/main/examples/sample.json): script input · Canonical script JSON used to drive the pipeline. · `examples/sample.json`
- [Layout samples](https://github.com/gaebalai/study-recoding-pipeline/blob/main/examples/sample-compare.json): example scripts · Representative inputs for compare, image, table, and video layouts. · `examples/sample-compare.json`
- [Authoring docs](https://github.com/gaebalai/study-recoding-pipeline/blob/main/docs/quickstart.md): docs · Setup and content guidance that define the expected input contract. · `docs/quickstart.md`

### Node pipeline

Scripts that synthesize audio, prepare Remotion props, and orchestrate the end-to-end run.

- [Render runner](https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/render.js): orchestrator · Top-level script that loads env vars, coordinates synthesis, and invokes video rendering. · `scripts/render.js`
- [Speech synth](https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/synthesize.js): audio pipeline · Calls ElevenLabs and writes per-segment MP3 files with caching and retry behavior. · `scripts/synthesize.js`
- [Props builder](https://github.com/gaebalai/study-recoding-pipeline/blob/main/scripts/make-props.js): data bridge · Converts script JSON plus synthesis results into Remotion-ready props. · `scripts/make-props.js`

### Remotion app

Self-contained rendering app that turns props and staged assets into video.

- [App entry](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/index.ts): runtime entry · TypeScript entrypoint for the Remotion app. · `remotion/src/index.ts`
- [Root entry](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/Root.tsx): composition boot · Remotion bootstrap that registers the composition tree. · `remotion/src/Root.tsx`
- [Study video](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/StudyVideo.tsx): composition · Main composition component that assembles the final video from props and staged assets. · `remotion/src/StudyVideo.tsx`
- [Render types](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/types.ts): schema · Type definitions for script, speakers, and layout data used by the renderer. · `remotion/src/types.ts`
- [Speaker config](https://github.com/gaebalai/study-recoding-pipeline/blob/main/remotion/src/speaker-config.json): voice map · Maps logical speakers to ElevenLabs voice IDs, model IDs, and voice settings. · `remotion/src/speaker-config.json`
- [Audio staging](https://github.com/gaebalai/study-recoding-pipeline/tree/main/remotion/public): static assets · Rendered MP3 files copied here so Remotion can read them as static media. · `remotion/public`
- [Character art](https://github.com/gaebalai/study-recoding-pipeline/tree/main/remotion/public/characters): static assets · Placeholder character imagery used by sample layouts. · `remotion/public/characters`

### Generated artifacts

Disposable build outputs produced by synthesis, props generation, and rendering.

- **Synthesis output**: generated audio · Per-slug audio files produced by synthesis and cached for reruns.
- **Video output**: rendered mp4 · Final rendered MP4 files produced by Remotion.
- **Props file**: generated props · Intermediate Remotion input generated from the script and synthesis results.

### Configuration

Environment and speaker mapping that control runtime behavior.

- [Env template](https://github.com/gaebalai/study-recoding-pipeline/blob/main/.env.example): runtime config · Example environment variables for API keys, model selection, timeout, and retry controls. · `.env.example`

### External service

Third-party SaaS used for speech synthesis.

- **ElevenLabs**: speech api · External speech synthesis service used to generate the narration audio.

## Connections

- Sample script → Speech synth: script JSON · The canonical input script feeds audio synthesis.
- Layout samples → Props builder: input patterns · Sample layouts document the supported content shapes.
- Authoring docs → Sample script: authoring guide · Docs explain how to author scripts consumed by the pipeline.
- Env template → Render runner: env vars · Local configuration controls synthesis and render behavior.
- Env template → Speech synth: api settings · API key and retry/timeout settings affect synthesis calls.
- Render runner → Speech synth: run first · The orchestrator invokes audio generation before rendering.
- Speech synth → ElevenLabs: speech request · Audio is generated through the external speech API.
- ElevenLabs → Synthesis output: MP3 files · Returned narration is stored in the audio output cache.
- Synthesis output → Props builder: audio manifest · Synthesized audio metadata is consumed when building render props.
- Sample script → Props builder: content model · The script structure is transformed into rendering props.
- Props builder → Props file: write props · The bridge emits Remotion-ready props as a generated file.
- Props file → App entry: render input · The generated props are loaded by the Remotion app.
- App entry → Root entry: bootstrap · The app entry initializes the composition tree.
- Root entry → Study video: register comp · Root exposes the main study video composition.
- Speaker config → Study video: voice mapping · Speaker configuration informs narration and voice selection.
- Render types → Study video: data shapes · Types define the props and layout contract used by the composition.
- Audio staging → Study video: static audio · The composition reads staged MP3 assets from the public directory.
- Character art → Study video: art assets · Placeholder imagery supports sample layouts.
- Render runner → Video output: final render · The orchestrator triggers the MP4 render output.
- Speech synth → Audio staging: copy audio · Generated MP3s are staged into Remotion's static asset directory.
- Synthesis output → Audio staging: staged assets · Audio output is mirrored into the renderer's public path.
