From d25e693a4affd7defc336a25a7fc457e01d1ab87 Mon Sep 17 00:00:00 2001
From: Irene <irene@novoyuuparosk.org>
Date: Wed, 9 Sep 2026 17:38:21 +0900
Subject: [PATCH] docs: add Remotion quickstart guide

---
 README.md              | 54 ++++++++++++++++++++++--------
 REMOTION-QUICKSTART.md | 75 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+), 14 deletions(-)
 create mode 100644 REMOTION-QUICKSTART.md

diff --git a/README.md b/README.md
index 6c69dcd..81a723d 100644
--- a/README.md
+++ b/README.md
@@ -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.
diff --git a/REMOTION-QUICKSTART.md b/REMOTION-QUICKSTART.md
new file mode 100644
index 0000000..428fc22
--- /dev/null
+++ b/REMOTION-QUICKSTART.md
@@ -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)