Video-related files for NCMR songs

This repo houses the code-like files for NCMR music videos. Binary assets live elsewhere.

Structure

Repo state: workspace under construction. master is not locked in yet — it is still being assembled as the shared template. Until it is locked, any branching strategy is fine and template/tooling work can land on master directly. The branch conventions below describe the intended end state, not a rule currently in force.

master branch — shared template

This branch holds the common scaffolding:

• Remotion project — entry point, root component, and a placeholder composition
• scripts/ — Python toolchain (stdlib only) for subtitles, ffmpeg and asset manifests
• Build config — TypeScript, ESLint, Prettier, Remotion studio

src/ vs scripts/

Two directories, two jobs:

• src/ — Remotion input only. Everything here is compiled by tsc/Remotion and linted by npm run lint.
• scripts/ — operator tooling. Python, standard library only, run directly (python3 scripts/tools.py --help). Nothing here is part of the Remotion build.

Keep the boundary sharp: anything the video build compiles belongs in src/, and anything you run by hand belongs in scripts/.

Song branches

For each song, create a branch <song-name>/master (and optionally feature branches like <song-name>/synced-lyrics-remotion):

git checkout -b <song-name>/master

Copy the shared template into the song branch, then add song-specific files:

mkdir -p <song-name>
# Place your song-specific compositions, assets manifests, etc.

Once master is locked in it remains protected and mostly immutable. Until then, song branches are a rehearsal for that end state, not a requirement.

Guideline

Git-ignored (not tracked here)

• Binary input assets (audio, images, fonts, material video clips)
• Video output (out/, rendered files)
• package-lock.json — see below

For untracked input assets, a bill of materials listing everything and explaining what each file is will be mandatory. Keep it as BOM.md alongside your song assets.

Why there is no package-lock.json

Deliberate, not an oversight. Work happens on both Windows and Linux, and two things make a lockfile a liability here rather than a safeguard:

1. There is nothing for it to pin. Every dependency in package.json is pinned to an exact version — no ^, no ~. A plain npm install on any machine resolves to the same versions the lockfile would have recorded.
2. A lockfile is platform-specific. It records the resolved tree, including the optional native binaries for whichever OS generated it (@rollup/rollup-linux-x64-gnu, @rollup/rollup-win32-x64-msvc). Committed from Linux it is wrong on Windows, and npm ci refuses outright rather than adapting, since its whole purpose is to reproduce the recorded tree exactly.

So it would be strict about the wrong thing: breaking installs across machines while guarding versions that were never floating. Revisit this if a dependency is ever loosened to a range, or picks up transitive drift that exact pinning cannot control — at that point the lockfile earns its friction.

Branching

• master — minimal template (protected once locked in)
• <song>/master — song-specific work
• <song>/<feature> — parallel features for a song

Once master is locked, this repo's branching rules supersede any generic git operation conventions. Before that point, use whatever is convenient.