@machinal/mcp 0.0.0-stage → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (174) hide show
  1. package/README.md +366 -2
  2. package/bin/machinal-mcp.mjs +19 -0
  3. package/bin/machinal-stdio.mjs +14 -0
  4. package/package.json +47 -4
  5. package/skills/machinal-cinema/SKILL.md +18 -0
  6. package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
  7. package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
  8. package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
  9. package/skills/machinal-cinema/references/film-library/README.md +13 -0
  10. package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
  11. package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
  12. package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
  13. package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
  14. package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
  15. package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
  16. package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
  17. package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
  18. package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
  19. package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
  20. package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
  21. package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
  22. package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
  23. package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
  24. package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
  25. package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
  26. package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
  27. package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
  28. package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
  29. package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
  30. package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
  31. package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
  32. package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
  33. package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
  34. package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
  35. package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
  36. package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
  37. package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
  38. package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
  39. package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
  40. package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
  41. package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
  42. package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
  43. package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
  44. package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
  45. package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
  46. package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
  47. package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
  48. package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
  49. package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
  50. package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
  51. package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
  52. package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
  53. package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
  54. package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
  55. package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
  56. package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
  57. package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
  58. package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
  59. package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
  60. package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
  61. package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
  62. package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
  63. package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
  64. package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
  65. package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
  66. package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
  67. package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
  68. package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
  69. package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
  70. package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
  71. package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
  72. package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
  73. package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
  74. package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
  75. package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
  76. package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
  77. package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
  78. package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
  79. package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
  80. package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
  81. package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
  82. package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
  83. package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
  84. package/skills/machinal-cinema/references/film-styles.json +1322 -0
  85. package/skills/machinal-cinema/references/film-techniques.json +107 -0
  86. package/skills/machinal-cinema/references/workflow.md +58 -0
  87. package/skills/machinal-credits/SKILL.md +24 -0
  88. package/skills/machinal-editing/SKILL.md +43 -0
  89. package/skills/machinal-editing/references/brief.md +98 -0
  90. package/skills/machinal-editing/references/effects.md +58 -0
  91. package/skills/machinal-editing/references/looks-motion.md +37 -0
  92. package/skills/machinal-editing/references/styles.json +15 -0
  93. package/skills/machinal-editing/references/styles.md +16 -0
  94. package/skills/machinal-editing/references/transitions.md +46 -0
  95. package/skills/machinal-editing/references/workflow.md +43 -0
  96. package/skills/machinal-media/SKILL.md +23 -0
  97. package/skills/machinal-media/references/workflow.md +160 -0
  98. package/skills/machinal-recipes/SKILL.md +32 -0
  99. package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
  100. package/skills/machinal-recipes/references/commands.md +45 -0
  101. package/skills/machinal-recipes/references/example.edit.yaml +26 -0
  102. package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
  103. package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
  104. package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
  105. package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
  106. package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
  107. package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
  108. package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
  109. package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
  110. package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
  111. package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
  112. package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
  113. package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
  114. package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
  115. package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
  116. package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
  117. package/skills/machinal-recipes/references/examples.md +28 -0
  118. package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
  119. package/skills/machinal-recipes/references/text-audio.md +118 -0
  120. package/skills/machinal-recipes/references/yaml.md +72 -0
  121. package/skills/machinal-review/SKILL.md +18 -0
  122. package/skills/machinal-review/references/production.md +146 -0
  123. package/skills/machinal-scenes/SKILL.md +44 -0
  124. package/skills/machinal-scenes/references/authoring.md +97 -0
  125. package/skills/machinal-scenes/references/runtime.md +136 -0
  126. package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
  127. package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
  128. package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
  129. package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
  130. package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
  131. package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
  132. package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
  133. package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
  134. package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
  135. package/skills/machinal-scenes/references/scene-templates.json +178 -0
  136. package/skills/machinal-scenes/references/scene-templates.md +50 -0
  137. package/skills/machinal-scenes/references/workflow.md +206 -0
  138. package/skills/machinal-support/SKILL.md +42 -0
  139. package/src/bridge.mjs +287 -0
  140. package/src/cli.mjs +157 -0
  141. package/src/configuration.mjs +148 -0
  142. package/src/connection.mjs +187 -0
  143. package/src/credential-store.mjs +61 -0
  144. package/src/credits.mjs +86 -0
  145. package/src/docker.mjs +93 -0
  146. package/src/download.mjs +90 -0
  147. package/src/endpoints.mjs +3 -0
  148. package/src/errors.mjs +9 -0
  149. package/src/formats.mjs +140 -0
  150. package/src/keys.mjs +127 -0
  151. package/src/launch.mjs +29 -0
  152. package/src/local-setup.mjs +109 -0
  153. package/src/opencode-auth.mjs +246 -0
  154. package/src/opencode-checkpoints.mjs +90 -0
  155. package/src/opencode-configuration.mjs +53 -0
  156. package/src/opencode-media.mjs +139 -0
  157. package/src/opencode-plugin/index.mjs +7 -0
  158. package/src/opencode-plugin/package.json +5 -0
  159. package/src/opencode-recipes.mjs +130 -0
  160. package/src/opencode-routing.mjs +154 -0
  161. package/src/opencode-tools.mjs +30 -0
  162. package/src/opencode-workflow.mjs +32 -0
  163. package/src/presentation.mjs +31 -0
  164. package/src/prompts.mjs +32 -0
  165. package/src/reference-files.json +127 -0
  166. package/src/runtime.mjs +51 -0
  167. package/src/setup-options.mjs +69 -0
  168. package/src/setup-stdio.mjs +116 -0
  169. package/src/setup.mjs +173 -0
  170. package/src/skills.mjs +68 -0
  171. package/src/transfer-http.mjs +109 -0
  172. package/src/version.mjs +3 -0
  173. package/src/windows-key-prompt.mjs +37 -0
  174. package/src/windows-key-prompt.ps1 +77 -0
