docs: add Remotion quickstart guide

2026-09-09 17:38:21 +09:00
parent 74b70967a1
commit d25e693a4a
2 changed files with 115 additions and 14 deletions
@@ -1,24 +1,50 @@
 # Video-related files for NCMR songs

-This repo houses the video-related, code-like files for NCMR music videos. 
+This repo houses the code-like files for NCMR music videos. Binary assets live elsewhere.
+
+## Structure
+
+### `master` branch — shared template
+
+This branch holds the common scaffolding:
+
+- **Remotion project** — entry point, root component, and a placeholder composition
+- **`ffmpeg.sh`** — helper for baking ASS subtitles or bypassing with static image + audio
+- **`src/lrc2srt.ts`** — legacy LRC → SRT subtitle converter
+- **Build config** — TypeScript, ESLint, Prettier, Remotion studio
+
+### 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.
+```
+
+The `master` branch remains protected and mostly immutable. Song branches are independent.

 ## Guideline

-### gitignored (not tracked here)
- binary input assets (audio, image, fonts, material video clips if any)
- video output
+### Git-ignored (not tracked here)

-For untracked input assets, a bill of materials listing everything and explaining what each is will be mandatory.  
+- Binary input assets (audio, images, fonts, material video clips)
+- Video output (`out/`, rendered files)

-### branching rule
+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.

-This repo has specialised local branching rules and will supersede any generic git operation conventions.
+### Branching

- `master` serves as the minimal template and remain protected and mostly immutable
-  - [Remotion](https://www.remotion.dev/) project scaffolding
-  - `ffmpeg` helper script for baking in `ass` styled subtitles or bypassing the Remotion route (static image + audio)
-  - legacy lrc->srt conversion script
+- `master` — minimal template, protected
+- `<song>/master` — song-specific work
+- `<song>/<feature>` — parallel features for a song

- for each song, a song root named `<song-name>/master` should be created, for the very least
-  - usually, working on a song root incrementally is the norm and totally acceptable
-  - branches for parallel features (e.g. `<song-name>/synced-lyrics-remotion`, `<song-name>/overlay-ass`) may be created.
+This repo's branching rules supersede any generic git operation conventions.
@@ -0,0 +1,75 @@
+# Remotion Quickstart
+
+## Prerequisites
+
+- Node.js 18+
+- ffmpeg installed on your system
+
+## Getting started
+
+```bash
+npm install          # install dependencies
+npm run dev          # start Remotion Studio
+```
+
+Remotion Studio opens at **http://localhost:3000** in your browser.
+
+## Commands
+
+| Command              | What it does                                 |
+|----------------------|----------------------------------------------|
+| `npm run dev`        | Starts Remotion Studio (live preview UI)     |
+| `npm run build`      | Bundles the project for production           |
+| `npx remotion render`| Renders a video from the command line        |
+| `npx remotion upgrade` | Upgrades all Remotion packages to latest   |
+
+## Remotion Studio
+
+`npm run dev` starts the Studio — a browser-based editor where you can:
+
+- Preview compositions in real time
+- Scrub through frames
+- Change props and see changes instantly
+- Render videos from the browser
+
+The Studio auto-reloads on file changes. No manual refresh needed.
+
+## Project structure
+
+```
+.
+├── src/
+│   ├── index.ts          # Entry point — calls registerRoot()
+│   ├── Root.tsx          # React root component
+│   ├── Composition.tsx   # Composition definitions (placeholder)
+│   └── lrc2srt.ts        # LRC → SRT subtitle converter
+├── package.json          # Remotion + React + Tailwind deps
+├── remotion.config.ts    # CLI config (rspack, jpeg output format)
+├── tsconfig.json         # TypeScript (strict, ES2018)
+└── ffmpeg.sh             # Helper for ASS subtitle baking
+```
+
+## Compositions
+
+Compositions are defined in `src/Composition.tsx`. Each has:
+
+- **id** — unique name
+- **durationInFrames** — length in frames
+- **fps** — frames per second
+- **width/height** — resolution
+
+The placeholder is 1280×720 at 30fps, 60 frames (2 seconds).
+
+## Rendering a video
+
+```bash
+npx remotion render src/index.ts MyComp out/video.mp4
+```
+
+Replace `MyComp` with your composition ID. The output goes to `out/`.
+
+## Next steps
+
+- [Remotion docs](https://www.remotion.dev/docs)
+- [Compositions guide](https://www.remotion.dev/docs/the-introduction-video)
+- [Props guide](https://www.remotion.dev/docs/props)