ncmr-songs-videos/README.md

# 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)

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.

### 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.