Skip to content

Commit 7fa9861

Browse files
michelpmichelp
committed
Update README with all tasks options documented in tables.
1 parent f5f54f2 commit 7fa9861

1 file changed

Lines changed: 187 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 187 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,243 @@
11
# IllustratedGraphBLAS
22

3-
To start create a virtual environment and install requirements:
3+
## Local Development Setup
4+
5+
Create a virtual environment and install requirements:
46

57
```
68
virtualenv --python=python3 .virt
79
. .virt/bin/activate
810
pip install -r requirements.txt
911
```
1012

11-
Manim quality settings are (l) low, (m) medium, (h), high and can be
12-
passed in the `--quality` argument.
13+
### Quality Settings
14+
15+
Manim quality settings control resolution and framerate. Pass them via the
16+
`--quality` argument (default is `l`):
17+
18+
| Flag | Resolution | Framerate |
19+
|------|-----------|-----------|
20+
| `l` | 480p | 15 fps |
21+
| `m` | 720p | 30 fps |
22+
| `h` | 1080p | 60 fps |
23+
24+
### Production Builds (Local)
25+
26+
By default, builds use Google TTS for free narration. Production builds use
27+
ElevenLabs TTS for high-quality narration. To enable production builds, add
28+
your ElevenLabs API key to a `.env` file in the repo root:
29+
30+
```
31+
ELEVEN_API_KEY=sk_your_key_here
32+
```
33+
34+
Then pass `--prod` to any build command. In production mode, the small
35+
chapter/scene indicator in the upper-right corner is hidden.
36+
37+
### Build Commands
38+
39+
#### `invoke build-scene`
1340

14-
To build a scene in a chapter:
41+
Renders a single Manim scene from a chapter. The scene is rendered using Manim
42+
with voiceover narration. In dev mode (default), a small chapter/scene
43+
indicator appears in the upper-right corner. The rendered video is saved to
44+
the chapter's `media/videos/` directory.
1545

1646
```
1747
invoke build-scene --chapter Chapter0 --scene Scene0 --quality l
1848
```
1949

20-
To build all scenes in a chapter:
50+
| Option | Description |
51+
|--------|-------------|
52+
| `--chapter` | Chapter directory name (e.g. `Chapter0`). Required. |
53+
| `--scene` | Scene file name without `.py` extension (e.g. `Scene0`). Required. |
54+
| `--quality` | Render quality: `l`, `m`, or `h`. Default: `l`. |
55+
| `--prod` | Use ElevenLabs TTS and hide the dev indicator. Requires `ELEVEN_API_KEY` in `.env`. |
56+
57+
#### `invoke build-chapter`
58+
59+
Builds all scenes in a chapter sequentially, then stitches them into a single
60+
video file. Scenes are discovered by finding all `Scene*.py` files in the
61+
chapter directory and sorting them by number. A configurable pause is inserted
62+
between scene builds to respect ElevenLabs API concurrency limits.
2163

2264
```
2365
invoke build-chapter --chapter Chapter0 --quality l
2466
```
2567

26-
To build all chapters:
68+
| Option | Description |
69+
|--------|-------------|
70+
| `--chapter` | Chapter directory name (e.g. `Chapter0`). Required. |
71+
| `--quality` | Render quality: `l`, `m`, or `h`. Default: `l`. |
72+
| `--pause-time` | Seconds to wait between scene builds. Default: `3`. Set to `0` for CI builds. |
73+
| `--prod` | Use ElevenLabs TTS and hide the dev indicator. |
74+
| `--no-stitch` | Build all scenes but skip stitching them into a final video. |
75+
76+
#### `invoke build-all`
77+
78+
Builds every chapter in the repository. Iterates through all directories
79+
matching `Chapter*` in sorted order, calling `build-chapter` for each one.
2780

2881
```
2982
invoke build-all --quality l
3083
```
3184

32-
To stich all scenes in a chapter final video of a given quality:
85+
| Option | Description |
86+
|--------|-------------|
87+
| `--quality` | Render quality: `l`, `m`, or `h`. Default: `l`. |
88+
| `--prod` | Use ElevenLabs TTS and hide the dev indicator. |
89+
90+
#### `invoke stitch-chapter`
91+
92+
Concatenates all rendered scene videos for a chapter into a single MP4 file
93+
using ffmpeg. Finds all `Scene*/[resolution]/Scene*.mp4` files in the
94+
chapter's `media/videos/` directory, sorts them by scene number, and produces
95+
a final video at `docs/ChapterN_[resolution].mp4`.
3396

3497
```
3598
invoke stitch-chapter --chapter Chapter0 --quality l
3699
```
37100

38-
To stich all chapters with a given quality:
101+
| Option | Description |
102+
|--------|-------------|
103+
| `--chapter` | Chapter directory name (e.g. `Chapter0`). Required. |
104+
| `--quality` | Determines which resolution folder to stitch from: `l` = 480p15, `m` = 720p30, `h` = 1080p60. Default: `l`. |
105+
106+
#### `invoke stitch-all`
107+
108+
Stitches all chapters. Iterates through all `Chapter*` directories in sorted
109+
order, calling `stitch-chapter` for each one.
39110

