@machinal/mcp 0.0.0-stage → 0.4.0
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.
- package/README.md +361 -2
- package/bin/machinal-mcp.mjs +19 -0
- package/bin/machinal-stdio.mjs +14 -0
- package/package.json +47 -4
- package/skills/machinal-cinema/SKILL.md +18 -0
- package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
- package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
- package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
- package/skills/machinal-cinema/references/film-library/README.md +13 -0
- package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
- package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
- package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
- package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
- package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
- package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
- package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
- package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
- package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
- package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
- package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
- package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
- package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
- package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
- package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
- package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
- package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
- package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
- package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
- package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
- package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
- package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
- package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
- package/skills/machinal-cinema/references/film-styles.json +1322 -0
- package/skills/machinal-cinema/references/film-techniques.json +107 -0
- package/skills/machinal-cinema/references/workflow.md +58 -0
- package/skills/machinal-credits/SKILL.md +24 -0
- package/skills/machinal-editing/SKILL.md +43 -0
- package/skills/machinal-editing/references/brief.md +98 -0
- package/skills/machinal-editing/references/effects.md +58 -0
- package/skills/machinal-editing/references/looks-motion.md +37 -0
- package/skills/machinal-editing/references/styles.json +15 -0
- package/skills/machinal-editing/references/styles.md +16 -0
- package/skills/machinal-editing/references/transitions.md +46 -0
- package/skills/machinal-editing/references/workflow.md +43 -0
- package/skills/machinal-media/SKILL.md +23 -0
- package/skills/machinal-media/references/workflow.md +160 -0
- package/skills/machinal-recipes/SKILL.md +32 -0
- package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
- package/skills/machinal-recipes/references/commands.md +45 -0
- package/skills/machinal-recipes/references/example.edit.yaml +26 -0
- package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
- package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
- package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
- package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
- package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
- package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
- package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
- package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
- package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
- package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
- package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
- package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
- package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
- package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
- package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
- package/skills/machinal-recipes/references/examples.md +28 -0
- package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
- package/skills/machinal-recipes/references/text-audio.md +118 -0
- package/skills/machinal-recipes/references/yaml.md +72 -0
- package/skills/machinal-review/SKILL.md +18 -0
- package/skills/machinal-review/references/production.md +146 -0
- package/skills/machinal-scenes/SKILL.md +44 -0
- package/skills/machinal-scenes/references/authoring.md +97 -0
- package/skills/machinal-scenes/references/runtime.md +136 -0
- package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
- package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
- package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
- package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
- package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
- package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
- package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
- package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
- package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
- package/skills/machinal-scenes/references/scene-templates.json +178 -0
- package/skills/machinal-scenes/references/scene-templates.md +50 -0
- package/skills/machinal-scenes/references/workflow.md +206 -0
- package/skills/machinal-support/SKILL.md +42 -0
- package/src/bridge.mjs +285 -0
- package/src/cli.mjs +155 -0
- package/src/configuration.mjs +148 -0
- package/src/connection.mjs +187 -0
- package/src/credential-store.mjs +61 -0
- package/src/credits.mjs +86 -0
- package/src/docker.mjs +93 -0
- package/src/download.mjs +90 -0
- package/src/errors.mjs +9 -0
- package/src/formats.mjs +140 -0
- package/src/keys.mjs +127 -0
- package/src/launch.mjs +29 -0
- package/src/local-setup.mjs +109 -0
- package/src/opencode-auth.mjs +246 -0
- package/src/opencode-checkpoints.mjs +90 -0
- package/src/opencode-configuration.mjs +53 -0
- package/src/opencode-media.mjs +139 -0
- package/src/opencode-plugin/index.mjs +7 -0
- package/src/opencode-plugin/package.json +5 -0
- package/src/opencode-recipes.mjs +130 -0
- package/src/opencode-routing.mjs +154 -0
- package/src/opencode-tools.mjs +30 -0
- package/src/opencode-workflow.mjs +32 -0
- package/src/presentation.mjs +30 -0
- package/src/prompts.mjs +32 -0
- package/src/reference-files.json +127 -0
- package/src/runtime.mjs +51 -0
- package/src/setup-options.mjs +64 -0
- package/src/setup-stdio.mjs +114 -0
- package/src/setup.mjs +173 -0
- package/src/skills.mjs +68 -0
- package/src/transfer-http.mjs +109 -0
- package/src/version.mjs +3 -0
- package/src/windows-key-prompt.mjs +37 -0
- package/src/windows-key-prompt.ps1 +77 -0
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Directing a cinematic film
|
|
2
|
+
|
|
3
|
+
The directing method behind every film in this library. Pair it with one `styles/<slug>/STYLE.md` (the style) and [`TECHNIQUE.md`](TECHNIQUE.md) (how to build).
|
|
4
|
+
|
|
5
|
+
You are the director, not a tech demo. A film is judged in this order: **sound, rhythm, camera, directing** (performance, staging, emotional arc). Good-looking frames are only the starting point.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Take the brief
|
|
10
|
+
|
|
11
|
+
The user gives a style and a topic, sometimes more (length, language, voice, must-have shots, brand rules). Everything else is your decision. Ask once, in a single message (AGENTS.md, Workflow), then no more questions. Defaults:
|
|
12
|
+
|
|
13
|
+
- Length **30–60 s**; shorter and tight beats padded. Beyond two or three minutes multiplies time and token cost: tell the user.
|
|
14
|
+
- 1920×1080 at 24 fps by default; an output frame rate set in the style's `STYLE.md` (30 or 60 fps, for example) wins, and is what you pass to `--fps` and `mux.sh`; other sizes (vertical 1080×1920, for example) with `--size WxH` on the render tools.
|
|
15
|
+
- Voice and subtitles in the language the user writes in. Subtitles burned in and exported as `.srt`.
|
|
16
|
+
- Loudness −14 LUFS.
|
|
17
|
+
|
|
18
|
+
Say it in the questions when it matters: a good Chinese voice uses Microsoft's online service (edge-tts) and needs a connection; offline, Kokoro reads Chinese but sounds plain (TECHNIQUE.md §4).
|
|
19
|
+
|
|
20
|
+
Requests that only change the plan:
|
|
21
|
+
|
|
22
|
+
- **No voice, or no subtitles.** Drop those steps and say so in the treatment.
|
|
23
|
+
- **Their own voice recording.** Use it as it is; transcribe it with faster-whisper for word timings.
|
|
24
|
+
- **Their own material**: logos, photos, footage, and for styles built from real material (the Evidence Films) their own data, scans, imagery or CAD. Ask whether they have any; what they give comes first, and the sources in the `STYLE.md` are the fallback. Before you download from those sources, tell the user what you will fetch, from where and under which licence. Rights: section 12.
|
|
25
|
+
|
|
26
|
+
## 2. Find a benchmark first
|
|
27
|
+
|
|
28
|
+
Before writing anything, pick one or two reference works (films, title sequences, games, ads) that set the bar for this style **and this topic**. They are your choice, made for the user's film; don't borrow the demo's. Write down:
|
|
29
|
+
|
|
30
|
+
- **What to learn**: composition, pacing, camera grammar, colour logic, score structure.
|
|
31
|
+
- **What not to take**: characters, designs, melodies, specific shots, logos, fonts.
|
|
32
|
+
|
|
33
|
+
The benchmark lifts quality more than any rule below.
|
|
34
|
+
|
|
35
|
+
## 3. Shape the story
|
|
36
|
+
|
|
37
|
+
- **One subject, one goal, one turn.** A character (or a single object, product or idea) wants something, something changes, it ends differently from how it began.
|
|
38
|
+
- **Hook in the first 3 seconds.** No slow logo reveal before anything happens.
|
|
39
|
+
- **An ending that echoes.** Bookend the opening, reveal the scale, or let the character do the thing right the second time.
|
|
40
|
+
- **One native move**: a moment only this medium can do (a fold that becomes a transition, ink that blooms into the next scene, a type grid that snaps into the logo). Put it at the emotional peak. `STYLE.md` lists the medium's native moves; pick or invent the one your story needs.
|
|
41
|
+
- **Cut the extras.** One gag the audience reads at thumbnail size beats three they can't. If a beat needs explaining, remove it.
|
|
42
|
+
|
|
43
|
+
## 4. Write the treatment
|
|
44
|
+
|
|
45
|
+
Write `TREATMENT.md` before drawing anything, and before you open the style's `DEMO.md` or demo code (an Edit & Documentary style gathers its material first: AGENTS.md, "Treatment first"):
|
|
46
|
+
|
|
47
|
+
1. **Three candidate structures**, a few lines each (for example: a single journey, a before/after, a countdown, a list that turns), then the one you chose and why. Choose the opening image, the ending and the shape of the score from the topic too; the first idea that comes to mind for a style is usually its cliché.
|
|
48
|
+
2. **Logline and arc**: one sentence, then setup → turn → ending.
|
|
49
|
+
3. **Benchmark**: learn / don't learn (section 2).
|
|
50
|
+
4. **Shot list**: for every shot, the framing (wide / full / medium / close / insert), angle, camera move (push, pull, pan, track, crane, zoom), duration, and **why** it is shot that way.
|
|
51
|
+
5. **Beat sheet**, second by second.
|
|
52
|
+
6. **Cue map**: tempo, bar grid, instrumentation per section, and on which beat every cut, key action and subtitle lands.
|
|
53
|
+
7. **Sound design table**: for each section, the ambience bed, the main foley and the music state.
|
|
54
|
+
8. **Subtitle and title design**: the type is part of the style.
|
|
55
|
+
|
|
56
|
+
## 5. Prove the look
|
|
57
|
+
|
|
58
|
+
- **With characters**: draw a model sheet (turnaround, 3–4 expressions, 2–3 key poses, palette) plus two style frames.
|
|
59
|
+
- **Without characters**: three style frames from the film, one of them the signature shot.
|
|
60
|
+
|
|
61
|
+
Render them with the real drawing code, not a mock-up, and check them yourself against the `STYLE.md` before going on.
|
|
62
|
+
|
|
63
|
+
### The storyboard (only if the user asked for one)
|
|
64
|
+
|
|
65
|
+
Render 6–9 key shots with the real drawing code, tiled into one sheet (`core/render/sheet.py`) with shot number, framing, duration and line under each. Send it with the logline and what you are least sure about, and **wait for approval**. If the user didn't ask for one, don't stop.
|
|
66
|
+
|
|
67
|
+
## 6. Sound is half the film
|
|
68
|
+
|
|
69
|
+
- **Every visible action has a sound**: landings, page turns, cuts, drips, clicks, cloth. Match the material (paper, wood, metal, ink and glass all sound different).
|
|
70
|
+
- **Three layers**: ambience (room, wind, rain, city), foley (tied to actions) and music. Duck the music under dialogue and key foley.
|
|
71
|
+
- **At least two real silences**, or near-silences, before the turn or the emotional peak. The first sound after the silence should be one of the most important sounds in the film.
|
|
72
|
+
- **Use sound as a transition** at least twice: bring the next scene's sound in early (J-cut) or let the last scene's sound run over the cut (L-cut).
|
|
73
|
+
- **Avoid generic "piano and strings".** Score in the instruments of the style's sound palette.
|
|
74
|
+
|
|
75
|
+
## 7. Rhythm: the music grid comes first
|
|
76
|
+
|
|
77
|
+
- Write the cue map before animating. The picture locks to the grid, and a script checks every cue (TECHNIQUE.md §3).
|
|
78
|
+
- **Vary the pace**: alternate fast and slow, include one clear acceleration or deceleration, and give the audience one breath (a long take or a held pause). A film at one even speed has failed.
|
|
79
|
+
- One action, one sound, one cut, but don't cut on every beat. Leave time to see.
|
|
80
|
+
- **Pace for the viewer, not the clock**:
|
|
81
|
+
- Hold every subtitle at least 1.8 s, and never shorter than the spoken line + 0.6 s.
|
|
82
|
+
- After text finishes animating in, hold it for roughly (letters ÷ 15 + 1.5) s in English, (characters ÷ 4.5 + 1.5) s in Chinese; `readcheck.mjs` checks this for you.
|
|
83
|
+
- Hold a title card at least 4 s.
|
|
84
|
+
- Give failures and gags enough time to be understood.
|
|
85
|
+
- Fast is fine; make it fast with fewer words per screen, not by cutting before people finish reading.
|
|
86
|
+
|
|
87
|
+
## 8. Camera: every shot needs a reason
|
|
88
|
+
|
|
89
|
+
- Use at least **four different camera moves** and real changes of framing. 2D has a camera too: push, pull, parallax, focus pulls, frames within frames.
|
|
90
|
+
- **One signature shot** people remember: a oner, a scale reveal, a transition made from the medium itself.
|
|
91
|
+
- **Design transitions inside the medium** (a page turn, a carved line growing, ink spreading), as one consistent grammar. Avoid default fades and hard cuts.
|
|
92
|
+
- At key moments the subject fills at least a third of the frame height, with clear staging and a readable silhouette.
|
|
93
|
+
|
|
94
|
+
## 9. Performance
|
|
95
|
+
|
|
96
|
+
- **Anticipation, action, follow-through** on every meaningful move. Characters change emotion. They do not just slide across the screen.
|
|
97
|
+
- **Motion continuity**, especially for characters built from code rigs:
|
|
98
|
+
- Blend every pose with keyframes and easing; never switch poses inside an `if`. The only exception is a deliberate one-frame comic pop.
|
|
99
|
+
- Check shoulders and arms on a large action test sheet (reach, raise, run, kneel) before shooting (TECHNIQUE.md §10).
|
|
100
|
+
- Held props sit **between the palms**, at a depth between the two arms. A hand-over interpolates from one palm to the other. A rolling object turns by distance ÷ radius.
|
|
101
|
+
- Step through key actions at 0.2 s intervals, enlarged.
|
|
102
|
+
- Check every expression at final size, especially eyebrow direction: "worried" and "angry" are one flip apart.
|
|
103
|
+
|
|
104
|
+
## 10. The failures we saw most
|
|
105
|
+
|
|
106
|
+
- Subject too small, too far away, or pushed against the frame edge.
|
|
107
|
+
- Too dark to read, or a colour laid on the same colour (red on red).
|
|
108
|
+
- Subtitles covering the subject.
|
|
109
|
+
- A gag or failure too fast to understand.
|
|
110
|
+
- Blank frames in transitions.
|
|
111
|
+
- A timed effect (iris, zoom, follow cam) that doesn't track the subject after the camera moves (one world → screen function, TECHNIQUE.md §2).
|
|
112
|
+
|
|
113
|
+
## 11. Before you deliver
|
|
114
|
+
|
|
115
|
+
- Run the review loop (TECHNIQUE.md §8): contact sheets, 0.2 s strips of key actions, one full-speed viewing with sound.
|
|
116
|
+
- **One fix round.** Fix everything the review and the checks below find in one round, then check once more. Small fixes that second check turns up (a level, a frame) belong to the same round; anything bigger, tell the user in one line when you deliver. The user's notes after delivery are new rounds: change only what they ask.
|
|
117
|
+
- **Not the demo again.** After the treatment, read `DEMO.md` and compare: structure, opening, signature shot, camera path, score shape, ending. At least four of the six must differ; rethink the ones that match. Before delivery, put your contact sheet next to the demo poster (`styles/<slug>/poster.jpg`) as a last check.
|
|
118
|
+
- Voice: every line transcribes back correctly (speech-to-text check). For Chinese, one misheard character in a short line is normal: listen, and if it is right, let the check expect what the model heard (TECHNIQUE.md §4).
|
|
119
|
+
- Loudness about −14 LUFS; no black frames, no NaN frames; subtitles in sync and not covering key action.
|
|
120
|
+
- Every row of the sound design table is actually in the mix.
|
|
121
|
+
- Every map, globe or satellite view passes section 13, checked enlarged.
|
|
122
|
+
- No LemoLab sign-off: `grep -rniE "lemo ?lab|opus 5\.5" <project folder>` finds nothing outside `LICENSE`, `CREDITS` and the library's path in `LIB=` lines, and you have watched the last seconds of the film (text drawn into an image can't be grepped).
|
|
123
|
+
|
|
124
|
+
**Deliver**, in the project folder (the complete list):
|
|
125
|
+
|
|
126
|
+
- `<name>.mp4` (24 fps unless `STYLE.md` sets another rate, about −14 LUFS) and `poster.jpg`;
|
|
127
|
+
- `<name>.srt`, when the film has narration, dialogue or subtitles;
|
|
128
|
+
- `TREATMENT.md`;
|
|
129
|
+
- `CREDITS`: every third-party asset in the film (sample libraries, music, fonts, images, the voice engine) with its source and licence (TECHNIQUE.md §11);
|
|
130
|
+
- the source, with a one-command `build.sh` (TECHNIQUE.md §2).
|
|
131
|
+
|
|
132
|
+
**Tell the user**, in their language: where the project folder and the film are; that `CREDITS` lists the third-party assets in the film and their licences; and that they are responsible for the materials they use in it.
|
|
133
|
+
|
|
134
|
+
## 12. Copyright red lines
|
|
135
|
+
|
|
136
|
+
- References teach grammar only. Don't copy characters, designs, melodies, shots, logos or type designs.
|
|
137
|
+
- No existing works, games, brands or events appear in the film unless the user owns them or has the right to use them. That includes the logos, photos and footage the user hands you: use them when they say they have the right, otherwise draw fictional stand-ins.
|
|
138
|
+
- Some of our demos are unofficial fan films of real events or characters. Keep the style, and never carry those names, marks or characters into a user's film.
|
|
139
|
+
|
|
140
|
+
## 13. Maps
|
|
141
|
+
|
|
142
|
+
These apply to every frame that shows a map, a globe or satellite imagery, in every style.
|
|
143
|
+
|
|
144
|
+
- **No borders unless the film is about them.** Draw coastlines, terrain, imagery or streets, without national or provincial borders. Prefer a regional view to a world map, and keep disputed areas out of frame.
|
|
145
|
+
- **When China is in frame, draw all of it.** Taiwan, Hainan, the South China Sea islands with the dashed line (in frame, or in an inset), and the Diaoyu Islands with Chiwei Yu. Taiwan and the mainland are one country, in the same colour and the same treatment. Zangnan and Aksai Chin are drawn as on China's standard map.
|
|
146
|
+
- **Default border data doesn't meet this.** The default boundaries of Natural Earth, world-atlas and OpenStreetMap can't be used to draw China. When the film needs borders, use China-view data (such as Natural Earth's `admin_0_countries_chn` layers, checked against the standard map) or China's standard map service (bzdt.ch.mnr.gov.cn).
|
|
147
|
+
- **Words follow the same map.** Taiwan, Hong Kong and Macao are never listed as countries: not in labels, legends, subtitles, the voice-over or data tables. A list that includes them is "countries and regions". Clean a dataset's country field before you chart it.
|
|
148
|
+
- **Other disputed areas**: the same; frame them out, or leave their borders undrawn.
|
|
149
|
+
- **Check and credit.** Before delivery, enlarge every map shot and check it against these rules. `CREDITS` names the map data, its source and its view (for example "Natural Earth 1:50m, China view").
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LemoLab
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Make a style your own
|
|
2
|
+
|
|
3
|
+
A user makes a style of their own, in one of two ways: **change a library style**, or **start from a blank page**. You plan it with them, one question at a time or in free conversation, prove the look with a style frame and make a short demo film. When they confirm it, you keep it in their own folder in the same shape as a library style. From then on they name it like any library style when they ask for a film. It lives outside the library and never changes it.
|
|
4
|
+
|
|
5
|
+
Use this guide when the user wants to change a style or make their own ("I want to change this style", "make my own version", "start from scratch", "我想改风格", "做成我自己的风格", "从空白开始"), or when they name a style that is in their own folder. Everything else in a film follows [`AGENTS.md`](AGENTS.md) as usual, with the exceptions this guide gives.
|
|
6
|
+
|
|
7
|
+
Talk to the user in their language. Write the files in English, like the library, with the style's name in both languages.
|
|
8
|
+
|
|
9
|
+
## Where it lives
|
|
10
|
+
|
|
11
|
+
Until the user confirms it (§6), a style is a draft in the demo film's project folder. Confirmed styles live in **`~/lemo-my-styles/`**, outside the library, so library updates and uninstalling never touch them. `~/lemo-my-styles/README.md` lists every style, one row each (English and Chinese name, slug, base, one line on what it is, and the folder when it isn't in `~/lemo-my-styles/`): it's how a later session finds a style by name. If the user wants a style kept in another folder, keep it there and still add its row, with the full path, to `~/lemo-my-styles/README.md`.
|
|
12
|
+
|
|
13
|
+
Each style has its own folder, `~/lemo-my-styles/<slug>/`, shaped like a library style (`MAINTAINING.md` **Add a style**, without the gallery and the release):
|
|
14
|
+
|
|
15
|
+
| File | What it holds |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `style.json` | `slug`, `en`, `cn`, `based_on` (the base slug; from a blank page, the technique base), `borrows` (slugs moves were taken from, may be empty), `size` (only when the default isn't 1920×1080, e.g. `"1080x1440"`), `library_version` (`git -C "$LIB" rev-parse --short HEAD`, or the plugin version when `$LIB` isn't a git clone), `created`, `line`, `line_cn` |
|
|
18
|
+
| `STYLE.md` | the style's invariants only, in the sections of a library `STYLE.md` (11 in most; a changed style keeps its base's): no story, beat table, durations or end card |
|
|
19
|
+
| `CHANGES.md` | one row per decision: section, base, now, why. From a blank page, "base" is the technique base's value, or "—" for something new. This is what the user approves and what you check the demo film against |
|
|
20
|
+
| `DEMO.md` | how the demo film was made, like a library `DEMO.md`: it opens with "One example among many. Don't reuse its story, arc, shots, props or timings.", then the story, shots, palette, score, build notes and which file draws what. It stands in for the film's `TREATMENT.md`, which isn't kept |
|
|
21
|
+
| `demo/` | the demo film's source with a one-command `build.sh` and `CREDITS`: the code and the small assets it needs to rebuild (fonts, data), not renders, frames, `node_modules`, virtual environments or caches |
|
|
22
|
+
| `styleframe.jpg` | the approved style frame |
|
|
23
|
+
| `styleframe-vs-base.jpg` | changing a library style only: the same frame, base on the left, theirs on the right |
|
|
24
|
+
| `test.mp4`, `test.jpg` | the demo film and its poster |
|
|
25
|
+
|
|
26
|
+
Never write into `styles/` or edit the library's guides for this. The name and slug must not match a library style or a row in `~/lemo-my-styles/README.md`.
|
|
27
|
+
|
|
28
|
+
## 1. Where to start
|
|
29
|
+
|
|
30
|
+
- **Change a library style.** The user names one (see **Finding the style** in `AGENTS.md`). If they haven't, do as **Finding the style** does for a film: the full list of library styles in your message, the gallery link, two or three suggestions on top when you know what they'll use it for, then a plain-text question asking them to type the name (not `AskUserQuestion`). One base only. If they want to mix two, take the one whose §1 *Essence* is closest as the base and take only what they want from the other, as changes (list it in `borrows`).
|
|
31
|
+
- **Start from a blank page.** The user describes the look in their own words, or brings a picture or a film they like. Choose one library style as the **technique base** (the closest materials and engine: what the code will build on) and at most two to borrow moves from. Make that the first question: your choice and why in one line each, with the next closest as the other options.
|
|
32
|
+
|
|
33
|
+
Either way, read the base `STYLE.md` in full before the first question. In this flow you may read the base's `DEMO.md` (and, in skill mode, get its source with `setup.sh demo <slug>`) before any treatment: the style frame needs its techniques. The demo film's story must still differ from the base demo's (DIRECTOR.md §11, *Not the demo again*, compared with the base).
|
|
34
|
+
|
|
35
|
+
## 2. Plan it together
|
|
36
|
+
|
|
37
|
+
Interview the user until every section of their `STYLE.md` is decided and they know what each choice costs.
|
|
38
|
+
|
|
39
|
+
**How to ask**
|
|
40
|
+
|
|
41
|
+
- **One question per message.** Use the `AskUserQuestion` tool: 2–3 options, the one you recommend first and marked (Recommended), each with one line on what it does to the film, and **Free conversation** (in their language) as the last option. Without the tool, a short numbered list with your recommendation, and free conversation as its last line.
|
|
42
|
+
- **Free conversation.** When they pick it, stop asking one by one. Post in the chat a checklist: what's decided, and each open item with your recommendation (when changing a library style, also its group from the table below). They answer in their own words, in any order, several at once, or ask you back. When they aren't sure about an item, give two or three concrete directions for it. Update the checklist each round; when everything is decided, or they say "you decide", go to the summary.
|
|
43
|
+
- Every question has your recommendation and the reason, drawn from the base `STYLE.md` and what the user said, with concrete examples from this style, not generic words.
|
|
44
|
+
- Don't ask what you can look up (the base `STYLE.md`, the library, their files).
|
|
45
|
+
- **About ten questions at most**, the technique base included. When more sections are in play, ask related ones together (motion with sound, camera with native moves). If they say "you decide" ("你定", "都按推荐"), take your recommendations for the rest, list them in one message and go on.
|
|
46
|
+
|
|
47
|
+
**The order** (skip what they've already said):
|
|
48
|
+
|
|
49
|
+
1. **Use.** What films they'll make with it, for whom, where they'll post them, and so the frame size (a vertical feed needs 1080×1920 or 1080×1440). Their brand or IP: colours, logo, font, a character. They give you the files later.
|
|
50
|
+
2. **What changes.**
|
|
51
|
+
- *Change a library style*: first show the three groups as a short message, using this style's own sections and examples. Then ask which parts they want to touch (several may be picked).
|
|
52
|
+
|
|
53
|
+
Section numbers below are the usual ones; some styles (Edit & Documentary above all) number or split them differently, so go by the section's subject in the base `STYLE.md`.
|
|
54
|
+
|
|
55
|
+
| Group | Sections of `STYLE.md` | What to tell the user |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| **Safe to change** | §3 colour (the palette within its logic), §4 type, §5 motion (tempo, how much moves), §7 sound palette (instruments, density), §8 native moves (add or swap one) | the style stays itself; give 2–3 ideas for each |
|
|
58
|
+
| **Changes its character** | §2 materials and rendering, the colour logic itself in §3, §6 camera grammar | possible; say what the style loses with each change |
|
|
59
|
+
| **Can't change** | §1 essence (and its "what it is not"), §10 engine | that's a different style, not a version of this one. Say so and suggest a closer base |
|
|
60
|
+
|
|
61
|
+
When a safe change narrows a phrase in §1 (three inks become two), adjust that phrase; the essence stays.
|
|
62
|
+
- *From a blank page*: the essence first, one sentence on what it is and one on what it is not. Then the materials.
|
|
63
|
+
3. **Section by section**, only the sections in play, in `STYLE.md` order: materials and rendering, colour, type, motion, camera, sound, native moves. Give 2–3 concrete directions for each.
|
|
64
|
+
4. **The name**: English, Chinese or both, and the slug.
|
|
65
|
+
|
|
66
|
+
**Help them change it well.** Most users know the feeling they want, not the section. While you ask:
|
|
67
|
+
|
|
68
|
+
- Start from the use. The changes follow what the films are for: a weekly brand bulletin needs readable type and a fixed opening, a kids' channel needs bigger shapes and slower reading.
|
|
69
|
+
- Turn vague wishes into options, never silent edits:
|
|
70
|
+
|
|
71
|
+
| They say | Usually means |
|
|
72
|
+
|---|---|
|
|
73
|
+
| more premium, 高级 | fewer colours, stronger contrast between light and dark, slower motion, more empty space, lighter type |
|
|
74
|
+
| younger, livelier, 活泼 | a brighter accent, cuts on the beat, bouncier easing, more percussion |
|
|
75
|
+
| calmer, 安静 | slower tempo, longer holds, fewer moving things, sparser instruments |
|
|
76
|
+
| like our brand, 像我们品牌 | the brand colour as the accent, not the ground; the brand font for titles; the logo at the open and the end |
|
|
77
|
+
|
|
78
|
+
- **Brand.** Keep the base's light-and-dark structure so text stays readable, and bring the brand colour in as the accent first. A brand font must cover the film's language (Chinese glyphs for a Chinese film) and allow use in video. Logos and fonts come from the user.
|
|
79
|
+
- **A reference.** Name two or three things in it that make it work, map each to a section, and say which ones would touch §1 essence.
|
|
80
|
+
- **Keep the signature.** The native move is what makes the style recognisable: swap at most one.
|
|
81
|
+
- **Changes that travel together.** Faster motion needs denser sound. A darker palette needs the type contrast checked. A new material brings its own pitfalls into §9.
|
|
82
|
+
- **Up to five changes** per round when changing a library style; more are hard to judge. A change the film's language forces (a Chinese font when the base has none) doesn't count.
|
|
83
|
+
- **Code draws everything**, as in the library: no image or video generation, which the user may not have. Anything that isn't code (pictures, fonts, stroke or map data, samples) is the user's own or openly licensed, as in TECHNIQUE.md §11, and named in `CREDITS`. A licence the user has to agree to is asked once, and their answer goes into `STYLE.md` so later films don't ask again. If something can't work, say so and offer the closest change code can draw.
|
|
84
|
+
- **What doesn't need a style.** Story, structure, opening, ending, cast, sets, pacing and voice (§11 *Variation space*) are free in every film. If that's all they want, they don't need their own style: they say it when they ask for a film.
|
|
85
|
+
|
|
86
|
+
When the plan is complete, show the user a short summary in their language: each decision, before and after, and what it costs. **Wait for their OK**, then write it down.
|
|
87
|
+
|
|
88
|
+
## 3. Write it down
|
|
89
|
+
|
|
90
|
+
Make the demo film's project folder now (`films/<slug>-test/` in a clone, `<slug>-test/` in the user's folder in skill mode) and work only there until §6. The draft style goes in its `style/` folder, with the files of the table above.
|
|
91
|
+
|
|
92
|
+
- **`STYLE.md`**:
|
|
93
|
+
- *Change a library style*: a full copy of the base `STYLE.md` with the changes written into their sections, so it reads like any style prompt (no "see the base" gaps). Change the title to the new name and add one line under it: `Based on <base name> (<base slug>) from the cinematic reference library.`
|
|
94
|
+
- *From a blank page*: all 11 sections written from the plan, with §10 engine from the technique base for now (§5 points it at the style's own code). Under the title: `Made from a blank page; techniques from <base name> (<base slug>) in the cinematic reference library.`
|
|
95
|
+
- When the default size isn't 1920×1080, one more line under the title: `Default size: 1080×1440.`
|
|
96
|
+
- Links: the style's own `DEMO.md` and `demo/` (they exist after §5) stay relative; links to the base become `$LIB/styles/<base slug>/…`. Keep every pitfall in §9 that still applies, and add the ones the changes bring.
|
|
97
|
+
- **`CHANGES.md`** and **`style.json`** as in the table above.
|
|
98
|
+
|
|
99
|
+
## 4. Prove the look
|
|
100
|
+
|
|
101
|
+
Render one style frame with the real drawing code, starting from the base style's techniques (copy code into the project, never edit the library). Check it against the new `STYLE.md` and fix what's off, once.
|
|
102
|
+
|
|
103
|
+
- *Change a library style*: render the same frame a second time with the base's settings (its colours, materials and type; a stand-in font when the base's has no glyphs for the film's language), and put the two side by side, base on the left, so only the changes differ: `style/styleframe-vs-base.jpg` (`core/render/sheet.py` tiles stills).
|
|
104
|
+
- *From a blank page*: there's nothing to compare against. Show the frame on its own, next to the user's reference if they gave one.
|
|
105
|
+
|
|
106
|
+
Save the frame as `style/styleframe.jpg`. **Show it to the user and wait.** If they want more, update `STYLE.md` and `CHANGES.md` and render again. If it still isn't right after two rounds of their notes, say so and suggest a closer base.
|
|
107
|
+
|
|
108
|
+
## 5. The demo film (15–30 s)
|
|
109
|
+
|
|
110
|
+
A short film whose job is to show the style working, not a full production:
|
|
111
|
+
|
|
112
|
+
- **Topic**: the user's own if they give one; otherwise a simple one with movement and a little light (a kite on a windy beach, the first tram of the morning). Not the base demo's story.
|
|
113
|
+
- **Every row of `CHANGES.md` is clearly on screen** at least once, and the native move appears once.
|
|
114
|
+
- Music and sound effects, no voice and no subtitles unless the user asks (a voice is a separate test).
|
|
115
|
+
- Treatment: one structure is enough (no three candidates). No storyboard. DIRECTOR.md's counts are written for longer films: at this length one real silence and three kinds of camera move are enough.
|
|
116
|
+
- **Checks**, as for any film: DIRECTOR.md §11, with its one fix round (no LemoLab sign-off in the film).
|
|
117
|
+
|
|
118
|
+
Then save it into `style/`:
|
|
119
|
+
|
|
120
|
+
- the film and its poster as `test.mp4` and `test.jpg`;
|
|
121
|
+
- the source as `demo/`, with `CREDITS` and a `build.sh` that runs from there: `LIB=<path>` at the top, library files as `$LIB/…` (never `../..`, also in code copied from the base), and everything it writes going to `${OUT:-<a folder outside demo/>}`. Run it once from the saved folder with `OUT` set to a temporary folder, and check that `demo/` holds the same files afterwards. Code copied from the library keeps its MIT notice in `demo/CREDITS`; that is a licence, not a credit in the film;
|
|
122
|
+
- `DEMO.md`;
|
|
123
|
+
- From a blank page, point §10 *Engine* in `STYLE.md` at the files in `demo/` that draw the style, then at the technique base.
|
|
124
|
+
|
|
125
|
+
## 6. Keep it
|
|
126
|
+
|
|
127
|
+
Show the user the demo film: where it is, and each change with the second where it can be seen. Then ask with `AskUserQuestion`:
|
|
128
|
+
|
|
129
|
+
1. **Keep it as my style** (Recommended): check that the name and slug are still free, copy `style/` to `~/lemo-my-styles/<slug>/` (or the folder they want), add its row to `~/lemo-my-styles/README.md` (create it if it's missing: a title and a table with one row per style), and tell them where it is and how to use it ("Make a film in my <name> style about…").
|
|
130
|
+
2. **One more round**: change what they ask (§7), then ask again.
|
|
131
|
+
3. **Not now**: leave it in the project folder. Tell them its path, and that saying "keep the style in <path> as my style" later saves it then.
|
|
132
|
+
|
|
133
|
+
Only a kept style is theirs: listed when the skill starts, and found by name.
|
|
134
|
+
|
|
135
|
+
## 7. Revise or use it
|
|
136
|
+
|
|
137
|
+
- **Not right yet**: change `STYLE.md` and `CHANGES.md`, then render the style frame and the demo film again and replace `demo/` and `DEMO.md`. Change only what the user asks.
|
|
138
|
+
- **Using it**: find it through `~/lemo-my-styles/README.md`. Read its `STYLE.md` in place of a library `STYLE.md` and follow the normal workflow in `AGENTS.md`, treatment first, at the style's default size unless the user asks for another. For techniques, read the style's own `DEMO.md` and `demo/` first, then the base's (`$LIB/styles/<based_on>/DEMO.md`). The demo film is one example: never reuse its story, shots or timeline. The films are the user's: no LemoLab credit, no watermark.
|
|
139
|
+
- **After a library update**: if the base `STYLE.md` changed since `library_version`, mention it once and offer to bring the useful fixes into their copy. Don't change their style without asking.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Cinematic reference library
|
|
2
|
+
|
|
3
|
+
66 visual styles, directing guides and visual-code helpers for machinal.
|
|
4
|
+
|
|
5
|
+
Discover styles through `get_editing_reference(topic: film-styles)` and selected guides through `film-techniques`. Read `machinal://reference/film-styles` before adapting any source.
|
|
6
|
+
|
|
7
|
+
These documents are creative references, not an executable production pipeline. Use the deployed Svelte/Three.js runtime and normal media, caption and spending safeguards. No demo films or third-party assets are included.
|
|
8
|
+
|
|
9
|
+
## Licence
|
|
10
|
+
|
|
11
|
+
Code and documentation: MIT, Copyright (c) 2026 LemoLab. The complete notice and licence are preserved in `LICENSE`.
|
|
12
|
+
|
|
13
|
+
The documents use neutral naming and are adapted for this integration. `manifest.json` records the exact bytes and checksums of the bundled adaptations.
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# Technique: how the films are built
|
|
2
|
+
|
|
3
|
+
Every film here is made from code: no video generation, no stock footage. This page explains the pipeline, to reproduce with our tools in `core/` or in your own stack. Pair it with [`DIRECTOR.md`](DIRECTOR.md) and one `styles/<slug>/STYLE.md`. Every command and flag is in [`core/README.md`](core/README.md).
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
timeline (single source of truth)
|
|
7
|
+
├─► picture: web page with render(t) ──► headless Chrome, frame by frame ──► video.mp4
|
|
8
|
+
├─► voice: TTS per line ──► speech-to-text check ──► word timings
|
|
9
|
+
├─► music: score from the same timeline (samples + synthesis) ──► stems
|
|
10
|
+
├─► sound: procedural foley at event times
|
|
11
|
+
└─► subtitles: .srt + burned-in captions
|
|
12
|
+
mix (duck, compress, balance) ──► mux with ffmpeg, two-pass loudnorm −14 LUFS ──► film.mp4
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 1. Requirements and install
|
|
16
|
+
|
|
17
|
+
System tools, which the user installs: **Node 20+**, **ffmpeg 7+** (6.x under-reports audio length through `loudnorm`, and `mux.sh` then rejects the file as cut off), and **Python 3.11+** or [uv](https://docs.astral.sh/uv/). Developed on macOS (Apple silicon); Linux should work; on Windows use WSL. 3D and shader-heavy styles want a GPU.
|
|
18
|
+
|
|
19
|
+
Everything else installs in tiers, from the library root (`$LIB` in skill mode). Install a tier only when the film needs it:
|
|
20
|
+
|
|
21
|
+
| Command | Adds | Size |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| External setup script (not bundled; do not execute) | core: npm packages, headless browser, Python `.venv` (numpy, scipy, soundfile, soxr, pillow): render, synthesize sound, mux | ~350 MB |
|
|
24
|
+
| `… setup.sh deps voice` | Kokoro + model (English, offline), edge-tts (Chinese, online), faster-whisper (voice check) | ~0.55 GB + a Whisper model on first check (~145 MB for English, ~480 MB for Chinese) |
|
|
25
|
+
| `… setup.sh deps music` | numba, for plucked strings (`pluck.py`); the sampler itself needs only the core | ~140 MB |
|
|
26
|
+
| `sh tools/fetch.sh instruments <lib>` | a sample library: `freepats`, `karoryfer`, `salamander`, `vcsl`, `vsco2ce` or `all` | 70–400 MB each |
|
|
27
|
+
| `sh tools/fetch.sh hdri` | HDRIs for 3D styles | 12 MB |
|
|
28
|
+
|
|
29
|
+
Some styles need packages of their own (a LiDAR reader, a slide-scan decoder, a CAD importer); the style's `STYLE.md` lists them. They are packages, not system tools: install them yourself into a private venv or `node_modules` in the project folder, never into `$LIB/.venv`.
|
|
30
|
+
|
|
31
|
+
A synthesized score needs no big download; `sampler.py` names the library to fetch when an instrument is missing. A pack needs about twice its size free while it unpacks. Downloads come from npm, PyPI, GitHub Releases and Hugging Face (`HF_ENDPOINT` sets a mirror).
|
|
32
|
+
|
|
33
|
+
## 2. The picture is a function of time
|
|
34
|
+
|
|
35
|
+
Each film is a folder with an `index.html` (`<demo>` in the commands) that exposes:
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
window.DUR = 54.2; // seconds
|
|
39
|
+
window.render = (t) => { ... }; // draw the frame at time t, deterministic
|
|
40
|
+
window.READY = true; // set once fonts and images are loaded
|
|
41
|
+
window.EV = [{t, type, ...}]; // optional: sound / cue events for the mixer
|
|
42
|
+
window.TEXTS = (t) => [{id, text, x0, y0, x1, y1}]; // optional: every text visible at t, for readcheck
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
**Paths:** pages reach library files with absolute URLs (`/core/lib.js`, `/node_modules/three/build/three.module.js`); scripts and `build.sh` use `$LIB`. Never `../..`.
|
|
46
|
+
|
|
47
|
+
A `build.sh` that works in both modes (in skill mode, put `LIB=<path setup.sh printed>` at the top):
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
#!/bin/sh
|
|
51
|
+
set -e
|
|
52
|
+
HERE=$(cd "$(dirname "$0")" && pwd)
|
|
53
|
+
LIB=${LIB:-$(cd "$HERE/../.." && pwd)} # clone mode: <repo>/films/<name>/
|
|
54
|
+
export LIB
|
|
55
|
+
[ -f "$LIB/core/render/video.mjs" ] || { echo "set LIB to the library folder"; exit 1; }
|
|
56
|
+
cd "$LIB"
|
|
57
|
+
node core/render/events.mjs "$HERE"
|
|
58
|
+
node core/render/video.mjs "$HERE" --fps 24 --out "$HERE/out/video.mp4"
|
|
59
|
+
"$LIB/.venv/bin/python" "$HERE/mix.py" # score, foley, voice → out/mix.wav
|
|
60
|
+
sh core/render/mux.sh "$HERE/out/video.mp4" "$HERE/out/mix.wav" "$HERE/<name>.mp4" 24
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Rules that keep it reliable:
|
|
64
|
+
|
|
65
|
+
- **Deterministic.** No `Date.now()`, no `Math.random()` without a seed (`core/lib.js` has `mulberry` and `hash`), no state carried from the previous frame. Any frame can be rendered alone, in any order, by any worker.
|
|
66
|
+
- **Canvas 2D** for most 2D styles; **three.js** for 3D (§9); **WebGL2** shaders for post passes (film damage, CRT, ink redraw).
|
|
67
|
+
- **Animate on twos where the style wants it** (12 fps stepping for stop-motion, pixel or cel looks), but keep the camera and light smooth every frame. A stepped camera reads as lag.
|
|
68
|
+
- **One world → screen function.** Any effect that follows a subject (iris, zoom, spotlight) goes through it. Never hand-type screen coordinates.
|
|
69
|
+
- **Draw for the frame you render.** The default is 1920×1080; for another size pass `--size WxH` (e.g. `1080x1920`) to every render tool and lay the page out from `innerWidth` × `innerHeight`.
|
|
70
|
+
|
|
71
|
+
Capture (`core/render/`):
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
node core/render/still.mjs <demo> 1.5 12 --range 0:50:2 # review stills; exits on page errors
|
|
75
|
+
node core/render/video.mjs <demo> --fps 24 --workers 3 # all frames → <demo>/out/video.mp4
|
|
76
|
+
node core/render/events.mjs <demo> # export DUR + EV → events.json
|
|
77
|
+
node core/render/readcheck.mjs <demo> # every on-screen text stays long enough to read
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
To render a second version with other content, pass it to the page and give it its own output: `--q 'content=content_alt.json' --out …/alt.mp4` (the same for `events.mjs`).
|
|
81
|
+
|
|
82
|
+
Capture is fast because of **JPEG screenshots**, **one browser per worker** and **grain added in ffmpeg**: grain drawn in the page makes every frame incompressible and slow.
|
|
83
|
+
|
|
84
|
+
## 3. One timeline drives everything
|
|
85
|
+
|
|
86
|
+
Keep sections, tempo, beats and hit points in one file (`timeline.js`). Export it to JSON and let the score, the mixer, the subtitles and the checks read the same numbers:
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
export const SECS = [{ id: 'chase', t: 12.0, bpm: 144, beats: 12 }, ...];
|
|
90
|
+
export const HIT = { pratfall: ['chase', 6], ... }; // section + beat
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
A small script (`cuecheck.py`, in `styles/<slug>/demo/tools/` of several demos) compares every visual hit with the music cue it should land on. Aim for 0 ms.
|
|
94
|
+
|
|
95
|
+
## 4. Voice
|
|
96
|
+
|
|
97
|
+
- **TTS is only the default.** If the user brings a recording or names a voice, use that. Otherwise:
|
|
98
|
+
- **English**: [Kokoro](https://github.com/thewh1teagle/kokoro-onnx), local, many voices (an unknown `voice` name makes `tts.py` print the full list; `af_` / `am_` are American, `bf_` / `bm_` British; cast the narrator for this film, not the demo's). `core/tts/tts.py lines.json out/` writes one WAV per line and a durations file. Its Chinese voices (`"lang": "cmn"`) work offline but sound plain.
|
|
99
|
+
- **Chinese**: `core/tts/tts_zh.py lines.json out/` uses [edge-tts](https://github.com/rany2/edge-tts) with Microsoft's neural voices (`zh-CN-XiaoxiaoNeural`, `zh-CN-YunxiNeural`…), with the same outputs as `tts.py`, a rate per line and the silence trimmed. **It needs a network connection.**
|
|
100
|
+
- Spell numbers out in the TTS text and write them as digits in the subtitles.
|
|
101
|
+
- **Check every line**: `core/tts/asr_check.py` transcribes each WAV with faster-whisper and compares it with the script (`--lang zh`: numbers by value, so 十九 matches 19, and the rest character by character); re-generate until it exits 0. A misheard character in a short Chinese line is normal: listen, and if it is right, put what the model heard in the line's `asr` field. It also writes word timestamps for placing lines and subtitles.
|
|
102
|
+
- **Before mixing**: TTS has a high peak-to-average ratio. Compress the voice first, then balance by RMS: voice about 10 dB above the music.
|
|
103
|
+
|
|
104
|
+
## 5. Music
|
|
105
|
+
|
|
106
|
+
Write an original score from the cue map, in the instruments of the style's sound palette; no generic piano and strings.
|
|
107
|
+
|
|
108
|
+
- **Samples**: `core/audio/sampler.py` plays real instruments from free libraries (VSCO 2 CE, VCSL, FreePats, Karoryfer, Salamander Grand Piano; list and licences in `core/audio/INSTRUMENTS.md`). Write the score as events `(time, instrument, pitch, duration, velocity, pan)`. Long notes are extended seamlessly, and round-robins avoid the machine-gun effect.
|
|
109
|
+
- **Plucked and folk strings** (guqin, pipa, shamisen, banjo…): `core/audio/pluck.py`, physical modelling (Karplus–Strong) with bends and vibrato.
|
|
110
|
+
- **Synthesis** with numpy for chip tunes, drones and effects; no download needed.
|
|
111
|
+
- **Balance the low end.** Synthetic scores get bass-heavy quickly. Measure energy per band after mixing; keep 20–120 Hz around −3 dB relative to the rest, skip pad notes below MIDI 48, and give the bass some 2nd and 3rd harmonics so it speaks on small speakers.
|
|
112
|
+
|
|
113
|
+
## 6. Sound effects and mix
|
|
114
|
+
|
|
115
|
+
- `core/audio/sfx.py` synthesises foley procedurally (click, whoosh, thump, ding, paper, noise beds…) with filters, envelopes and `add(buffer, sound, at, gain, pan)`. Drive it from `window.EV`, so every sound sits exactly on its frame.
|
|
116
|
+
- **Master**: `sh core/render/mux.sh video.mp4 mix.wav out.mp4 24 [grain]` muxes, runs a two-pass loudnorm to −14 LUFS with a true-peak limit, adds grain in ffmpeg and prints the measured loudness; it exits non-zero on any failure. On light backgrounds use less grain; for pixel and vector styles, none.
|
|
117
|
+
- Films with grain baked into the picture compress badly; re-encode with `-tune grain` and a higher CRF.
|
|
118
|
+
|
|
119
|
+
## 7. Subtitles
|
|
120
|
+
|
|
121
|
+
- Export `.srt` with `core/render/srt.py cues.json out.srt` (cues = `[{t0, t1, text}]`), and burn styled captions into the page itself: the caption design is part of the style.
|
|
122
|
+
- Timing rules are in DIRECTOR.md §7.
|
|
123
|
+
|
|
124
|
+
## 8. Review loop
|
|
125
|
+
|
|
126
|
+
1. Contact sheets: a frame every 1–2 s with `still.mjs --range`, tiled with `core/render/sheet.py`. At least two full passes.
|
|
127
|
+
2. Frame strips at 0.2 s for every key action: hand-overs, falls, hits.
|
|
128
|
+
3. On the final file: `ffmpeg -af ebur128` (loudness), `blackdetect` (blank frames), whisper again on the final mix if it has voice.
|
|
129
|
+
4. Watch it once, at full speed, with sound.
|
|
130
|
+
|
|
131
|
+
## 9. 3D notes
|
|
132
|
+
|
|
133
|
+
- three.js r170 rendered headless through WebGL2 on the GPU; physical depth of field and GTAO from `core/three/post.js`, rendered at 2× and downsampled.
|
|
134
|
+
- Lighting: soft area lights plus a Poly Haven HDRI at low intensity reads more "real" than bright ambient light.
|
|
135
|
+
- `core/three/post.js` is written for a perspective camera. For an orthographic camera swap `perspectiveDepthToViewZ` for `orthographicDepthToViewZ` in its depth pass, or the depth of field silently breaks.
|
|
136
|
+
|
|
137
|
+
## 10. Characters drawn in code
|
|
138
|
+
|
|
139
|
+
- A 2.5D rig (torso, head, limbs solved per frame) is enough for pantomime.
|
|
140
|
+
- Order the shoulder rotation as abduction, then flexion; the reverse order crosses raised arms into an X.
|
|
141
|
+
- Let the shoulder girdle rise and move forward as the arm lifts, and don't outline the part of the arm that overlaps the torso: that line is what makes a joint look like a puppet seam.
|
|
142
|
+
|
|
143
|
+
## 11. Assets, credits and fonts
|
|
144
|
+
|
|
145
|
+
Only CC0, CC BY or OFL material, each listed in the film's `CREDITS` with its source and licence; `core/audio/sampler.py credits(names)` writes the lines for the instruments you used. Public-domain works count as CC0; "no known restrictions" does not. Data or images under other open licences (ODbL, CC BY-SA, open-hardware licences) only after you have named the licence and its terms (attribution, share-alike) to the user and they agree. The user's own material is fine as it is.
|
|
146
|
+
|
|
147
|
+
A film that states facts (the Evidence Films styles) keeps a `FACTS.md` in the project folder: each claim with its source URL and the quoted wording, or the measurement that produced it.
|
|
148
|
+
|
|
149
|
+
Fonts: Google Fonts (OFL), self-hosted in the project. The typefaces a `STYLE.md` names are not in the library; download them (`https://github.com/google/fonts/tree/main/ofl/<family>`) into the project's `fonts/`. `core/fonts/` holds a few Latin display fonts and a Chinese display font with only about 200 glyphs, not enough for running Chinese text. For Chinese, subset a CJK font to the characters you use: the Google Fonts CSS API with `&text=` returns just those glyphs (`https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@700&text=<URL-encoded characters>`). Download the font file it points to into the project's `fonts/` and load it with `@font-face`; don't link Google Fonts at render time.
|
|
150
|
+
|
|
151
|
+
## 12. Where to look in our demos
|
|
152
|
+
|
|
153
|
+
| If you need… | Look at |
|
|
154
|
+
|---|---|
|
|
155
|
+
| 2D character animation and lip sync | `styles/scifi-toon/`, `styles/cel-anime-80s/` |
|
|
156
|
+
| a timeline-driven score with cue checking | `styles/microgame/`, `styles/silent-film/` |
|
|
157
|
+
| an image-to-ink redraw and film-damage post pass | `styles/silent-film/demo/engine/` |
|
|
158
|
+
| a brush or stroke engine | `styles/watercolor/`, `styles/ink-wash/`, `styles/impasto/` |
|
|
159
|
+
| 3D with depth of field and real materials | `styles/brick-toy/`, `styles/paper-popup/` |
|
|
160
|
+
| a CRT or VHS look | `core/post/crt.js`, `styles/ascii-crt/`, `styles/backrooms/` |
|
|
161
|
+
|
|
162
|
+
Each style's `DEMO.md` says how its demo was built. Open it and the code only after your treatment exists, to learn a technique, never to rebuild our film (an Edit & Documentary style's material tools in `demo/tools/` come first: AGENTS.md, "Treatment first"). In skill mode, get the source with `sh <skill folder>/scripts/setup.sh demo <slug>`. Copied demo code often reaches the library with `../..`: replace that with `$LIB` or absolute URLs.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// General small helpers: deterministic random, interpolation, easing
|
|
2
|
+
export const clamp = (x, a = 0, b = 1) => Math.max(a, Math.min(b, x));
|
|
3
|
+
export const lerp = (a, b, t) => a + (b - a) * t;
|
|
4
|
+
export const seg = (t, a, b) => clamp((t - a) / (b - a));
|
|
5
|
+
export const ss = t => { t = clamp(t); return t * t * (3 - 2 * t); };
|
|
6
|
+
export const eio = t => { t = clamp(t); return t < .5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2; };
|
|
7
|
+
export const eo = t => 1 - Math.pow(1 - clamp(t), 3);
|
|
8
|
+
export const ei = t => Math.pow(clamp(t), 3);
|
|
9
|
+
export const back = (t, s = 1.8) => { t = clamp(t) - 1; return 1 + t * t * ((s + 1) * t + s); };
|
|
10
|
+
// spring settle: 0→1, with one or two rebounds
|
|
11
|
+
export const spring = (t, k = 7, z = .35) => { t = Math.max(0, t); return 1 - Math.exp(-z * k * t) * Math.cos(k * Math.sqrt(1 - z * z) * t * 1.6); };
|
|
12
|
+
export function mulberry(seed) { return function () { seed |= 0; seed = seed + 0x6D2B79F5 | 0; let t = Math.imul(seed ^ seed >>> 15, 1 | seed); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; }; }
|
|
13
|
+
export const hash = n => { n = Math.sin(n * 127.1 + 311.7) * 43758.5453; return n - Math.floor(n); };
|
|
14
|
+
export const vnoise = x => { const i = Math.floor(x), f = x - i, u = f * f * (3 - 2 * f); return lerp(hash(i), hash(i + 1), u); };
|
|
15
|
+
export const TAU = Math.PI * 2;
|
|
16
|
+
|
|
17
|
+
// monotone cubic interpolation (Fritsch–Carlson)
|
|
18
|
+
export function monotone(keys) {
|
|
19
|
+
const n = keys.length, xs = keys.map(k => k[0]), ys = keys.map(k => k[1]);
|
|
20
|
+
if (n === 1) return () => ys[0];
|
|
21
|
+
const d = [], m = new Array(n).fill(0);
|
|
22
|
+
for (let i = 0; i < n - 1; i++) d.push((ys[i + 1] - ys[i]) / (xs[i + 1] - xs[i]));
|
|
23
|
+
m[0] = d[0]; m[n - 1] = d[n - 2];
|
|
24
|
+
for (let i = 1; i < n - 1; i++) m[i] = d[i - 1] * d[i] <= 0 ? 0 : (d[i - 1] + d[i]) / 2;
|
|
25
|
+
for (let i = 0; i < n - 1; i++) {
|
|
26
|
+
if (d[i] === 0) { m[i] = m[i + 1] = 0; continue; }
|
|
27
|
+
const a = m[i] / d[i], b = m[i + 1] / d[i], s = a * a + b * b;
|
|
28
|
+
if (s > 9) { const k = 3 / Math.sqrt(s); m[i] = k * a * d[i]; m[i + 1] = k * b * d[i]; }
|
|
29
|
+
}
|
|
30
|
+
return t => {
|
|
31
|
+
if (t <= xs[0]) return ys[0]; if (t >= xs[n - 1]) return ys[n - 1];
|
|
32
|
+
let i = 0; while (t > xs[i + 1]) i++;
|
|
33
|
+
const h = xs[i + 1] - xs[i], u = (t - xs[i]) / h, u2 = u * u, u3 = u2 * u;
|
|
34
|
+
return (2 * u3 - 3 * u2 + 1) * ys[i] + (u3 - 2 * u2 + u) * h * m[i] + (-2 * u3 + 3 * u2) * ys[i + 1] + (u3 - u2) * h * m[i + 1];
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
// multi-dimensional keyframes: [[t,[a,b,c]],...] → t => [..]
|
|
38
|
+
export function track(keys) {
|
|
39
|
+
const dim = keys[0][1].length, fs = [];
|
|
40
|
+
for (let j = 0; j < dim; j++) fs.push(monotone(keys.map(k => [k[0], k[1][j]])));
|
|
41
|
+
return t => fs.map(f => f(t));
|
|
42
|
+
}
|
|
43
|
+
// segment: a 0→1→0 envelope over [a,b]
|
|
44
|
+
export const env = (t, a, b, fi = .3, fo = .3) => Math.min(seg(t, a, a + fi), 1 - seg(t, b - fo, b));
|