@@ -0,0 +1,117 @@
1
+ # 80s Cel Anime — Style Prompt
2
+
3
+ > Hand-painted cel animation from the golden age of Japanese OVAs, re-created in code: flat two-tone cels over airbrushed backgrounds, backlit neon, limited-animation timing, played back as a late-80s videotape on a CRT television.
4
+ > References (grammar only): 1980s Japanese OVA and TV cel animation in general (painted-background vs flat-cel contrast, backlit light, held drawings, speed grammar, city-pop openings). Borrow the era's craft, never a specific work's characters, mecha, logos, place names or signature shots.
5
+
6
+ ## 1. Essence, and what it is not
7
+
8
+ Four layers, and the contrast between them is the look:
9
+ - **Background painting**: soft airbrushed gradients, glowing windows, wet reflections; painted once at load (colour + emissive pair), then only slid.
10
+ - **Cel** (characters, vehicles, props): flat fills, **hard-edged** shadow and highlight shapes, **coloured** outlines, never pure black; stepped at 12 or 8 fps.
11
+ - **Light**: backlit cel (透過光): signs, lamps, title letters glowing *through* the frame; flares, halation.
12
+ - **Playback**: videotape on a CRT: chroma bleed, scanlines, grille, phosphor glow, darkened corners, faint noise.
13
+
14
+ If a frame looks like modern digital anime, one layer is missing. Not moe anime (round eyes, giant irises, hatched blush), not vector clip-art (uniform black lines, gradients in shapes), not a film-print pastiche (no gate weave or scratches: this is tape).
15
+
16
+ ## 2. Materials & rendering
17
+
18
+ **Cel rendering.** Fill, then a **hard** shadow crescent, then a **hard** highlight crescent, then the coloured outline. No gradients inside a cel shape (exception: one "harmony" painted still at a peak). Automatic shading: clip to the shape and fill `shape − shape shifted toward the light` with the shadow colour (even-odd); the same shifted away for the highlight and for a saturated neon **rim light** (2–4 px). Add hand-placed cast shadows. Outlines ~2–3 px at 1080p, scaled down (0.45–0.8×) in extreme close-ups. **Colour models per lighting** (色指定): define each character in daylight, derive other sets by multiplying lit / shadow / line separately, plus a backlit silhouette set with a warm rim.
19
+
20
+ **People the 80s way.** Construct the head (sphere + jaw): long egg-shaped face, soft-point chin, far eye foreshortened with a cheekbone turn in 3/4. **Almond** eyes near the vertical middle of the head, a thick upper lash line flicking outward, a tall oval layered iris, two highlights, long thin brows. Nose = a shadow plane + one stroke; one faint blush layer, never hatched. Hair in overlapping locks with sharp uneven tips over a wider dark under-layer, a continuous "angel ring" highlight with a zigzag lower edge. Lines: skin thin warm dark brown, hair dark purple; only hard props near-black. Emotion lives in brows, lid height, iris size, mouth corners and shoulders. Build and approve a **model sheet** first; draw every shot from the same head function.
21
+
22
+ **Backgrounds.** Painted once at load: sky gradients, airbrushed clouds with lit undersides, buildings or landscape with painted light sources, and always a matching **emissive plate** that slides with the colour plate. Wet ground = a flipped, blurred, streaked copy of the plate darkened with ripple bands. Generic sign words only, never brands. Moving plates get a light horizontal smear (~16 px) against strobing.
23
+
24
+ **Light and lens.** Bloom strongly from the emissive canvas, weakly from the colour canvas above ~0.9; tint the widest bloom red-orange (halation). Flares: star-burst, anamorphic streak, hexagonal ghosts through frame centre. Stamp every cel's silhouette in black onto the emissive canvas so glow never bleeds through it.
25
+
26
+ **Videotape + CRT, restrained and deterministic:** chroma bleed (sharp luma, horizontally blurred and slightly shifted chroma), fine scanlines anchored to output pixels whose gap shrinks on brights, a faint RGB grille, phosphor glow, darkened corners without curved borders, faint signal noise. Subtitles are composited inside the pass after grading. Two optional accents: a **power-on** (dot → line → picture) and **tracking noise** (a few frames of tearing, rolling band, vertical hop). Check moiré on a 720p downscale. Frame: full 16:9 as a theatrical feature (4:3 pillarbox is valid for an OVA feel).
27
+
28
+ ## 3. Colour logic
29
+
30
+ - Painted plates carry gradients and atmosphere; cels are flat, few-colour, saturated. Each time of day gets its own colour model, never a filter over the frame.
31
+ - The protagonist has **one accent colour** that pops in every lighting set. Line colours are dark versions of their fill.
32
+ - Skin gets its own colour in every set; multiplying daylight skin by a tint turns faces pink under neon.
33
+ - Examples: night city (indigo, violet, neon magenta, cyan, window gold); seaside noon (cobalt, white cumulus, sand, coral); classroom dusk (amber, chalk green, brown wood, purple shadows).
34
+
35
+ ## 4. Type & subtitles
36
+
37
+ - Subtitles live on the tape, composited inside the CRT pass: a semi-condensed sans (e.g. Barlow Semi Condensed 600, ~50–56 px), cream-yellow with a thick dark outline and soft shadow, ~96 px above the bottom; a second speaker may take a second colour and a small boxed tag. Hold ≥ max(1.8 s, speech + 0.6 s); a line yields to the next.
38
+ - Titles: heavy italic Latin in a **chrome gradient** (sky → white horizon line → violet → pink → gold), dark + neon outlines, optional katakana line (e.g. Dela Gothic One), glowing through the emissive layer, flickering on at 12 fps with a light sweep and a star glint.
39
+
40
+ ## 5. Motion quality
41
+
42
+ - **Characters on twos (12 fps)**; performance beats (blinks, eye openings, lip flaps, gestures) on threes (8 fps). Camera, light sweeps, flares and rain on ones (24 fps); a stepped camera judders.
43
+ - **Cycles**: hair and cloth as ribbons driven by a travelling sine, 4-drawing cycle (6 when calm); bounce = a 12 fps jitter of a few px.
44
+ - **Move light, not drawings**: coloured bands sweeping across a held cel (`source-atop`).
45
+ - **Impact frames**: 2 frames of an inverted or monochrome silhouette over radial lines, then the result.
46
+ - **Hold the peak**: a painted still with a slow pan, only cycles moving.
47
+ - Fast blinks (one 8 fps closed drawing); eye openings in three drawings; lip flaps of 3–4 shapes at 8 fps ending on a held expression.
48
+
49
+ ## 6. Camera grammar
50
+
51
+ A vocabulary, not a route. Opening and ending come from the topic.
52
+
53
+ | Move | What it expresses | Can serve |
54
+ |---|---|---|
55
+ | Multiplane crane over a tall plate | a world revealed layer by layer | arriving; descending into a place; rising above it |
56
+ | Side tracking, 3–4 parallax layers | steady momentum | a journey; a chase; progress |
57
+ | Rear view into a pseudo-3D canyon | speed, pressure ahead | a race; a tunnel; a countdown |
58
+ | Held bust with light bands | speed or tension without animation | a drive; waiting; a decision |
59
+ | Insert with bokeh and a sliding highlight | this object matters | a letter; a key; a ticket |
60
+ | Extreme close-up on eyes | resolve, recognition | a choice; a promise |
61
+ | Slow pan across a painted still | awe, a held breath | a peak; a memory; a landscape |
62
+ | Radial speed lines + one-beat freeze | the instant before impact | a leap; a collision; a goal |
63
+ | Truck-in through a window or screen | entering another world | a flashback; a broadcast; a dream |
64
+ | Locked two-shot with lip flaps | conversation | banter; a confession; an argument |
65
+ | An earlier composition repainted | what changed | after a storm; years later |
66
+
67
+ Cut on bars. Framing: cels readable against the painted plate; keep the lower ~120 px clear for subtitles. Transitions: cuts, white flashes, impact frames, tracking noise at a tape-related beat; no digital dissolves or wipes.
68
+
69
+ ## 7. Sound palette
70
+
71
+ - **Instruments** (city pop, synth funk, anime-opening pop): saxophone or synth-brass lead, FM electric piano with a bell transient, slap bass, chorus-y 16th guitar chanks, gated-reverb snare and big toms, drum machine, arpeggiated analog synth, string pad, FM bell sparkle. Extended jazz-pop harmony (maj7, 9ths).
72
+ - **Techniques, as options**: band-pass the score to cassette/AM when a diegetic source plays, then open it; a brass hit on a title; a drum fill left open for an effect; one beat of true silence before a peak; a semitone lift for a last chorus.
73
+ - **Foley** (synthesized): engines from an RPM curve, rain, tire hiss, wind, bells, radio squelch, impacts, sparks, cassette clicks, crowd murmur, door buzzers, footsteps on wet pavement; tape accents get their own thunk, whine, hiss.
74
+ - **Voice**: an English-dub feel, short lines; a second voice through a phone/radio band-pass (~380–2800 Hz). Verify every line with whisper.
75
+ - **Mix**: limit then compress TTS, voices ~10 dB over ducked music (duck ~9 dB), beds ducked ~3 dB, choruses louder than intros, two-pass loudnorm to −14 LUFS.
76
+
77
+ ## 8. Native moves
78
+
79
+ A menu: use the ones your story needs.
80
+
81
+ - **Small flat hero in a huge painted world.** *Fits content like:* a first day in a big company; a child in a museum hall; a lone researcher at an observatory.
82
+ - **Stillness as drama** (held close-up or harmony still). *Fits content like:* an exam result; a goodbye at a gate; an unveiling.
83
+ - **Backlit light.** *Fits content like:* a lantern festival; a screen full of code; a lighthouse; stage lights.
84
+ - **Speed grammar** (speed lines, looping plates, impact frames). *Fits content like:* a sprint final; a data packet crossing the world; a kitchen rush.
85
+ - **Light-band sweep on a held cel.** *Fits content like:* a night train; a scanner reading a page; a heartbeat quickening.
86
+ - **A song as an object** (tape, radio, jukebox changes the score). *Fits content like:* a band's origin; a family memory; a call-in show.
87
+ - **Tape artefacts as punctuation.** *Fits content like:* found home video; a rewind to the past; an interrupted broadcast.
88
+ - **Colour-model change** (one place, another hour). *Fits content like:* a day in a shop; a farm's seasons; before/after a renovation.
89
+
90
+ ## 9. Pitfalls of the medium
91
+
92
+ - White cels bloom pink → bloom from the emissive canvas; weak, high-threshold bloom on colour.
93
+ - Neon bleeds through characters → silhouettes stamped into the emissive canvas.
94
+ - Black holes in highlights → clamp before S-curves.
95
+ - Thick rim light swallows thin shapes → 2–4 px offsets.
96
+ - Hair like tentacles, a face like a paper mask, moe eyes, uniform black lines → the drawing rules in §2.
97
+ - Pink faces under coloured light → skin gets its own colour per set; weaker light sweeps on faces.
98
+ - Front views are the hardest drawing → hide them behind a visor, a windscreen or backlight when you can.
99
+ - Pseudo-3D points behind the camera flip into the sky → clamp z to the near plane.
100
+ - Canvas silently falls back to a serif → `document.fonts.load` every weight before painting.
101
+ - CRT detail inflates files → noise in the shader, only `noise=c0s=2:allf=t` in ffmpeg, CRF ≈ 23; loudnorm in two passes with `linear=true`; don't let a limiter flatten the dynamics.
102
+
103
+ ## 10. Engine
104
+
105
+ In `demo/`: `cel.js` (path, cel, ribbon, flutter), `pal.js` (colour models), `head80.js` (80s head, 3 views × expressions), `hands.js`, `bg.js` (painted plates, crane plates, wet reflections), `fx.js` (rain, speed lines, flares, trails), `post.js` (WebGL tape + CRT pass: bloom, grade, subtitles, power-on, tracking noise), `hud.js`, `music/score.py` (numpy FM/slap/brass synthesis), `tools/`. `?test=model|close|side` draws model sheets, `?raw=1` skips the CRT pass. A minimal new use: a harbour sunset plate with its emissive pair, one cel boat shaded with `cel.js`, through `post.js`.
106
+
107
+ ## 11. Variation space
108
+
109
+ You decide the structure, the characters, the world, the opening, the ending, the camera path, the pacing and the colour models. All far from our demo:
110
+
111
+ - Structures: **slice of life in four seasons** (one place, four colour models, a small change each time); **two-hander dialogue** (a locked two-shot comedy that breaks into one fantasy sequence); **the mock opening credits** (a character roster introduced one by one, each with a pose and a name card).
112
+ - Openings: **in the middle of a conversation** (lip flaps already moving, no establishing shot); **a TV being switched on** to an in-world broadcast; **a close-up of a drawing hand** in a classroom, then cut to the world it draws.
113
+ - Endings: **a freeze-frame** on a laugh with a "to be continued" card; **the tape runs out** into blue screen; **a slow pan up to a starry sky** from a quiet rooftop, no dialogue.
114
+
115
+ ---
116
+
117
+ How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,153 @@
1
+ # Chalkboard — Style Prompt
2
+
3
+ > A real classroom blackboard on which chalk writes itself, stroke by stroke in true stroke order, with no hand, no chalk stick and no eraser in sight. One idea is taught the way a teacher does it: write what people think, wipe it with one pass, write what is true in the same place.
4
+ > References (grammar only): a primary-school literacy lesson on a sliding double blackboard; the way a teacher underlines the parts of a character, circles one component and wipes a wrong line. Take the order of a lesson, not any teacher's handwriting.
5
+
6
+ Suits short lessons on one idea: where a word or a character comes from, a misconception set right, a worked problem. The length follows how many steps the lesson has.
7
+
8
+ ## 1. Essence, and what it is not
9
+
10
+ - **A clean, freshly wiped board.** One even deep ink green with its own fine grain and very slow mottling. No history on the slate: no old swirls, no ghost lessons, no floating dust, no bokeh.
11
+ - **Writing that grows like a hand writes.** Strokes appear along their centre line in the correct stroke order, with pressure: pressed starts and corners, points that lift, 捺 feet that spread, hooks flicked off.
12
+ - **Three chalks at most.** White for structure, one accent chalk for the single part the lesson tracks, one pale chalk for a second hand (a pupil, a visitor).
13
+ - **A real object in a real room.** Wooden frame, a tray with sticks of chalk, painted tian-zi grids, sliding panels, a wall and a clock around it.
14
+ - **Few words, large letters.** The board holds keywords; the explanation is spoken.
15
+
16
+ Not Whiteboard Explainer: that style is a bright glossy board, coloured markers, floating marker props and magnets, ghost marks of old lessons, and a camera travelling across a knowledge map of many regions to explain how something works. Chalkboard is a dark matte slate with nothing floating in front of it, kept clean, one question per board, the camera facing it flat; it advances by writing a claim, wiping it and rewriting in place, and it lives in a classroom (panels that slide, grids painted on, a tray, a wall). Not a slide either: nothing is typeset, nothing fades in.
17
+
18
+ ## 2. Materials & rendering
19
+
20
+ - Canvas 2D for everything visible; WebGL2 only for the post pass (camera motion blur, a light vignette, grade, dither).
21
+ - Each stroke is baked once into a board-space coverage sprite (coverage, arc length, lateral position). A partial stroke reveals pixels up to the current arc length with a round leading edge; the board's grain decides which grains take the chalk (deposit with a 2×2 supersample and a faint powder halo).
22
+ - Chalk edges are firm; loose powder only at the lift-off of a stroke (two to five grains). Never sugar the board.
23
+ - Writing strokes carry a width profile per stroke type (start bump, corner bumps, taper for 撇 / 提, foot for 捺, quick lift for hooks) and a pressure profile (heavier at both ends, lighter in the middle). Straight strokes bow slightly; horizontals rise 2–3° to the right; 横, 竖 and 折 enter with a short pressed tick from the upper left.
24
+ - Board, panels, frame, tray, clock and wall are baked once in world units; the slate grain is a periodic tile drawn in world space (soft-light) only when the camera is close.
25
+ - Erasing is a blurred destination-out band along one smooth path on a layer that holds only the strokes being wiped; it leaves a very thin, even haze. One wipe per film is plenty.
26
+ - A wet streak (a board just wiped with a damp cloth) is a soft mask with a wide blur at its drying edge, fading at top and bottom, that darkens the slate slightly; never a hard rim.
27
+ - Light: a gentle multiply falloff away from the windows and at most a faint warm window patch. Light never draws shapes across the writing in close shots.
28
+
29
+ ## 3. Colour logic
30
+
31
+ - Ground: deep ink green slate, wood frame, warm white wall and a coloured dado if the room is seen.
32
+ - White chalk carries every structure: characters, lines, labels, arrows.
33
+ - The accent chalk (example: orange) is reserved for the one component the lesson tracks; it never decorates and never draws arrows or underlines that are not that component.
34
+ - A pale second chalk (example: yellow) marks another person's handwriting.
35
+ - No rainbow, no gradients in chalk, no glow. Painted grids are dull and thin so the chalk always wins.
36
+
37
+ ## 4. Type & subtitles
38
+
39
+ - Chinese is hand-authored stroke data (centre lines + stroke type per stroke) drawn by the chalk engine, never a font's outline. Every character the topic needs is added to the data and checked against an OFL kai font behind it before shooting (how: §10, *New characters*).
40
+ - English on the board is a single-line OFL handwriting font (EMS family) drawn by the same engine; symbols missing from the font (arrows, plus) are drawn as strokes.
41
+ - On the board: keywords only, one line of Chinese, the next line English, a size smaller.
42
+ - Sizes at 1080p: big characters 300–450 px; labels ≥ 55 px CJK and ≥ 30 px Latin cap height; small writing gets heavier chalk so no stroke is thinner than 3 px.
43
+ - Reading time: every block stays fully in frame ≥ CJK ÷ 4.5 + other ÷ 15 + 1.5 s, counted from the frame it is wholly visible (readcheck). A block is fully written before it is read.
44
+
45
+ ### Voice and subtitles
46
+
47
+ - When the style tells a story it is narrated: one calm teacher's voice in short spoken sentences, said as the matching chalk appears; what the voice names is being written or shown at that moment.
48
+ - A quiet subtitle plate sits above the bottom safe area: the spoken line in Chinese and a free English translation, one line each, a plain kai face (an OFL subset) on a soft dark plate, in and out with the voice. Long lines are split at sentence ends into several cues.
49
+ - Nothing the viewer must read on the board sits behind the plate; frames held for the board's words are composed above it.
50
+ - Pauses between voice lines are short (0.25–0.4 s); one longer hold (about 1.5 s) is kept for the verdict. Board action (a panel sliding, a wipe) runs under the voice instead of waiting for it.
51
+
52
+ ## 5. Motion quality
53
+
54
+ - 30 fps, continuous (render with `--fps 30`: `core/render/video.mjs` defaults to 24).
55
+ - Chalk speed, measured on our demo: a big character takes about 0.1 s per stroke including the air between strokes (a ten-stroke character about 1 s), labels about 0.04 s per stroke. Writing speeds up rather than making the voice wait, but a big character written much faster than about 0.07 s per stroke stops looking like a hand.
56
+ - When reading time and chalk speed pinch in a short film, change the words, not the hand. Ways that work (choose per film): fewer and shorter blocks on the board; big characters only for what the lesson tracks, everything else at label size; start a block while the voice is still on the previous line, so it is finished when it is named; write the next block while the last one is still being read in the same frame; hold the frame instead of moving on; make the film longer.
57
+ - Camera eases in and out (cubic), never bounces except a whip landing.
58
+ - Things appear only by being written, wiped, revealed by a sliding panel or by drying. Nothing fades in.
59
+
60
+ ## 6. Camera grammar
61
+
62
+ The camera always faces the board flat on (no perspective tilt).
63
+
64
+ | Move | What it expresses | Can serve |
65
+ |---|---|---|
66
+ | Close shot on the writing | attention on how a character or line is built | a component; a step of a proof; a spelling |
67
+ | Slow lateral pan along a line | time or sequence | a timeline; a derivation; a list of cases |
68
+ | Pull back to a fixed medium frame | the whole question at once | a comparison; a claim and its counter-claim |
69
+ | Same frame later | judgement | a correction; a before / after |
70
+ | Locked frame while a panel slides | a page turned in the room's own way | a new chapter; a hidden board |
71
+ | Whip with motion blur (≤ 0.5 s) | a jump to another part of the wall | a change of board |
72
+ | Cut on a line crossing a seam | a connection | cause and effect; the same part in two places |
73
+ | Wide shot of the whole wall | summary | the map of what was learnt |
74
+
75
+ The room is part of the style: at least once the frame opens wide enough to read board, frame, tray and wall as a classroom (where, and what else the room holds, is the film's choice). Close shots may show only slate and frame.
76
+
77
+ Rules: the subject is never smaller than a third of the frame in close shots; text blocks are never cut by the frame edge while they are read; no empty board for more than half a second. Transitions are hard cuts, a sliding panel or a line across a seam; no dissolves or page flips.
78
+
79
+ ## 7. Sound palette
80
+
81
+ - Voice first: it is the loudest element; music sits 15–18 dB under it and comes up only in the pauses.
82
+ - Foley: real chalk recordings cut into grains, one grain chain per stroke, level from stroke size; a light knock on landings; the accent chalk slightly softer and duller. A felt pass for the wipe, the low roll of a sliding panel ending on a stop, room tone very low; school sounds (a distant bell) only as punctuation. Where the recordings come from and how to cut them: §10, *Sound*.
83
+ - Music: sparse plucked strings (a guqin model or nylon guitar) with marimba and pizzicato bass; a plucked note can be "born" from something drawn. Silence while a question or a verdict is read.
84
+ - Mix: about −16 LUFS integrated before mastering, true peak ≤ −1.5 dBFS.
85
+
86
+ ## 8. Native moves
87
+
88
+ - **Write, wipe, rewrite in place.** The wrong reading is written under its object, wiped with one pass, and the right one written in the same spot from the same camera position. *Fits content like:* a common misconception in physics; a misremembered date; a sum everybody gets wrong.
89
+ - **Tracked component in accent chalk.** One part keeps its colour and its height across several forms. *Fits content like:* a root through a word family; a variable through an equation's rearrangements; a gene through generations.
90
+ - **Sliding panel reveal.** The front panel slides away to show a clean back board, and can slide back to close the lesson. *Fits content like:* "but before that…"; the hidden proof; the answer kept back.
91
+ - **A line that sews two boards.** One accent line runs across the seam to join two places. *Fits content like:* the same constant in two formulas; a quote and its source; cause and effect.
92
+ - **Drying wet streak.** The freshly wiped board dries back and reveals what was left untouched. *Fits content like:* yesterday's question; a note left by a student; a reminder at the corner.
93
+ - **Second hand.** A different, childlike chalk colour and hand on the same board. *Fits content like:* a pupil's question; a visitor's comment; a wrong attempt.
94
+ - **Chalk as a measuring tool.** An accent object laid along a white line and ticked off, so a comparison is shown, not told. *Fits content like:* a unit's origin; a scale; how many of one thing fit another.
95
+
96
+ ## 9. Pitfalls of the medium
97
+
98
+ - Dirty boards (old swirls, ghosts, floating dust) read as "messy", not "real". Keep the slate clean and let the grain carry the realism.
99
+ - Equal-width polylines look like a plotter and make characters misread. Use stroke-type width and pressure profiles.
100
+ - Character data that is structurally wrong is caught at once by native readers: check every character against a reference before shooting.
101
+ - Small writing at 1080p disappears with the same chalk width as large writing; give small text heavier chalk.
102
+ - Text written while the camera moves away fails reading time; hold the frame or keep the block in view.
103
+ - Accent colour spread over arrows and decorations stops meaning anything.
104
+ - A soft halo at the chalk's front reads as glow. The demo's `drawFront` (`props.js`) puts a faint radial gradient under its grains: in your copy, drop the gradient and keep the grains.
105
+ - A wet streak with a hard edge looks like a cut-out.
106
+ - Board-speak in the voice ("A plus B", component names with no meaning) is not understood: every component is said with what it means the first time it appears.
107
+
108
+ ## 10. Engine
109
+
110
+ The demo's code is a working engine; copy it into the project folder and write the film yourself.
111
+
112
+ **Copy as is:** `js/chalk.js` (`Stroke`, `bake`, `drawStroke`: the chalk), `js/hand.js` (`writeChar(ch, cx, cy, size, clock, o)`, `writeLine` for mixed Chinese and Latin, `writeLatin`, `latinWidth`, `loadSvgFont`; each returns `Stroke[]` with `t0`/`t1` set and `.end` = the time the last stroke ends), `js/r2d.js` (grain tile, deposit), `js/stage.js` (slates, frame, tray, clock, wall, `paintGrid`; world units: slate x 0…6400, y 0…1700, panel width `PW` 3200), `js/post.js`, `js/lab.js`, `tools/foley_lib.py`, `tools/subset.py` (subtitle font cut from the strings in `SUB` in `film.js`), `tools/srt.py`. `js/props.js` too, minus the glow (§9).
113
+
114
+ **Adapt:** `js/hz.js` (keep its characters, add yours), `index.html` (title), `js/app.js` (the compositor: it draws the layers, wet streak, wipe, light, subtitle plate and exposes `render`, `TEXTS`, `DUR`, `EV`; edit it to the film's board instead of feeding it placeholder data).
115
+
116
+ **Write yourself:** `js/film.js` (every stroke, time, camera key, voice start and subtitle, as data), the voice lines, the score and mix (`audio.py` is the demo's own score; its chalk-grain part is reusable), `build.sh`. `js/ancient.js` is the demo's old forms of one character: not an engine file.
117
+
118
+ **What `app.js` reads from `build(W, H)` in `film.js`:**
119
+
120
+ | Field | What it is |
121
+ |---|---|
122
+ | `S` | every `Stroke`, each with `layer`: `'FL'` (the sliding front panel, in panel-local units, moved by `slideX`), `'FR'` (the right panel, world units), `'BK'` (the back board, drawn only once the panel has moved), `'WORLD'` (on top, world units, drawn while `t < T.back0`); FL strokes also carry `phase` (`'pre'` = can be wiped, `wiped: true` = removed by the wipe; `'post'` = written after it). `o.R` sets bake resolution (default 2) |
123
+ | `DUR` | length in seconds |
124
+ | `camAt(t)` | `{cx, cy, s, shot}`: centre in world units, scale for a 1920-wide frame, shot index (motion blur is only taken within one shot) |
125
+ | `slideX(t)` | the front panel's offset; `() => 0` if it never moves |
126
+ | `TX` | board text for readcheck: `{id, text, layer, box:[x0,y0,x1,y1] in that layer's units, t0, t1}` |
127
+ | `SUBS` | subtitle cues `{id, t0, t1, zh, en}` |
128
+ | `EV` | sound events for `core/render/events.mjs`: `vo` (voice starts), `sub` (for the .srt), `chalk` (`t, d, len, color, pan, big`, one per stroke) and any of your own |
129
+ | `G1`, `G2`, `SMALL`, `T.back0`, `wet`, `wipe` | painted grids on the front panel and back board; when the closing slide starts; the wet streak `{x0, y0, y1, xEnd, bx0, t0, t1}`; the wipe `{t0, t1, w, path}` |
130
+
131
+ A film without a wet streak, a wipe, grids or a sliding panel removes those parts from its copy of `app.js` (or guards them, e.g. `if (!F.wet) return` at the top of `drawWet`, `if (!F.wipe) return null` in `drawWipeHaze`), and draws `WORLD` strokes on a condition of its own if there is no closing slide. Don't pass dummy fields to keep the compositor quiet.
132
+
133
+ **New characters.** `hz.js` maps a character to its strokes in standard stroke order (GF 0023-2020); each stroke is `"type x,y x,y …"`: the centre line through its anchor points in a 100 × 100 box, y down. Types: `h` 横, `s` 竖, `p` 撇, `n` 捺, `d` 点, `t` 提, `x` 悬针竖; `z…` for turns (corners pressed); a last letter `g` ends in a hook (its last point is the hook's tip), `p` / `t` in a point, `d` in a dot. Write only the centre line: the slight bow, the rise of horizontals and the pressed entry tick are added by `writeChar`. Symbols (arrows, plus, a tick) are written the same way. A way that works:
134
+
135
+ 1. Take the stroke order and count from a dictionary that shows the standard order, and write down the type sequence first.
136
+ 2. Set the character large from the reference kai (LXGW WenKai, `fonts/`) on a 100-unit grid, placed as the check page places it so the numbers line up: e.g. with PIL, `ImageFont.truetype(font, 1000)` drawn into a 1000 × 1000 image at `(0, 880)` with `anchor='ls'` (left edge, baseline at 0.88 of the box), with 100-px grid lines; read each stroke's start, corners and end off it and divide by 10. Keep the anchors on the middle of the font's stroke, not its edge.
137
+ 3. Open `index.html?lab=hz&chars=<new characters>&size=400`: the chalk is drawn over the font in red. Check stroke count and order, which strokes touch or cross and which stop short, the proportion of each component, hook directions and the 撇/捺 feet; then look again at the size the film uses for it. Fix the numbers, not the font.
138
+ 4. Read it at film size the way a native reader would, before shooting (§9): a structure that looks right at 400 px over the font can still read as another character on its own.
139
+
140
+ **Sound.** Three CC0 / CC BY recordings of chalk on a board from Wikimedia Commons (URLs in the demo's `build.sh`, credits in `CREDITS`) are cut into tagged grains with `python -I tools/foley_lib.py <out_dir> <name>=<file> …`: `tap`, `stroke` and `squeak` grains plus `index.json` with each grain's length, attack and brightness. The demo's `audio.py` places one grain chain per `chalk` event (length from `d`, level from `len`, the accent chalk low-passed); other recordings can be cut the same way.
141
+
142
+ **Render.** `node core/render/events.mjs <film>` (events from the page), your mix, `node core/render/video.mjs <film> --fps 30`, `sh core/render/mux.sh <video> <mix> <out> 30 1`, `node core/render/readcheck.mjs <film>`. The page bakes every stroke on load (about 10 s for 500 strokes), then 20–50 ms per 1080p frame. readcheck counts from the first frame a block's box is on screen, which is when its writing starts: leave the reading time after the last stroke yourself (§4).
143
+
144
+ ## 11. Variation space
145
+
146
+ The agent decides the topic, the board layout, the number of panels, the tracked component, the hands, the camera path and the pacing.
147
+ - **Structures:** a proof built on one board line by line; three wrong answers wiped one after another before the right one; two boards in dialogue, question on one, answer on the other.
148
+ - **Openings:** a duster's last pass revealing a formula; a close-up of the tray as one chalk starts writing; the bell ringing over an empty, freshly wiped board.
149
+ - **Endings:** the whole wall with the lesson complete; a final underline under one word; the board half-wiped for the next class with one line kept.
150
+
151
+ ---
152
+
153
+ How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,149 @@
1
+ # Circuit Board — Style Prompt
2
+
3
+ > The subject is drawn as a printed circuit board seen from straight above: the world is copper under green solder mask, routes are traces, places are pads, words are white silkscreen, and what flows (power, water, signals, goods) is light running along the copper. The camera rides that light and jumps between the scale of a map and the scale of a single component.
4
+ > References (grammar only): real PCB design files and assembly drawings (layers, clearances, designators, detail callouts); macro photography of boards (shallow depth of field, gold sheen, soft key light); schematic and single-line diagrams (one symbol stands for one function). Draw your own boards: never copy a real board layout, a logo or a part marking.
5
+ >
6
+ > **Frame rate: 30 fps.** Pass `--fps 30` to `video.mjs` and `30` to `mux.sh`; this overrides the 24 fps in the DIRECTOR.md and TECHNIQUE.md examples.
7
+
8
+ ## 1. Essence, and what it is not
9
+
10
+ - A top-down board in every frame: copper pour with clearances cut around everything, traces with 0/45/90° runs and mitred corners, gold pads and vias, white monoline silkscreen. Nothing is drawn in perspective.
11
+ - Information moves as light on copper. The way the light moves *is* the explanation: a pulse, a stream, a rocking dash, a pad that flashes.
12
+ - Two scales on one board: whole regions (a map, a supply chain, a city) are drawn in the same language as single components, and the camera passes between them without changing medium.
13
+ - Only real things are drawn. Every trace, pad and label stands for something in the subject; empty copper is filled with what boards really have (stitching vias, via fences, solder-mask mottling), never with decorative routing.
14
+ - Not the library's Engineering Briefing Board (a whiteboard on which real photos are pinned and written over in marker): here there are no photos and no handwriting; the subject itself becomes copper, pads and silkscreen, and information travels as light along the traces. Not a blueprint (no white-on-blue linework, no paper), not a sci-fi HUD (no glass, no floating panels, no glowing UI chrome), not a 3D circuit "city" (no buildings rising, no perspective).
15
+
16
+ ## 2. Materials & rendering
17
+
18
+ Layers bottom-up, all in board space under one world → screen camera:
19
+ 1. **Laminate (FR-4):** dark green, a glass-weave basket texture in two crossfaded octaves so its on-screen size stays bounded at every zoom. Bottom-layer copper may show through faintly.
20
+ 2. **Copper pour:** fills the board; everything is a **clearance** punched out of it (channels, lakes, sea, keep-outs around parts and traces). Rendered twice: a lighter rim pass with the plain clearance, then the fill pass with the clearance grown by ~1.6 px, so every copper edge gets a bevelled rim. A soft mottling texture sits only on the pour (solder mask is never perfectly flat).
21
+ 3. **Traces:** rim colour stroke + narrower fill stroke, round caps; a channel of bare laminate runs on both sides (the clearance). Parallel traces keep the pour out of the gap between them when they are a pair.
22
+ 4. **Exposed metal:** ENIG-gold pads (rect, round, square pin-1) with a sheen band on the top third and a dark drill hole; vias are gold rings with dark bores; bare copper (salmon with a vertical gradient and brushed streaks) only for one heavy, special part. Fiducials and mounting holes at board corners.
23
+ 5. **Silkscreen:** off-white monoline strokes with a pinhole texture punched out, slightly blurred (0.35 px). Outlines, designators, polarity marks, component symbols, labels.
24
+ 6. **Light:** an additive layer (glow) with two blurs (≈24 px and ≈5 px) under a sharp copy. Current, water, lit pads all live here.
25
+ 7. **Screen space (once per frame):** a soft warm key light drifting from the upper left, shallow depth of field (a blurred copy faded in at the top and bottom bands, stronger in macro shots, weak or off where text must be read), out-of-focus motes of light drifting with parallax in front of the board, a vignette, film grain at mux. A window's light (a soft parallelogram with a mullion shadow) may fall on the board when the whole board is on a desk.
26
+ Level of detail: textures crossfade between octaves; small features (vias, designators, rims) fade out before they go sub-pixel, so zooms never shimmer. Nested boards (a module inside a board) are separate boards composited into their footprint, so a continuous zoom can cross six or more orders of magnitude without precision loss.
27
+
28
+ ## 3. Colour logic
29
+
30
+ - Ground: green solder mask in three values (dark laminate, mid pour, light rim/trace). The film is green; never recolour the mask per scene.
31
+ - Metal: gold for pads and vias, one bare-copper accent at most.
32
+ - Ink: one off-white for all silkscreen.
33
+ - Light carries meaning and is the only saturated colour: **amber** for energy/current (with a near-white core), **silver-cyan** for a second kind of flow (water, data, goods) when the story has two. A third flow gets a third light colour only if it must be told apart; red is reserved for a fault and appears at most once.
34
+ - Dark (bare laminate, sea, holes) for what is absent.
35
+ Example: laminate #05190F, pour #1C6A44, rim #4AA977, gold #D9B25B, silk #F2EEE1, current (255,190,84), water (170,214,226).
36
+
37
+ ## 4. Type & subtitles
38
+
39
+ - All type is silkscreen in one **monoline stroke font routed like traces** (0/45/90° strokes, chamfered corners, round caps), drawn in code. Chinese uses the same rules: every hanzi hand-routed on a 0/45/90° grid with the same stroke width as the Latin line beside it. Use simplified characters only and proof every glyph at large size before use.
40
+ - Text is world-anchored and **plotted stroke by stroke**; it stays on the board and is still there when the camera pulls back.
41
+ - Roles: labels (a Chinese line above a smaller English line, same stroke width), board-native text in one language (designators, voltages, timestamps, km, values), micro texture (pinyin tags, notes, REV/sheet lines) which may fade below reading size.
42
+ - Reading: a label must be fully in frame and stay there for its reading time (≥ 1.5 s + characters at 4.5/s CJK, 15/s Latin). Never let text sit in the depth-of-field bands; never cut text at the frame edge in a held shot. Title caps ≥ 60 px at 1080p.
43
+ - Moving camera: `readcheck.mjs` starts a label's clock when it is first fully in frame and stops it the first time it leaves, so a label that slides out during a ride or whip fails even if it comes back. Before plotting a label, check where the camera path takes it for its whole reading time: place it where the path keeps it in frame, print it once the camera settles, or let it be micro texture (under ~9 px tall it is not reported).
44
+ - Glyph coverage: the routed font draws only the characters it has. The demo's `hanzi.js` holds just the hanzi its film needed, and the Latin set is capitals, digits, common signs and a few lowercase letters (`a b d e k l m o p s u z`, enough for units like ms, km, kV). A missing character prints as `?` with no error. Check every label string against the font before building, write English labels in capitals (or add the lowercase you need), and route the hanzi you lack (§10, New hanzi).
45
+ - With a voice, every line gets a subtitle in the bottom safe area: a dark translucent plate, Chinese over English (an open-licence sans, e.g. Noto Sans SC, subset to the characters used; never a system font), 34 px / 24 px at 1080p. The board then prints only the voice's key words and numbers, never whole sentences. Keep picture text above the subtitle band.
46
+
47
+ ## 5. Motion quality
48
+
49
+ - 30 fps, everything on ones. `render(t)` depends on t only; motion blur from measured screen motion (180° shutter, sub-frames from 1 to ~20), never across a cut.
50
+ - Kinds of current, told apart only by how the light moves:
51
+ - **AC / alternating:** short dashes rocking back and forth along the trace (a slowed mains frequency) over a faint energised line.
52
+ - **DC / one-way:** a continuous lit stream behind a travelling head, with slow streaks inside and an afterglow that dims slowly behind the head.
53
+ - **Step-down:** the trace gets thinner and the dashes smaller.
54
+ - **Water / second flow:** several parallel streamlines of moving dashes at different speeds, faster in the middle, with short glints.
55
+ - Pads flash on arrival (a quick bright bloom, then a steady glow). Components "conduct": the symbol's internal edges glow while current passes.
56
+ - Silkscreen appears only by plotting; copper and pads never pop in. What never moves: the board itself (only the camera moves).
57
+
58
+ ## 6. Camera grammar
59
+
60
+ Straight-down camera always (rotation about the view axis allowed, small). Moves:
61
+
62
+ | Move | What it expresses | Can serve |
63
+ |---|---|---|
64
+ | Ride the pulse (camera locked to a moving head, head on a third) | following one thing through a system | a delivery route; a signal path; a single order through a process |
65
+ | Rise while following (zoom out during the ride until both ends are in frame) | the whole length becomes visible | a distance; a supply chain end to end; a timeline |
66
+ | Crash zoom onto a pad | arrival, impact | a deadline met; a package delivered; a test result |
67
+ | Locked macro hold | reading, comparing, verdict | two numbers side by side; a spec; a rule |
68
+ | Whip along a trace | jump to the next station | the next stage; skipping ahead |
69
+ | Matched cut on a centred symbol (same symbol, same screen size, the world around it changes scale) | the same step repeated at every level | step-downs; repeated approvals; hand-offs |
70
+ | Plunge through a hole / via, reverse out of another hole | entering a smaller world | into a device; into a building; into a file |
71
+ | Continuous pull-out across nested boards | everything was one board | the big picture after the detail; the system behind one object |
72
+
73
+ Framing rules: the lit subject sits on a third or dead centre for symbols; at least two layers of detail around it (background copper/vias/routes, foreground motes or depth-of-field blur); the board edge appears only when the whole board is the subject. Transitions: motion-into-motion and matched cuts; no fades, no wipes, no page turns.
74
+
75
+ ## 7. Sound palette
76
+
77
+ All synthesised: sine/saw tones, pulse waves, FM bells and glockenspiel, relay clicks (two-click transients), soft kicks and 16th ticks, filtered noise. Tune the drone to the mains hum (50 Hz ≈ G1; 60 Hz ≈ B♭1) so the hum belongs to the key. Rule the ear can follow: an **amplitude-gated tremolo tone = alternating**, a **steady tone = direct**; a component that converts one into the other is heard as the tremolo smoothing into the long tone. Arrivals are relay clicks or a filtered noise burst; a step-down is a relay one step lower each time; plotting silkscreen is a faint scratch of grains. Outside sounds (water, cicadas, traffic) only behind a low-pass, as if heard through a wall. Silence: drop the rhythm before a verdict, keep only long tones. With a voice, the voice leads: duck the bed so it sits 15–18 dB under the speech, effects a few dB. Mix around −16 LUFS before mastering, true peak under −3 dBTP, lean low end (high-pass ≈ 55 Hz).
78
+
79
+ ### Voice-over and subtitles
80
+
81
+ When the film explains something, a voice tells it and the board shows it at the same moment: each spoken line has one picture action (a pad lights, a stream changes shape, a tag prints). Every line gets a subtitle in the bottom safe area, a Chinese line over an English line on a dark translucent plate, appearing and leaving with the voice; the board itself prints only the key words and numbers the voice says (a name, a value, a verdict), never whole sentences. Keep the voice on top: the bed sits 15–18 dB under it and rises in the gaps. Pick one calm, clear voice for the whole film; numbers and units are spoken in full.
82
+
83
+ ## 8. Native moves
84
+
85
+ - **Flow becomes current.** A second flow (silver) enters a row of pads; each pad lights on a beat and amber leaves on its other side. *Fits content like:* raw material entering a factory and leaving as product; requests hitting servers and leaving as responses; donations becoming grants.
86
+ - **Pulse-path explainer.** Every stage of a process is a component on one trace; the way the light changes (rocking, streaming, thinning) tells what each stage does. *Fits content like:* a payment's clearing path; a parcel's sorting hubs; a message across a network.
87
+ - **The map is a board.** Geography re-routed octilinear as copper and channels; rivers, lakes and coasts are clearances with via fences; cities are test points; corridors are buses of parallel traces. *Fits content like:* a pipeline across countries; a migration route; the cables under an ocean. A board that covers China follows DIRECTOR.md §13.
88
+ - **Detail callout.** An assembly-drawing circle that shows another place of the same board (or another board) at a chosen scale next to the thing it is compared with. *Fits content like:* the same mechanism at two sizes; a lab prototype beside the plant; yesterday's version beside today's.
89
+ - **Nested boards.** A module footprint on a board is a complete board of its own; plunge into it, or pull out through every level in one move. *Fits content like:* a country → city → building → device; an organisation → team → person; a chip → core → transistor.
90
+ - **Matched step-down.** The same symbol held centred while the board around it changes scale on each cut. *Fits content like:* voltage levels; approval tiers; zoom levels of a map.
91
+ - **Timestamp tags.** Silk frames printing times at two stations, the second tag repeating the first digit-for-digit above its own. *Fits content like:* latency; a race between two routes; before and after.
92
+
93
+ ## 9. Pitfalls of the medium
94
+
95
+ - **Flat pour.** A board that is all mid-green reads as an empty slide. Fill with real board texture: stitching vias that stay visible at map scale, fences along every clearance, mottling, micro silk, other unlit routes that exist in the subject.
96
+ - **Decorative routing.** Traces that mean nothing make viewers ask what they are. Draw only real routes; texture comes from vias and mask, not invented traces.
97
+ - **Lines crossing on one layer.** Two traces can't cross on the same copper: use a via to the bottom layer, or route around. A trace may cross a bare channel (a river, a street).
98
+ - **Overexposed light.** Wide traces with additive bloom turn into white bars. Cap glow widths and flash radii in pixels, keep the amber body and a thin core.
99
+ - **Text in the blur or under the frame edge.** Depth of field and the vignette eat the top and bottom bands: keep labels out of them, or turn the blur down in reading shots.
100
+ - **Too-fast holes.** A plunge into a hole under 0.6 s reads only as "darkness". Hold on the hole first, then plunge; come out of another hole the opposite way.
101
+ - **Precision.** Zooming a single coordinate system over many orders of magnitude breaks the canvas transform. Nest boards (each with moderate units) and convert cameras between levels in double precision.
102
+ - **Hanzi in a stroke font.** Automatic skeletons of fonts lose dots and strokes; route each character by hand and proof traditional/simplified forms (鹤 not 鶴, 换 not 換). A glyph that only works at small size (one component missing, two strokes merged) reads as another character on a title: proof it large (§10).
103
+ - **The board edge by accident.** When the camera's view comes near the board outline, `Board` switches to drawing the desk and clips to the board, so a close shot near the edge suddenly shows black desk. Keep the view well inside the outline (the check uses the frame's half-diagonal plus 4% of the board width), or make the board larger than the shot needs; show the edge only when the whole board is the subject.
104
+
105
+ ## 10. Engine
106
+
107
+ Reference code in `demo/src/`. Copy what you use into the project's `src/` (never import from `styles/`); edit your copies freely. The build order (subtitle font, voice and check, events, score, render at 30 fps, mux, `.srt`, readcheck, stills) is in `demo/build.sh`.
108
+
109
+ **Reusable as is** (no demo content inside):
110
+ - `render.js` — `Board(canvas, world, {unit, noDesig})`; `board.frame(cam, sc)` draws one board for a camera `{x, y, z, r}` (world centre, pixels per unit, rotation); `board.texts(cam, sc)` returns the label boxes for `window.TEXTS`; `camFor(worldPt, screenPt, z, r)` builds a camera that puts a world point at a screen point. `unit` is a typical feature size in world units: it sets where textures change octave and small features fade.
111
+ - `levels.js` — nested boards: `makeLevels`, `toChild`/`toParent`, `baseOf`, `drawLevel`. Needed only when one board sits inside another.
112
+ - `font.js` (+ your `hanzi.js`) — `drawText(ctx, str, x, y, cap, {sw, align, progress})`, `layout`, `textWidth`, `isHanzi`.
113
+ - `geo.js` — `octi` (0/45/90° routing through waypoints, `'d'` diagonal first), `offset`, `measure`/`at`/`sub`/`trim`, `frameAt`.
114
+ - `parts.js` — footprint builders returning `{pads, silk, keep, …anchors}`: `chip`, `ecap`, `xfmr`, `xformer`, `bridge` (with `flow` paths for conduction glow), `reactor`, `capBank`, `ground`, `tag`, `box`. Add your own the same way.
115
+ - `post.js` (key light, depth of field, motes, window light, vignette), `palette.js` (every colour).
116
+
117
+ **Demo content, to replace:** `main.js` (timeline, cameras, scenes, subtitles, sound events) and the world modules `world.js`, `city.js`, `house.js`, `charger.js`, `loss.js`. `render.js` also carries optional demo-specific keys, skipped when a world doesn't export them: `DAM` (the bare-copper bar), `GENS`, `PENS`, `RESERVOIR`, `RES_FLOW`, `TAIL`, and `sc.water` / `sc.gens`. `loss.js` is the smallest complete world module to read first.
118
+
119
+ **A world module** exports, in its own units:
120
+ - required: `BOARD {x0, y0, x1, y1, r, inset}`, `TRACES [{id, pts, w, layer?: 'bottom'}]` (add `m: measure(pts)` to any trace that carries light), `PADS [{x, y, shape: 'round'|'square'|'rect', r | w, h, hole?}]`;
121
+ - optional: `LABELS [{id, text, x, y, cap, sw, align}]` (plotted by `sc.labels[id]`), `SILK [{pts, w, plot?} | {circle, w}]`, `DESIG`, `KEEP` (extra clearances), `VIAS [[x, y, r, bore]]`, `HOLES`, `FIDS`, `TPADS` (pad grids lit by `sc.lit`), `TITLE`, clearances `RIVER`, `LAKES`, `SEA`, `STREETS`, `SLOTS`, `CLEARLINES`, sizes `CLR`, `VIA_R`, `FENCE_R`, `HOLE_R`, and functions `fence()` / `stitch()` returning via positions.
122
+ - `RIVER` entries are channels cut **out of the copper** (and are where `sc.water` flows): use them only for something that really is a gap in the board.
123
+
124
+ **A scene** is the plain object `frame` reads each frame: `{t, labels: {id: 0..1}, ac: [], dc: [], glow: [], flashes: [], lit, after}`.
125
+ - `ac` — `{trace, s0, s1, a, lam, amp, phase}` rocking dashes; with `fade` and `v` they travel forward and die away. `dc` — `{trace, head, s0, a, decay, floor, v, minPx, maxPx, headGlow}` a stream behind a head. Both are drawn in the current colour.
126
+ - `glow` — `{pts, w, a, c}` any polyline in any light colour, with the bloom; `flashes` — `{p, r, a, c: {h, g}, maxPx}` blooms at a point.
127
+ - `after(ctx, M, z)` — draws on top of the finished board (no bloom), for overlays such as a detail-callout circle.
128
+
129
+ **Your own flows and light, without changing the engine (one way of doing it):** a second flow along a trace (a signal, goods, water in a pipe) is built in your scene from `glow` and `flashes`: each frame cut the trace with `sub(trace.m, s0, s1)` into short pieces (a head, a fading tail, dashes moving at your speed) and push them as `glow` entries with the second light colour (`PAL.water.g` or your own), plus a `flash` with `c: PAL.water` at the head. A new kind of motion or a darkness that only the board (not the light) sits under needs a small hook in **your copy** of `render.js`, e.g. `if (sc.myLight) sc.myLight(glowCtx, z, t, vb)` at the end of `glowLayer` (it then gets the bloom), or a dark fill before the silkscreen pass; a darkening of the whole frame belongs in your `main.js` between the board stack and `post`.
130
+
131
+ **Page contract:** your `main.js` exposes `window.render(t)`, `DUR`, `TEXTS(t)` (collect `board.texts` for every level drawn), `EV`, `READY`, as in `core/README.md`. Motion blur averages sub-frames of `render(t)`; keep sub-frames within one shot.
132
+
133
+ **Check the lettering before building:** list every character used in `LABELS`, `DESIG` and silk text that is neither in `HANZI` nor in `GLYPHS` (e.g. a few lines in node importing `font.js`, or `isHanzi` plus the glyph table); the list must be empty.
134
+
135
+ **New hanzi** (`hanzi.js`): one entry per character, an array of strokes, each stroke a flat list `[x, y, x, y, …]` in a 12 × 12 box (y down), runs at 0/45/90° only. `font.js` chamfers right-angle corners and plots strokes in the order listed, so list them in writing order. A dot is a stroke about one unit long; a hook is a final short 45° run. Keep the same stroke width as the Latin: never vary width per glyph. One way to work:
136
+ 1. Make a proof page in the project folder: for each character, a 12 × 12 grid, the character from an open-licence font (e.g. Noto Sans SC) faintly underneath as a structure reference, your routed glyph on top via `drawText` at a cap of a few hundred pixels; a second row without the reference; and once at the size it is used in the film. Render it with `core/render/still.mjs`.
137
+ 2. Read the components and their proportions off the reference and route them by hand (not an automatic skeleton, which drops dots and merges strokes). Reuse shared components from glyphs you already have, so radicals match across the film (e.g. 氵, 扌, 亻 in the demo's `hanzi.js`).
138
+ 3. Look at the proof image: every component of the reference present, nothing reads as a neighbouring character (声 vs 青, 手 vs 毛), simplified forms. Fix and re-render until it reads without the reference. If a character still won't read, choose another word.
139
+
140
+ ## 11. Variation space
141
+
142
+ The agent decides the structure, the stations, the scales visited, the camera path, the pacing and which flows get which light. Range, far from the demo:
143
+ - Structures: a single packet's round trip and the time it took; three routes raced side by side on parallel buses; one board revealed component by component like an exploded view, ending on the whole.
144
+ - Openings: a via drilled through in macro, light rising out of it; a whole board on a desk, the camera diving to one pad; a single silk label plotting itself in the dark, then the copper lighting under it.
145
+ - Endings: the last pad lights and the board's power LED stays on; a pull-out to many identical boards in a rack; the title block of the board printing the answer.
146
+
147
+ ---
148
+
149
+ How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,140 @@
1
+ # Time-lapse Symphony — Style Prompt
2
+
3
+ > A city film cut like a piece of minimalist music: time-lapse turns traffic, crowds and clouds into rivers of light, the cuts get denser with the score's subdivisions, one thing is slowed almost to a stop, and the film ends on a hard cut to black on a downbeat. No narrator. The music carries it.
4
+ > Grammar learned from the city-symphony tradition and the "Qatsi" films (Reggio / Fricke, scores in the Philip Glass manner). Nothing is taken from those films: no footage, no melody, no title lettering, no names in the film.
5
+
6
+ ## 1. Essence, and what it is not
7
+
8
+ - **An edit style.** The picture is real footage of a place (time-lapse, hyperlapse, aerials, slow motion, archive film, photographs). The style lives in *how time is bent* and *where the cuts fall*, not in a drawn look.
9
+ - **The score is the script.** It is written first, with a clear arc: minimal repetition → acceleration → climax → a sudden stop → acceleration again → hard stop → a quiet coda. Every cut sits on a beat or a subdivision of it.
10
+ - **Machines fast, people slow.** Cars, trains, clouds and light are sped up until they become lines; the one slowed moment is something fragile (a soap bubble, steam, a flag, a flock), and people appear as crowds, tracks or long-exposure ghosts.
11
+ - **Few words, each one earned.** On-screen text is a title, a handful of numbers that state the size of the place (each from an official source), an archive date, and one line from a real public-domain text at the end.
12
+ - **It is not** a travel reel (no drone-porn montage on a pop track), a vlog, a news package, an explainer with a narrator, or a slideshow of postcards. No lower thirds with names, no headers, no centred title cards with page-turn transitions, no logo stings.
13
+
14
+ ## 2. Materials & rendering
15
+
16
+ - Footage only (2D). Sources mixed freely: tripod time-lapse, long single-camera time-lapse (≥ 12 h, sunrise and sunset in the same frame), hyperlapse, drone aerials (top-down is gold), high-frame-rate slow motion, archive film (pre-1931), photographs (a pair from the same camera position is gold), a scanned page of a historic text.
17
+ - Everything is unified into one **35 mm release-print** look: 1.85:1 matte (21 px bars on 1920×1080), warm highlights, lifted blacks, highlight bloom, clumped mid-tone grain, ±0.5 px gate weave, soft vignette.
18
+ - Never generated images; never restored, colourised or speed-corrected archive copies; never YouTube mirrors of archive films.
19
+ - Upscale limits: archive ≤ 2.5× (denoise → lanczos → light sharpen → grain); modern ≤ 1.5×.
20
+
21
+ ## 3. Colour logic
22
+
23
+ | Use | Value |
24
+ |---|---|
25
+ | Type (warm white) | `#EDE8DF` |
26
+ | Secondary line (English, labels) | `#B0AAA0` |
27
+ | Sodium orange — the only accent (rules under numbers, source lines, crowd tracks, the day ring's hand) | `#D9772F` |
28
+ | Matte and black | `#000000` |
29
+
30
+ Grade (`tools/render.py → make_luts / grade`): per-shot partial grey-world white balance first (only pixels with luminance 0.12–0.88, strength 0–0.6; **0 for night shots**, which keep their sodium and blue), then one LUT for all shots: S-curve (sigmoid slope 6.2, pivot 0.47, blended 55/45 with linear) → black 7/255, white 250/255 → R ×1.025, B ×0.965 (warm highlights, a little cold in the shadows) → saturation 0.86. Bloom: pixels above 170/255, blurred 6 px at ⅛ size, added back × (1, .82, .62); 0.09 by day, 0.15–0.2 at night. Grain: half-resolution Gaussian noise up-sampled and blurred 0.6 px, weighted `0.35 + 1.3·L·(1−L)`, strength 9/255. Archive film stays black-and-white and goes through the same LUT, so it reads as part of the same print.
31
+
32
+ ## 4. Type & subtitles
33
+
34
+ - Latin: **Michroma** (OFL), capitals, tracking 0.06–0.32 em. Chinese: **Noto Sans SC** variable, weight 300–350, tracking 0.08–0.14 em. Credits: Noto Sans SC 17 px.
35
+ - **Left-aligned**, left margin 168–196 px, never centred, never on a box. Legibility comes from a very soft elliptical darkening behind the block (α ≤ 0.6), not a panel.
36
+ - **Number card**: the number in Michroma 84 px (44 px when three numbers stack); a 2 px sodium rule grows under it; one Chinese line (28 px) and one English line (14–16 px) say what it counts and the source year. A census-type number locks digit by digit on sixteenths (one glockenspiel note per digit); a flow number counts up from 0 in 0.6 s (ease-out). "About" numbers carry `≈` and "约".
37
+ - **Archive date**: just the year, Michroma 22 px, bottom-left of the archive panel.
38
+ - **Closing quote**: on the page shot the whole sentence is lit; on the card, a short fragment over the last moving shot — Chinese 60 px, English original in capitals 20 px, source line 14 px sodium, fading in within 0.25 s and held just past the reading time.
39
+ - One line per language, never wrapped; every text block stays fully in frame at least CJK ÷ 4.5 + other ÷ 15 + 1.5 s (`readcheck.mjs`). Text may stay up across cuts underneath it, but only while the shots under it belong to what it counts.
40
+ - `.srt`: the film has no voice, so the subtitle file carries the on-screen text (one Chinese and one English line per cue) for muted or accessible playback.
41
+
42
+ ## 5. Motion quality
43
+
44
+ - Speed is the main instrument. Shot speeds run from 0.3× to 75×; every speed above 1× uses **frame blending** (a 360° shutter): each output frame averages the source frames it covers, capped at N frames. Headlights become continuous lines, crowds become fog, clouds become water.
45
+ - **Speed ramps** are smooth (smoothstep between key speeds) and always mean something: a corridor accelerates out of real time (1× → 6×), a time-lapse ramps into a frenzy (1× → 7×), a fast shot brakes into slow motion (2.2× → 0.3× in 0.55 s) on the bar where the music stops.
46
+ - Camera moves are added sparingly in post: slow push-ins (1.00 → 1.05–1.10 over the shot), a falling push on the opening still (1.0 → 1.3 in 0.35 s, ease-out, then accelerating to ×2 by the cut). No shakes, no whip pans, no digital zooms past the upscale limit.
47
+
48
+ ## 6. Camera grammar — editing
49
+
50
+ **Cut-point table (the score decides; numbers at 120 BPM and 30 fps: 1 beat = 15 frames, triplet = 5, sixteenth = 3.75)**
51
+
52
+ | Score texture | Cut length | Frames | Use |
53
+ |---|---|---|---|
54
+ | Opening hit + eighth-note arpeggio | 2 bars → 1 bar | 120 → 60 | the opening still, the first single-camera time-lapse |
55
+ | Eighths | 2 beats → 1 beat | 30 → 15 | dawn, match cuts |
56
+ | Triplets against eighths (3:2) | 1 beat → ½ beat | 15 → 7/8 alternating | morning, the montage of streets |
57
+ | Sixteenths, full ensemble | grid cells light every 1–2 frames; cells re-cut every sixteenth | 1–4 | the grid |
58
+ | Arpeggios stop, one long chord | 3–4 s, one or two shots | 90–120 | the brake: the slowed thing, the archive split |
59
+ | Sixteenths + triplets + horns | ½ beat → 4 frames → 2 frames | 7 → 4 → 2 | dusk to night, the reverse flashback |
60
+ | Dry cut of the whole ensemble, reverb left ringing | hard cut to black on the bar line | — | the hard stop |
61
+
62
+ Rules:
63
+
64
+ - **Cuts land on beats.** All cut times come from one function, `bar(n, beat)` in `tools/timeline.py`; shot lengths are never typed in seconds. The music is rendered from the same file.
65
+ - **One long single-camera time-lapse is the clock.** It returns three or four times (night → dawn, noon clouds, a one-second nightfall, a day/night flicker), always from the same position, so the viewer knows the time without a caption.
66
+ - **Density follows the score.** The editor never cuts faster than the current subdivision, and the slowest picture sits under the place where the arpeggios stop.
67
+ - **Shape match cuts** on the beat: clock → clock, arch → arch, grid of streets → grid of cells. A small-to-large punch-in on the same shape is allowed.
68
+ - **The grid** is the split screen of this style: 1×2 → 2×2 → 3×3 → 4×4, one stage per half bar or bar, the new cells lighting up in a scattered order over the previous stage within 0.3 s (never back to black), gutters 6 px black; in the last beat the cells re-cut on every sixteenth.
69
+ - **Counterpoint split**: two halves, archive left, today right, the same kind of place or shape; the gutter grows from the centre in 8 frames.
70
+ - **Day/night flicker**: the same camera, a noon frame and a night frame alternating every 2 frames; a pair of same-position photographs alternating every 2 frames.
71
+ - **Reverse flashback**: in the last bar before the hard stop, earlier shots return in reverse order, 4 frames each, then 2 frames each.
72
+ - Transitions: hard cuts only, plus the hard cut to black. No dissolves except fades from black for the page and the end card.
73
+
74
+ ## 7. Sound palette
75
+
76
+ - **Music only.** No narrator, no source sound (the footage soundtracks are other people's music), no sound effects. A narrator would turn watching into listening and would fight the score for the structure; that is why the style has none. If a voice is ever required, one short line at the very start or end, never over the cuts.
77
+ - Orchestration (sampled, CC0 — `core/audio/sampler.py`): pipe organ (full and soft stops, pedal), winds staccato (flute, clarinet), strings (spiccato cellos and violins, sustained cellos, violins, double bass), horn pair for the last two bars, concert bass drum on section downbeats, suspended-cymbal crescendos into the hits, glockenspiel only for numbers locking.
78
+ - Writing: arpeggios over a one-chord-per-bar progression; additive layering (eighths → triplets over eighths → sixteenths); the *break* is all arpeggios stopping at once into one held chord (maj7 or 9th); the return is a full-organ hit; the hard stop is a dry cut of every instrument in 15 ms with the reverb tail left ringing; the coda is one soft chord that does not resolve, with the opening figure returning in quarter notes under the end card.
79
+ - Reverb: `S.room(size .7, mix .28)` for the body, `size .78, mix .36` for the coda. Master to −14 LUFS / −1.2 dBTP with `core/render/mux.sh` (grain 0: the grain is already in the picture).
80
+
81
+ ## 8. Native moves (and how they are built)
82
+
83
+ | Move | Code |
84
+ |---|---|
85
+ | **Light river** | `tools/prep.py`: integrate the speed curve to source time; each output frame averages the source frames in its window (cap `blend`). Speed 40× / blend 30 at night, 37.5× / 24 for clouds, 75× / 30 for a one-second nightfall. |
86
+ | **Speed ramp** | `speed=[(t, v), …]` keyframes, smoothstep between them, same integrator. |
87
+ | **Brake into slow motion** | ramp 2.2× → 0.3× with `interp=3` (ffmpeg `minterpolate` mci, bidir) for soft subjects; `mix=True` (crossfade of the two nearest frames) for thin lines such as cables, where motion compensation tears. |
88
+ | **Crowd → tracks** (people as data) | `Trails` in `tools/render.py`: background = per-pixel median of the whole fixed-camera shot; blobs that differ by > 22/255 (scipy `ndimage.label`, area 8–900 px at half size) are people; each centroid joins the nearest one from the previous frame (< 70 px) with a 2 px line; lines fade × 0.9 per frame; the plate is darkened and desaturated as the tracks appear (0.15 → 0.55 s). Fixed cameras only. |
89
+ | **Traffic → light** | a static or slowly drifting top-down aerial at 5× with full frame blending. |
90
+ | **Grid** | `grid_plate()`: pool clips of 30 frames held in memory at 960×540; stages from `GRID_STAGES`; light-up order scattered; last beat re-cuts cells every sixteenth. |
91
+ | **Counterpoint split** | `split_plate()`: archive 4:3 centre 960 px | today centre 960 px, 6 px gutter grown from the centre. |
92
+ | **Day/night flicker** | two 15-frame clips from the same camera (noon, night), alternating every 2 frames. |
93
+ | **Photo that moves** | a same-position photo pair alternating every 2 frames. |
94
+ | **Number lock** | `lock_digits()`: one digit locks per sixteenth, the others roll; `counter()`: ease-out count-up; music adds one glockenspiel note per lock. |
95
+ | **Day ring** | a thin 24-hour ring bottom-right with a sodium hand and a 3-hour arc: it runs with the film's day, **freezes and dims during the brake**, and **spins backwards during the reverse flashback**. It is a graphic, not a clock reading. |
96
+ | **Reading light on a page** | scanned page, 16:9 window pushed 1.06 → 1.56 page widths, side light (bright top-left), paper tint (1, .93, .80), a Gaussian band (σ 95–140 px) over the quoted line growing to +38 %. |
97
+ | **Hard stop** | picture cuts to black on the bar line; the music's dry signal is cut in 15 ms on the same frame; only reverb remains. |
98
+
99
+ ## 9. Pitfalls of the medium
100
+
101
+ - **Watermarks and slates hidden in CC footage**: corner logos (scale from the centre until they leave frame, within 1.5×), opening thank-you cards, end-card music credits, title text over the first shots. Check a 1-second contact sheet (`tools/secsheet.py`) of every source before choosing in-points.
102
+ - **Hidden cuts inside sources.** Hyperlapse reels hide 2–3-frame jump cuts and whip transitions; frame blending across a cut makes ghosts. Scan with `ffmpeg … select='gt(scene,0.25)',showinfo` and keep every clip's source window inside one shot.
103
+ - **Too much blending** turns noon clouds into grey mush: about 40 % shutter (24 of 60 frames) looks better than 100 %.
104
+ - **Grey-world balance kills night**: it washes sodium light to white. Strength 0 for night shots.
105
+ - **Tracking needs a fixed camera.** A drifting drone flags every building as motion. Use a median background only on tripod shots; for moving aerials use blending instead.
106
+ - **Motion-compensated slow motion tears thin lines** (cables, rails, text): use the crossfade mode there.
107
+ - **Text over bright sky** disappears: put number cards over the dark half of the frame or add the soft darkening; never a box.
108
+ - **A slow face is not a free subject.** Do not make an identifiable ordinary person the slowed or close-up hero. Slow a thing; show people as crowds, tracks or ghosts. Public figures and people in news events are a different case.
109
+ - **Numbers drift.** Official pages update; quote the page and the year, keep the quote in `FACTS.md`, and recheck before the last render. Prefer one clean figure over a range.
110
+ - **CC BY credits are long.** Each one needs author, full title and licence on the end card. Treat them as fine print (16 px, 29 px line pitch, the licence and changes on one header line) and keep the end card short (4–5 s); a 10 s card of text on black loses the audience. The film's last moving shot runs on under the card, darkened.
111
+ - **Don't end on dead black.** After the hard stop, the coda is a page (≈1 s), then the quote laid over one last moving city shot (≈4 s, just long enough to pass `readcheck`), then the end card over the same shot.
112
+ - Commons rate-limits (HTTP 429): search and download serially with back-off (`tools/s.sh`, `tools/f.sh`); for long 4K files download only the needed excerpt (`tools/seg.py`) or the 1080p transcode.
113
+
114
+ ## 10. Footage: where it comes from
115
+
116
+ 1. **Ask the user first** whether they have their own footage, photographs, documents or data for the place: their own time-lapses, a phone hyperlapse, family photos, a city's open data. Their material comes first.
117
+ 2. If not, search these sources (all searchable with `demo/tools/footage.py`, which records title, author, licence and page in `SOURCES.jsonl` and writes `SOURCES.md`):
118
+ - **Wikimedia Commons** — modern time-lapse, aerial and slow-motion footage under CC BY / CC0, photographs (for example the Carol M. Highsmith Archive, dedicated to the public domain), scans of old maps and books. Check the licence on each file page. Many videos are YouTube or Vimeo imports: use one only when its page carries a passed review (YouTubeReview / VimeoReview / LicenseReview / Flickrreview with a reviewer and a date) or the author's own source page still shows the licence. A pending review is not enough: a channel can later switch to the standard licence and claim the footage through Content ID.
119
+ - **Library of Congress** (loc.gov, also mirrored on Commons) — archive films published in the US before 1931 are public domain; a rights statement of "no known restrictions" alone is **not** enough: you need the publication date or another public-domain basis.
120
+ - **NASA** (images.nasa.gov, ISS crew photographs) — public domain; the night photos of cities from orbit make a strong opening.
121
+ - **Internet Archive** — scanned books and documents marked NOT_IN_COPYRIGHT with a pre-1931 publication date; take the line you quote from the scan, not from a modern edition.
122
+ - **National archives** (US National Archives, other governments' open archives) — check each country's terms.
123
+ - Licences allowed: public domain, CC0, CC BY. Not allowed: CC BY-SA, "no known restrictions" without a basis, YouTube mirrors, unknown sources, restored or colourised archive copies.
124
+ 3. **Before downloading, tell the user** what you will download, from where, under which licence, and how it will be credited.
125
+
126
+ Data for number cards comes from official pages (census, transport department, the place's own statistics); write the claim, URL and quoted wording into `FACTS.md`.
127
+
128
+ Recipe for another place: one single-camera time-lapse of ≥ 12 hours (the clock); 10–15 ground time-lapses and hyperlapses (streets, stations, bridges); 2–4 aerials, one of them top-down at night; one slow-motion shot of a fragile thing; one fixed-camera crowd shot for tracks; one archive film of the same kind of place; one night photograph from orbit or above; a same-position photo pair; three official numbers; one public-domain sentence written about the place.
129
+
130
+ ## 11. Variation space
131
+
132
+ - Place: any city, port, airport, market, campus, factory, a river over a year (the clock becomes a season).
133
+ - Length: 30–90 s; one brake at least; one hard stop always.
134
+ - Score: organ/winds/strings is the default; a choir, a piano ensemble or analogue synth arpeggios also work if the writing stays additive and the break stays a sudden held chord.
135
+ - Tempo 96–132 BPM; at 30 fps prefer tempos whose beat is a whole number of frames (120: 15, 100: 18, 112.5: 16).
136
+ - Grid sizes and the counterpoint pair change with the material (archive vs today, day vs night, two cities).
137
+ - Number cards: 2–4 at most; the day ring may be dropped for non-daily structures.
138
+ - Fixed: footage only, the frame-blended light, cuts on the beat, the brake, few words, one quote, the hard stop, the release-print grade.
139
+
140
+ See [`DEMO.md`](DEMO.md) for the example film.