40111
```
41112
invoke stitch-all --quality l
42113
```
43114

44-
To render thumbnails:
115+
| Option | Description |
116+
|--------|-------------|
117+
| `--quality` | Resolution to stitch. Default: `l`. |
45118

46-
```
47-
invoke render-thumbnails
48-
```
119+
#### `invoke clean-chapter`
49120

50-
To clean all media in a chapter:
121+
Recursively deletes all files and subdirectories inside a chapter's `media/`
122+
folder. This removes all rendered videos, cached LaTeX, generated images, and
123+
voiceover audio files for that chapter. The source `.py` files are not
124+
affected.
51125

52126
```
53127
invoke clean-chapter --chapter Chapter0
54128
```
55129

56-
To clean all chapters:
130+
| Option | Description |
131+
|--------|-------------|
132+
| `--chapter` | Chapter directory name (e.g. `Chapter0`). Required. |
133+
134+
#### `invoke clean-all`
135+
136+
Cleans every chapter's media directory. Iterates through all `Chapter*`
137+
directories in sorted order, calling `clean-chapter` for each one.
57138

58139
```
59140
invoke clean-all
60141
```
61142

62-
To clean, build, stitch and render all thumbnails:
143+
No options.
144+
145+
#### `invoke render-thumbnails`
146+
147+
Renders a static thumbnail image for each chapter by running each chapter's
148+
`Thumb.py` file with Manim's screenshot mode (`-s`). The resulting PNG is
149+
saved to `docs/ChapterN.png` for use on the site.
150+
151+
```
152+
invoke render-thumbnails --quality l
153+
```
154+
155+
| Option | Description |
156+
|--------|-------------|
157+
| `--quality` | Render quality for the thumbnail. Default: `l`. |
158+
159+
#### `invoke all`
160+
161+
Full rebuild pipeline. Builds all chapters, stitches all final videos, and
162+
renders all thumbnails. Equivalent to running `build-all`, `stitch-all`, and
163+
`render-thumbnails` in sequence.
63164

64165
```
65166
invoke all --quality l
66167
```
67168

169+
| Option | Description |
170+
|--------|-------------|
171+
| `--quality` | Render quality: `l`, `m`, or `h`. Default: `l`. |
172+
| `--prod` | Use ElevenLabs TTS and hide the dev indicator. |
173+
174+
#### `invoke demo`
175+
176+
Renders a quick demo of a `scene_utils` component for testing and development.
177+
Each utility registered in `_demos/demo.py` can be previewed in isolation
178+
without building a full chapter scene.
179+
180+
```
181+
invoke demo --util create_sparse_matrix --quality l
182+
invoke demo --list
183+
```
184+
185+
| Option | Description |
186+
|--------|-------------|
187+
| `--util` | Name of the scene_utils component to demo (e.g. `create_sparse_matrix`). |
188+
| `--quality` | Render quality: `l`, `m`, or `h`. Default: `l`. |
189+
| `--list` | Print all available demo utilities and exit. |
190+
191+
#### `invoke notebooks`
192+
193+
Launches the Jupyter notebook browser, opening the interactive GraphBLAS
194+
tutorial index at `notebooks/index.ipynb`.
195+
196+
```
197+
invoke notebooks
198+
```
199+
200+
No options.
201+
202+
## CI/CD Build System
203+
204+
Videos are built automatically by GitHub Actions and deployed to GitHub Pages.
205+
Video files are not stored in git.
206+
207+
### Dev and Prod Views
208+
209+
The site has two views, built from the same source but with different videos:
210+
211+
- **Prod** (root URL) — production-quality narration via ElevenLabs TTS.
212+
Updated only when a manual prod build is triggered.
213+
- **Dev** (`/dev/` path) — development narration via Google TTS (free).
214+
Updated automatically on every push to `main` that changes chapter source files.
215+
216+
### Automatic Builds (Dev)
217+
218+
Any push to `main` that modifies chapter source files, `scene_utils/`, `imgs/`,
219+
`docs/*.md`, `mkdocs.yml`, `manim.cfg`, or `requirements.txt` triggers a dev
220+
build. Only chapters with source changes are rebuilt; unchanged chapters use
221+
cached videos from previous runs.
222+
223+
### Manual Builds
224+
225+
Go to **Actions > Build Videos and Deploy Site > Run workflow** to trigger a
226+
manual build. Options:
227+
228+
- **chapters** — comma-separated chapter numbers to rebuild (e.g. `0,3,5`) or
229+
`all` (default)
230+
- **prod** — check this box to build with ElevenLabs TTS and update the prod
231+
site at the root URL
68232

233+
### Required Secrets for Prod Builds
69234

235+
Prod builds require an ElevenLabs API key. Contributors who fork this repo need
236+
to add their own key:
70237

238+
1. Sign up at [elevenlabs.io](https://elevenlabs.io) and get an API key
239+
2. In your fork, go to **Settings > Secrets and variables > Actions**
240+
3. Add a repository secret named `ELEVEN_API_KEY` with your key
71241

242+
Without this secret, dev builds (Google TTS) still work. Only prod builds
243+
require the ElevenLabs key.

0 commit comments

Comments
 (0)