@litfamily/litgravity 0.1.1 → 0.1.3

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 (251) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +19 -3
  3. package/README_ko-KR.md +19 -3
  4. package/TRADEMARK.md +12 -0
  5. package/package.json +3 -2
  6. package/plugin/hooks/lib/lanes.mjs +65 -0
  7. package/plugin/hooks/lib/liveness.mjs +81 -0
  8. package/plugin/hooks/lib/motion.mjs +34 -5
  9. package/plugin/hooks/lib/reentry.mjs +7 -0
  10. package/plugin/hooks/lib/rewind/brief.mjs +364 -0
  11. package/plugin/hooks/lib/rewind/collect.mjs +359 -0
  12. package/plugin/hooks/lib/rewind/gauge.mjs +55 -0
  13. package/plugin/hooks/lib/rewind/next-step.mjs +77 -0
  14. package/plugin/hooks/lib/rewind/redact.mjs +60 -0
  15. package/plugin/hooks/lib/rewind/transcripts.mjs +214 -0
  16. package/plugin/hooks/lib/routes.mjs +79 -5
  17. package/plugin/hooks/lib/workflow-stack.mjs +213 -0
  18. package/plugin/hooks/post-tool-use.mjs +39 -1
  19. package/plugin/hooks/pre-invocation.mjs +93 -2
  20. package/plugin/hooks/session-start.mjs +26 -3
  21. package/plugin/hooks/stop.mjs +55 -6
  22. package/plugin/hud/looks.mjs +29 -0
  23. package/plugin/hud/render.mjs +277 -12
  24. package/plugin/plugin.json +1 -1
  25. package/plugin/skills/frontend-ui-ux/SKILL.md +12 -1
  26. package/plugin/skills/frontend-ui-ux/kit/components.css +417 -0
  27. package/plugin/skills/frontend-ui-ux/kit/fonts.json +22 -0
  28. package/plugin/skills/frontend-ui-ux/kit/layouts/landing.html +164 -0
  29. package/plugin/skills/frontend-ui-ux/kit/layouts/settings.html +114 -0
  30. package/plugin/skills/frontend-ui-ux/kit/layouts/workspace.html +115 -0
  31. package/plugin/skills/frontend-ui-ux/kit/styles/computational-brutalism.json +227 -0
  32. package/plugin/skills/frontend-ui-ux/kit/styles/field-notes.json +205 -0
  33. package/plugin/skills/frontend-ui-ux/kit/styles/graphite.json +200 -0
  34. package/plugin/skills/frontend-ui-ux/kit/styles/meadow.json +199 -0
  35. package/plugin/skills/frontend-ui-ux/kit/styles/neo-brutalism.json +222 -0
  36. package/plugin/skills/frontend-ui-ux/kit/ui.js +226 -0
  37. package/plugin/skills/frontend-ui-ux/references/house-styles.md +234 -0
  38. package/plugin/skills/frontend-ui-ux/scripts/design-lock.mjs +400 -0
  39. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-lock.mjs +196 -0
  40. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-page.mjs +30 -9
  41. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-rules.mjs +20 -8
  42. package/plugin/skills/frontend-ui-ux/scripts/interface-probe.mjs +42 -9
  43. package/plugin/skills/frontend-ui-ux/scripts/pixel-art.mjs +60 -0
  44. package/plugin/skills/lit-adhd/SKILL.md +160 -0
  45. package/plugin/skills/lit-adhd/references/card-examples.md +107 -0
  46. package/plugin/skills/lit-adhd/references/status-taxonomy.md +34 -0
  47. package/plugin/skills/lit-adhd/scripts/rewind.mjs +5 -0
  48. package/plugin/skills/lit-diagram-drawer/SKILL.md +5 -3
  49. package/plugin/skills/lit-diagram-drawer/references/drawing-rules.md +1 -1
  50. package/plugin/skills/lit-diagram-drawer/references/style-guide.md +21 -12
  51. package/plugin/skills/lit-diagram-drawer/references/type-architecture.md +3 -3
  52. package/plugin/skills/lit-diagram-drawer/references/type-dependency.md +1 -1
  53. package/plugin/skills/lit-diagram-drawer/references/type-tree.md +3 -3
  54. package/plugin/skills/lit-diagram-drawer/references/type-wardley.md +1 -1
  55. package/plugin/skills/lit-diagram-drawer/scripts/diagram-craft-rules.mjs +1 -2
  56. package/plugin/skills/lit-diagram-drawer/scripts/visual-quality.mjs +1 -2
  57. package/plugin/skills/lit-docx/SKILL.md +3 -3
  58. package/plugin/skills/lit-handoff/SKILL.md +1 -0
  59. package/plugin/skills/lit-hijack/SKILL.md +263 -0
  60. package/plugin/skills/lit-hijack/references/capture-and-provenance.md +100 -0
  61. package/plugin/skills/lit-hijack/references/clean-room-build.md +75 -0
  62. package/plugin/skills/lit-hijack/references/distil-and-licence.md +67 -0
  63. package/plugin/skills/lit-hijack/references/gap-and-port-design.md +100 -0
  64. package/plugin/skills/lit-hijack/references/parity-and-report.md +85 -0
  65. package/plugin/skills/lit-hijack/scripts/hijack.mjs +953 -0
  66. package/plugin/skills/lit-plan/SKILL.md +3 -2
  67. package/plugin/skills/lit-plan/references/plan-contract.md +12 -1
  68. package/plugin/skills/lit-plan/scripts/check-plan.mjs +39 -3
  69. package/plugin/skills/lit-plan/templates/plan.md +3 -0
  70. package/plugin/skills/lit-pptx/SKILL.md +8 -8
  71. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Bold.ttf +0 -0
  72. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Regular.ttf +0 -0
  73. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/OFL.txt +93 -0
  74. package/plugin/skills/lit-pptx/fonts/provenance.json +32 -1
  75. package/plugin/skills/lit-pptx/references/agents/analyst.md +34 -56
  76. package/plugin/skills/lit-pptx/references/agents/antithesis.md +49 -67
  77. package/plugin/skills/lit-pptx/references/agents/architect.md +38 -51
  78. package/plugin/skills/lit-pptx/references/agents/critic.md +25 -41
  79. package/plugin/skills/lit-pptx/references/agents/synthesizer.md +37 -46
  80. package/plugin/skills/lit-pptx/references/agents/thesis.md +29 -49
  81. package/plugin/skills/lit-pptx/references/anti-slop-checklist.md +119 -145
  82. package/plugin/skills/lit-pptx/references/authoring-guide.md +187 -278
  83. package/plugin/skills/lit-pptx/references/consensus-protocol.md +99 -97
  84. package/plugin/skills/lit-pptx/references/data-display-cookbook.md +36 -137
  85. package/plugin/skills/lit-pptx/references/density-and-fill.md +147 -216
  86. package/plugin/skills/lit-pptx/references/design-system-azure.md +56 -85
  87. package/plugin/skills/lit-pptx/references/direction-step.md +134 -176
  88. package/plugin/skills/lit-pptx/references/examples/01-pitch-signal-ko.md +114 -115
  89. package/plugin/skills/lit-pptx/references/examples/02-pitch-studio-ko.md +66 -66
  90. package/plugin/skills/lit-pptx/references/examples/03-business-review-ledger-ko.md +63 -63
  91. package/plugin/skills/lit-pptx/references/examples/04-business-review-night-en.md +96 -96
  92. package/plugin/skills/lit-pptx/references/examples/05-research-talk-paper-en.md +81 -81
  93. package/plugin/skills/lit-pptx/references/examples/06-lecture-chalk-ko.md +103 -103
  94. package/plugin/skills/lit-pptx/references/examples/07-data-review-night-en.md +100 -98
  95. package/plugin/skills/lit-pptx/references/examples/08-image-led-atlas-ko.md +76 -76
  96. package/plugin/skills/lit-pptx/references/examples/09-briefing-gazette-ko.md +96 -96
  97. package/plugin/skills/lit-pptx/references/examples/10-status-update-ledger-ko.md +80 -80
  98. package/plugin/skills/lit-pptx/references/examples/11-portfolio-studio-en.md +72 -72
  99. package/plugin/skills/lit-pptx/references/examples/12-research-tutorial-chalk-en.md +95 -95
  100. package/plugin/skills/lit-pptx/references/examples/13-engineering-review-computational-brutalism-ko.md +173 -0
  101. package/plugin/skills/lit-pptx/references/examples/14-launch-pitch-neo-brutalism-ko.md +154 -0
  102. package/plugin/skills/lit-pptx/references/examples/15-design-lecture-bauhaus-ko.md +139 -0
  103. package/plugin/skills/lit-pptx/references/examples/16-community-programme-riso-ko.md +158 -0
  104. package/plugin/skills/lit-pptx/references/examples/17-public-data-briefing-newsroom-ko.md +179 -0
  105. package/plugin/skills/lit-pptx/references/interview-protocol.md +83 -102
  106. package/plugin/skills/lit-pptx/references/layout-families.md +161 -265
  107. package/plugin/skills/lit-pptx/references/stages/autopilot.md +30 -70
  108. package/plugin/skills/lit-pptx/references/stages/interview.md +36 -68
  109. package/plugin/skills/lit-pptx/references/stages/plan.md +26 -67
  110. package/plugin/skills/lit-pptx/references/title-treatments.md +93 -145
  111. package/plugin/skills/lit-pptx/references/tonalities/atlas.md +95 -108
  112. package/plugin/skills/lit-pptx/references/tonalities/bauhaus.md +140 -0
  113. package/plugin/skills/lit-pptx/references/tonalities/chalk.md +107 -122
  114. package/plugin/skills/lit-pptx/references/tonalities/computational-brutalism.md +150 -0
  115. package/plugin/skills/lit-pptx/references/tonalities/gazette.md +87 -111
  116. package/plugin/skills/lit-pptx/references/tonalities/ledger.md +96 -125
  117. package/plugin/skills/lit-pptx/references/tonalities/neo-brutalism.md +161 -0
  118. package/plugin/skills/lit-pptx/references/tonalities/newsroom.md +144 -0
  119. package/plugin/skills/lit-pptx/references/tonalities/night.md +104 -131
  120. package/plugin/skills/lit-pptx/references/tonalities/paper.md +114 -130
  121. package/plugin/skills/lit-pptx/references/tonalities/riso.md +137 -0
  122. package/plugin/skills/lit-pptx/references/tonalities/signal.md +96 -103
  123. package/plugin/skills/lit-pptx/references/tonalities/studio.md +81 -112
  124. package/plugin/skills/lit-pptx/scripts/compile-deck.js +4 -6
  125. package/plugin/skills/lit-pptx/scripts/craft_extras.py +135 -91
  126. package/plugin/skills/lit-pptx/scripts/deck_craft.py +1 -1
  127. package/plugin/skills/lit-pptx/scripts/embed_fonts.py +13 -1
  128. package/plugin/skills/lit-pptx/scripts/layout_inventory.py +1 -1
  129. package/plugin/skills/lit-pptx/scripts/learn_template.py +1 -1
  130. package/plugin/skills/lit-pptx/scripts/lib/grid-resolver.js +101 -110
  131. package/plugin/skills/lit-pptx/scripts/lib/layout-resolver.js +9 -15
  132. package/plugin/skills/lit-pptx/scripts/lib/render-pack.js +370 -563
  133. package/plugin/skills/lit-pptx/scripts/lib/slide-grid.js +104 -0
  134. package/plugin/skills/lit-pptx/scripts/lib/template-registry.js +57 -6
  135. package/plugin/skills/lit-pptx/scripts/qa_deck.py +6 -6
  136. package/plugin/skills/lit-pptx/scripts/render_pages.py +31 -0
  137. package/plugin/skills/lit-pptx/scripts/validate_pptx.py +1 -1
  138. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v1.md +167 -191
  139. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v2.md +117 -166
  140. package/plugin/skills/lit-pptx/specs/template-enrollment-contract.md +307 -330
  141. package/plugin/skills/lit-pptx/templates/tonalities/atlas/pack.yaml +1 -1
  142. package/plugin/skills/lit-pptx/templates/tonalities/bauhaus/pack.yaml +98 -0
  143. package/plugin/skills/lit-pptx/templates/tonalities/chalk/pack.yaml +1 -1
  144. package/plugin/skills/lit-pptx/templates/tonalities/computational-brutalism/pack.yaml +99 -0
  145. package/plugin/skills/lit-pptx/templates/tonalities/gazette/pack.yaml +1 -1
  146. package/plugin/skills/lit-pptx/templates/tonalities/ledger/pack.yaml +1 -1
  147. package/plugin/skills/lit-pptx/templates/tonalities/neo-brutalism/pack.yaml +107 -0
  148. package/plugin/skills/lit-pptx/templates/tonalities/newsroom/pack.yaml +99 -0
  149. package/plugin/skills/lit-pptx/templates/tonalities/night/pack.yaml +1 -1
  150. package/plugin/skills/lit-pptx/templates/tonalities/paper/pack.yaml +1 -1
  151. package/plugin/skills/lit-pptx/templates/tonalities/riso/pack.yaml +99 -0
  152. package/plugin/skills/lit-pptx/templates/tonalities/signal/pack.yaml +2 -2
  153. package/plugin/skills/lit-pptx/templates/tonalities/studio/pack.yaml +1 -1
  154. package/plugin/skills/lit-schematic/SKILL.md +114 -0
  155. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/build.mjs +38 -0
  156. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/scene.mjs +133 -0
  157. package/plugin/skills/lit-schematic/examples/journal-adsorption-rig/build.mjs +87 -0
  158. package/plugin/skills/lit-schematic/examples/pid-dosing-skid/build.mjs +85 -0
  159. package/plugin/skills/lit-schematic/references/cutaway-outputs.md +70 -0
  160. package/plugin/skills/lit-schematic/references/isometric-craft.md +101 -0
  161. package/plugin/skills/lit-schematic/references/journal-figures.md +72 -0
  162. package/plugin/skills/lit-schematic/references/kit-api.md +134 -0
  163. package/plugin/skills/lit-schematic/references/pfd-and-layout.md +53 -0
  164. package/plugin/skills/lit-schematic/references/pid-drafting.md +103 -0
  165. package/plugin/skills/lit-schematic/references/pid-symbols.md +163 -0
  166. package/plugin/skills/lit-schematic/references/verification.md +100 -0
  167. package/plugin/skills/lit-schematic/scripts/doctor.mjs +57 -0
  168. package/plugin/skills/lit-schematic/scripts/lib/figure.mjs +81 -0
  169. package/plugin/skills/lit-schematic/scripts/lib/fonts.mjs +27 -0
  170. package/plugin/skills/lit-schematic/scripts/lib/geom.mjs +113 -0
  171. package/plugin/skills/lit-schematic/scripts/lib/interactive.mjs +292 -0
  172. package/plugin/skills/lit-schematic/scripts/lib/isa.mjs +115 -0
  173. package/plugin/skills/lit-schematic/scripts/lib/iso.mjs +719 -0
  174. package/plugin/skills/lit-schematic/scripts/lib/legend-sheet.mjs +162 -0
  175. package/plugin/skills/lit-schematic/scripts/lib/pid.mjs +937 -0
  176. package/plugin/skills/lit-schematic/scripts/lib/png.mjs +132 -0
  177. package/plugin/skills/lit-schematic/scripts/lib/qa-core.mjs +658 -0
  178. package/plugin/skills/lit-schematic/scripts/lib/route.mjs +218 -0
  179. package/plugin/skills/lit-schematic/scripts/lib/sheet.mjs +890 -0
  180. package/plugin/skills/lit-schematic/scripts/lib/svg.mjs +82 -0
  181. package/plugin/skills/lit-schematic/scripts/lib/theme.mjs +115 -0
  182. package/plugin/skills/lit-schematic/scripts/motion.mjs +129 -0
  183. package/plugin/skills/lit-schematic/scripts/qa.mjs +92 -0
  184. package/plugin/skills/lit-schematic/scripts/render.mjs +233 -0
  185. package/plugin/skills/lit-schematic/scripts/scaffold.mjs +60 -0
  186. package/plugin/skills/lit-scientific-visualization/SKILL.md +17 -6
  187. package/plugin/skills/lit-typographic-motion/SKILL.md +58 -48
  188. package/plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES +13 -2
  189. package/plugin/skills/lit-typographic-motion/engine/blender/runner.py +218 -0
  190. package/plugin/skills/lit-typographic-motion/engine/core/presets.mjs +1 -1
  191. package/plugin/skills/lit-typographic-motion/engine/node/analysis.mjs +65 -1
  192. package/plugin/skills/lit-typographic-motion/engine/node/assets.mjs +298 -0
  193. package/plugin/skills/lit-typographic-motion/engine/node/blender.mjs +143 -0
  194. package/plugin/skills/lit-typographic-motion/engine/node/board.mjs +136 -0
  195. package/plugin/skills/lit-typographic-motion/engine/node/brief.mjs +7 -1
  196. package/plugin/skills/lit-typographic-motion/engine/node/chrome.mjs +9 -12
  197. package/plugin/skills/lit-typographic-motion/engine/node/cover-assets.mjs +5 -3
  198. package/plugin/skills/lit-typographic-motion/engine/node/cover-capture.mjs +7 -6
  199. package/plugin/skills/lit-typographic-motion/engine/node/cover-treatment.mjs +37 -4
  200. package/plugin/skills/lit-typographic-motion/engine/node/cover.mjs +19 -8
  201. package/plugin/skills/lit-typographic-motion/engine/node/done.mjs +45 -6
  202. package/plugin/skills/lit-typographic-motion/engine/node/frame-worker.mjs +7 -5
  203. package/plugin/skills/lit-typographic-motion/engine/node/gallery.mjs +121 -0
  204. package/plugin/skills/lit-typographic-motion/engine/node/host.mjs +34 -0
  205. package/plugin/skills/lit-typographic-motion/engine/node/house.mjs +44 -0
  206. package/plugin/skills/lit-typographic-motion/engine/node/look.mjs +34 -20
  207. package/plugin/skills/lit-typographic-motion/engine/node/pipeline.mjs +19 -9
  208. package/plugin/skills/lit-typographic-motion/engine/node/scaffold.mjs +210 -0
  209. package/plugin/skills/lit-typographic-motion/engine/node/score.mjs +639 -0
  210. package/plugin/skills/lit-typographic-motion/engine/node/sound-cli.mjs +21 -4
  211. package/plugin/skills/lit-typographic-motion/engine/node/sound.mjs +127 -29
  212. package/plugin/skills/lit-typographic-motion/engine/node/stage-capture.mjs +7 -6
  213. package/plugin/skills/lit-typographic-motion/engine/node/stage-gate.mjs +59 -5
  214. package/plugin/skills/lit-typographic-motion/engine/node/stage-qa.mjs +141 -9
  215. package/plugin/skills/lit-typographic-motion/engine/node/stage-serve.mjs +28 -5
  216. package/plugin/skills/lit-typographic-motion/engine/node/stage.mjs +82 -14
  217. package/plugin/skills/lit-typographic-motion/engine/node/styles.mjs +213 -0
  218. package/plugin/skills/lit-typographic-motion/engine/node/treatment.mjs +311 -10
  219. package/plugin/skills/lit-typographic-motion/engine/stage/cover-init.js +14 -2
  220. package/plugin/skills/lit-typographic-motion/engine/stage/init.js +11 -1
  221. package/plugin/skills/lit-typographic-motion/engine/stage/qa.js +6 -1
  222. package/plugin/skills/lit-typographic-motion/engine/stage/stage-kit.js +83 -0
  223. package/plugin/skills/lit-typographic-motion/engine/vendor/three/LICENSE +21 -0
  224. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/environments/RoomEnvironment.js +144 -0
  225. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/geometries/RoundedBoxGeometry.js +155 -0
  226. package/plugin/skills/lit-typographic-motion/engine/vendor/three/three.module.js +54571 -0
  227. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/expected.json +69 -0
  228. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/index.html +139 -0
  229. package/plugin/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +6 -4
  230. package/plugin/skills/lit-typographic-motion/recipes/painted-light/expected.json +4 -2
  231. package/plugin/skills/lit-typographic-motion/recipes/weight-tide/expected.json +7 -5
  232. package/plugin/skills/lit-typographic-motion/references/cover.md +394 -443
  233. package/plugin/skills/lit-typographic-motion/references/craft-loop.md +57 -87
  234. package/plugin/skills/lit-typographic-motion/references/depth.md +122 -0
  235. package/plugin/skills/lit-typographic-motion/references/look.md +94 -129
  236. package/plugin/skills/lit-typographic-motion/references/runtime.md +58 -91
  237. package/plugin/skills/lit-typographic-motion/references/sound.md +130 -99
  238. package/plugin/skills/lit-typographic-motion/references/stage.md +190 -215
  239. package/plugin/skills/lit-typographic-motion/references/studio.md +245 -0
  240. package/plugin/skills/lit-typographic-motion/references/style-bibles.md +108 -97
  241. package/plugin/skills/lit-typographic-motion/references/treatment.md +191 -143
  242. package/plugin/skills/lit-typographic-motion/scripts/motion-doctor.mjs +17 -5
  243. package/plugin/skills/lit-typographic-motion/scripts/motion.mjs +47 -7
  244. package/plugin/skills/lit-typographic-motion/styles/paper.json +41 -0
  245. package/plugin/skills/lit-typographic-motion/styles/swiss-signal.json +41 -0
  246. package/plugin/skills/lit-typographic-motion/styles/terminalcore.json +42 -0
  247. package/plugin/skills/lit-typographic-motion/styles/tidal.json +41 -0
  248. package/plugin/skills/litresearch/SKILL.md +1 -0
  249. package/plugin/skills/readme-studio/SKILL.md +2 -0
  250. package/plugin/skills/review-work/SKILL.md +1 -1
  251. package/plugin/skills/start-work/SKILL.md +2 -2
@@ -1,100 +1,67 @@
1
- # The motion runtime in LitGravity
1
+ # Runtime, pre-warm and BLOCKED states
2
2
 
3
- Rendering needs a few things the plugin cannot ship: one pinned npm package, two fonts whose licences
4
- call for a fetched original, optional Python audio analysis, and host programs such as Chrome. LitGravity
5
- keeps the first three in its own cache and never installs any of them while a film is being made. A
6
- headless `agy -p` run refuses the shell command an install needs, and a half-finished install in the middle
7
- of a render would look like a broken engine. The cache is filled once, by the pre-warm command below, and
8
- every render after that only reads it.
3
+ ## What is installed where
9
4
 
10
- ## What lives where
11
-
12
- | Piece | Location | Put there by |
5
+ | Piece | Where | Installed by |
13
6
  | --- | --- | --- |
14
- | Engine code, scenes, GLSL passes, bundled fonts, recipes | the skill folder inside the installed plugin | the LitGravity package |
15
- | opentype.js 2.0.0, pinned by `engine/package-lock.json` | `<cache>/node-<lockdigest>-<platform>-<arch>/` | the pre-warm, via `npm ci --omit=dev --ignore-scripts` |
16
- | Galmuri9 and MesloLGS NF with their licence files | `<cache>/fonts/`, fetched from pinned URLs and checked by sha256 | the pre-warm |
17
- | Pretendard Regular and Bold | the lit-pptx skill's `fonts/pretendard/` folder, reused by path and hash-checked | the LitGravity package |
18
- | librosa venv (Tier 2, optional) | `<cache>/audio-<digest>/`, built from `engine/audio/requirements.lock` with `pip install --require-hashes --only-binary=:all:` | `node "$SKILL_ROOT/scripts/motion-runtime.mjs" install --audio` |
19
- | Word-timing models (Tier 3) | not shipped; `engine/models/word-timing.json` only pins them | `install --word-timing` prints sizes and pins, then stops |
20
- | Chrome, ffmpeg, img2webp and dwebp, gifski as the cover fallback | host programs | the user |
21
-
22
- `<cache>` is `$LITGRAVITY_MOTION_RUNTIME` when set (tests and isolated probes use it), otherwise
23
- `${XDG_DATA_HOME:-~/.local/share}/litgravity/runtime/motion`. The cache key for the npm part is a digest of
24
- the lockfile, so a new LitGravity release with a new pin lands in a fresh folder.
25
-
26
- ## The font manifest
27
-
28
- `fonts/manifest.json` lists every font key with one of three sources, and the status check reads the same
29
- list:
30
-
31
- - **bundled**: shipped inside the skill (the Archivo width and weight instances, VT323, Silkscreen,
32
- JetBrains Mono for cover recipes, and the five EMS single-stroke SVG fonts). Hash and licence are
33
- checked in place.
34
- - **reuse**: the Pretendard pair from lit-pptx, verified against the hash recorded in the manifest. Should
35
- that file ever be missing, the manifest names a pinned fallback download that the pre-warm fetches into
36
- the cache.
37
- - **fetch**: Galmuri9 and MesloLGS NF, downloaded only by the pre-warm from a pinned URL, with their
38
- licence files, each checked by sha256.
39
-
40
- ## Pre-warming
41
-
42
- Run this once, from a terminal or as a `run_command` the user allows in an interactive agy session:
43
-
44
- ```bash
45
- npx @litfamily/litgravity runtime install motion
46
- npx @litfamily/litgravity runtime status motion
47
- ```
48
-
49
- Both call `scripts/motion-runtime.mjs` (`install --json` / `status --json`) and read
50
- `{name, ready, cache, missing}`. The install takes an mkdir lock in the cache (a stale lock older than 20
51
- minutes is cleared), installs the npm package, fetches the missing fonts and verifies every hash. The same
52
- script runs by hand as `node "$SKILL_ROOT/scripts/motion-runtime.mjs" status` for a readable report, and
53
- `install --audio` adds the optional venv. On an air-gapped machine `LITGRAVITY_MOTION_MIRROR` points at a
54
- mirror that serves every pinned file under its sha256 (and the npm tarball under its file name);
55
- `LITGRAVITY_MOTION_PYTHON` picks the interpreter for the audio venv.
56
-
57
- ## Checking readiness
58
-
59
- `node "$SKILL_ROOT/scripts/motion-doctor.mjs"` (add `--json` for data) runs six read-only probes and prints
60
- one line each:
61
-
62
- | Line | What it reports |
63
- | --- | --- |
64
- | `MOTION_CHROME` | the Chrome binary and version, or not found (set `CHROME_PATH`) |
65
- | `MOTION_FFMPEG` | ffmpeg and the preview encoder rung it supports; without it stills and sheets still work |
66
- | `MOTION_WEBGL2` | the renderer string from a real headless probe and the flags that got it |
67
- | `MOTION_SOFTWARE_GL` | whether that renderer is software GL (slower, samples lowered) or unknown |
68
- | `MOTION_PREWARM` | ready, or the missing pieces and the pre-warm command |
69
- | `MOTION_COVER` | img2webp and dwebp for cover loops, the gifski fallback, or BLOCKED_NO_COVER_ENCODER |
70
-
71
- The probe's Chrome profile is a fresh temporary folder removed afterwards. `npx @litfamily/litgravity doctor`
72
- shows the same picture at plugin level: rows for Chrome, ffmpeg and libwebp, and an engine row for
73
- `motion` with the command that fixes it.
74
-
75
- ## Exit codes on this path
7
+ | Engine code, GLSL passes, scenes, bundled fonts | this skill directory (the plugin) | the LitGravity package |
8
+ | opentype.js 2.0.0 (pinned in `engine/package-lock.json`) | `<cache>/node-<lockdigest>-<platform>-<arch>/` | `litgravity motion-runtime install` (`npm ci --omit=dev --ignore-scripts`) |
9
+ | Galmuri9, MesloLGS NF and their licence files | `<cache>/fonts/` (pinned URL, sha256-verified) | same command |
10
+ | Pretendard Regular / Bold | `../lit-pptx/fonts/pretendard/` (reused by path, hash-checked) | the package |
11
+ | librosa venv (Tier 2, optional) | `<cache>/audio-<digest>/` from `engine/audio/requirements.lock` with `pip install --require-hashes --only-binary=:all:` | `litgravity motion-runtime install --audio` |
12
+ | Word-timing models (Tier 3, optional) | not in this release | `--word-timing` prints the size and pins, then stops |
13
+ | Chrome, ffmpeg, img2webp and dwebp (libwebp), gifski (optional cover fallback) | host tools, never bundled | the user |
14
+
15
+ `<cache>` is `$LITGRAVITY_MOTION_RUNTIME`, otherwise `${XDG_CACHE_HOME:-~/.cache}/litgravity/motion-runtime`.
16
+
17
+ ## Pre-warm, never first use
18
+
19
+ The cache is written only by `litgravity motion-runtime install`; `litgravity install` (and the
20
+ global npm postinstall, which runs it) attempts the same pre-warm and prints one receipt line if it
21
+ fails, without failing the install. A agy plugin install runs no lifecycle step, so
22
+ there the explicit command is the pre-warm. A render session only reads the cache: it never runs
23
+ npm, pip or a download, because a sandboxed session usually has no network or no write access
24
+ outside the workspace, and a half-finished install would look like a broken engine.
25
+
26
+ `litgravity doctor` (and `npm run doctor` in a checkout) prints the seven probes: Chrome,
27
+ ffmpeg with the preview encoder rung, the WebGL2 renderer from a real headless probe, the software-GL
28
+ or unknown-renderer warning, the pre-warm state naming anything missing and the fix command,
29
+ the cover encoder (img2webp and dwebp, or the gifski fallback) that cover mode needs, and the
30
+ house styles (each one valid, the default named).
31
+ `litgravity motion-runtime status` prints the pre-warm state alone.
32
+
33
+ ## Exit codes
76
34
 
77
35
  | Exit | Name | Meaning | Fix |
78
36
  | --- | --- | --- | --- |
79
- | 0 | OK | the mode finished; for `make`, the gate passed | none |
80
- | 10 | BLOCKED_NO_CHROME | Chrome is missing or will not start headless; the message carries the launcher's first error line | install Chrome or Chromium, or set `CHROME_PATH` |
81
- | 11 | BLOCKED_NO_WEBGL2 | Chrome starts but no rung yields WebGL2, the software rung included | graphics drivers; nothing renders without WebGL2 |
82
- | 12 | BLOCKED_NO_FFMPEG_FOR_VIDEO | ffmpeg is missing; stills and the sheet were written anyway | install ffmpeg |
83
- | 13 | GATE_FAIL_QA | the gate or the pre-flight failed; see `gate-report.txt` | fix the named rule in the next round |
84
- | 14 | BLOCKED_DEPS_NOT_PREWARMED | the pinned npm package (or the Tier-3 runtime) is not in the cache | `npx @litfamily/litgravity runtime install motion`, from a terminal |
85
- | 15 | BLOCKED_FONT_FETCH | a required font is missing from the cache or its sha256 differs | the same command |
86
-
87
- Every blocked state names its real cause. The model repairs one only with the pre-warm command above, the one
88
- install step this skill owns, and never with an npm, pip or download command of its own. When `run_command`
89
- is refused (every headless run), it stops with BLOCKED, names the state, and gives the user the command to run
90
- in a terminal.
37
+ | 0 | OK | the mode finished; for `make`, the gate passed | — |
38
+ | 10 | BLOCKED_NO_CHROME | Chrome is missing or cannot launch headless; the message carries the launcher's first error line | install Chrome or set `CHROME_PATH` |
39
+ | 11 | BLOCKED_NO_WEBGL2 | Chrome runs but no flag rung gives a WebGL2 context, not even SwiftShader | GPU drivers; nothing can render without WebGL2 |
40
+ | 12 | BLOCKED_NO_FFMPEG_FOR_VIDEO | ffmpeg missing; stills and sheet were still written | install ffmpeg |
41
+ | 13 | GATE_FAIL_QA | the gate (or the pre-flight gate) failed; see `gate-report.txt` | fix the named rule; next round |
42
+ | 14 | BLOCKED_DEPS_NOT_PREWARMED | engine dependencies (or Tier-3 models) missing from the cache | `litgravity motion-runtime install` outside the session |
43
+ | 15 | BLOCKED_FONT_FETCH | a required font is missing or its sha256 differs | same command |
44
+
45
+ Each state names its real cause. A sandbox that refuses `listen` is not a blocked state: frames are
46
+ pulled over CDP from the same readback buffer, and the report names that egress.
47
+
48
+ ## Chrome flags (MO-A-51)
49
+
50
+ Tried in order, each counting only if a page gets WebGL2: macOS `--use-angle=metal
51
+ --enable-gpu-rasterization --ignore-gpu-blocklist`; Linux `--use-angle=gl --enable-gpu-rasterization
52
+ --ignore-gpu-blocklist`; Windows `--use-angle=d3d11 --enable-gpu-rasterization`; then the software rung
53
+ `--use-angle=swiftshader --enable-unsafe-swiftshader`. Every rung adds the three anti-throttling
54
+ flags. The rung that worked is recorded as `chromeFlags`. The Chrome profile lives in the run's own
55
+ `.run/chrome/` directory and is removed when the render ends. Every launch also passes
56
+ `--use-mock-keychain` and `--password-store=basic`, so Chrome never asks the OS keychain for its
57
+ safe-storage item (on macOS a fresh profile would otherwise raise a keychain dialog).
91
58
 
92
59
  ## Audio tiers
93
60
 
94
- - **Tier 1, the default.** Cuts follow reading time on a 100 BPM grid, or the brief's `bpm`.
95
- - **Tier 2.** The brief names an audio file and the venv is ready: librosa finds the beat grid, cuts land
96
- on detected beats, and the track is muxed. A missing venv, a venv whose pins changed, or an analysis that
97
- fails falls back to Tier 1 with the warning `audio analysis not prewarmed`, followed by the
98
- `install --audio` command. Only that command repairs it.
99
- - **Tier 3.** `--word-timing` only, and it exits 14 because the aligner runtime is not shipped. MMS_FA and
100
- madmom weights, aubio and essentia are excluded at every tier.
61
+ - **Tier 1 (default):** text reading time on a 100 BPM grid (or the brief's `bpm`).
62
+ - **Tier 2:** an audio file in the brief and a ready venv: librosa beat grid, cuts on detected
63
+ beats, audio muxed into the MP4. A missing venv, a venv whose pins changed, or a failed analysis
64
+ falls back to Tier 1 with the warning "audio analysis not prewarmed: run litgravity
65
+ motion-runtime install --audio" (or the analysis error). It is never repaired in the session.
66
+ - **Tier 3:** `--word-timing` only; exits 14 in this release. Never MMS_FA or madmom weights,
67
+ never aubio or essentia, at any tier.
@@ -1,121 +1,152 @@
1
1
  # Sound
2
2
 
3
- Films have sound unless the user said otherwise. The treatment's `sound` object (`{ mode, plan, palette,
4
- file }`) plans it on both paths, the renderer muxes the track the plan names, and after the encode it
5
- decodes the film's audio stream and gates it. The generated bed is synthesized by LitGravity's own code from
6
- the treatment: no sample library, model or package is downloaded for it, and the same treatment always
7
- produces the same bytes.
3
+ Every film gets a sound plan in `treatment.json` (`sound: { mode, plan, genre?, palette?, events }`), on
4
+ both render paths. The renderer muxes whatever track the plan names, then audits the decoded stream
5
+ after the encode. Nothing here downloads a sample, a model or a library, and nothing borrows a melody:
6
+ the score and the bed are synthesized in product code, deterministically, from the treatment.
8
7
 
9
- ## Choosing a mode
8
+ ## Modes
10
9
 
11
- | `sound.mode` | Track | Use it when |
10
+ | `sound.mode` | What is muxed | When |
12
11
  | --- | --- | --- |
13
- | `generated` | A bed built from the treatment: a tempo grid, a pulse, a pad chord per beat, and the accents the beats ask for | The default under a bare `lit`, on either path |
14
- | `supplied` | The user's file at `sound.file` (relative to the output folder), padded or trimmed to the film | The user handed over a track |
15
- | `authored` | A WAV you wrote into the stage folder, named by `sound.file` | The plan needs sound the bed cannot make; the file must sit inside `<dir>/stage/` |
16
- | `none` | No audio stream | The request asks for silence (무음, 소리 없이, silent, muted, no music …) or the `channel` plays muted by design |
17
-
18
- A supplied or authored track is always muxed, whatever the state of the optional analysis tier below.
19
- The reply calls a generated bed "a generated music bed" in plain words and names a supplied track by its
20
- file name. Switching to `none` to get past a failing check is a downgrade: the done-check records it and the
21
- reply has to admit it.
22
-
23
- ## The generated bed's palette
24
-
25
- A generated bed needs `sound.palette`:
26
-
27
- ```json
28
- { "timbre": "<timbre>", "key": "<pitch class>", "mode": "<major or minor>", "tempo": "<60-160>" }
29
- ```
30
-
31
- `key` is any of the twelve pitch classes, written with sharps or flats (`C`, `C#`, `Db` … `B`). `mode`
32
- picks the progression: major walks I–V–vi–IV, minor walks i–VI–III–VII, one chord per treatment beat (a long
33
- beat is split into two-bar chords), and the last chord always returns home. `tempo` is beats per minute
34
- and sets the pulse grid from t = 0. An invalid palette stops the render with exit 16 naming the exact field
35
- (`sound.palette.timbre`, `sound.palette.tempo` …).
12
+ | `score` | A layered score built for this film: drums, bass, chords, lead, arrangement FX and the on-screen events as separate stems, mixed and mastered | The default under a bare `lit`, on the type path and the stage path alike |
13
+ | `generated` | One of the style's preset beds: a pad chord progression with a pulse and the accents the beats ask for | Minimal films only (`register: minimal`) |
14
+ | `supplied` | The user's own audio file (`sound.file`), padded or trimmed to the film | The user gave a track |
15
+ | `authored` | A WAV the model wrote itself into the stage dir (`sound.file`) | The treatment calls for sound the bed cannot make |
16
+ | `none` | No audio stream | Only when the user asked for silence, or the `channel` plays muted by design |
17
+
18
+ A supplied or authored track is always muxed, whatever the state of the optional audio-analysis
19
+ tier; that tier only adds a beat grid for timing. Say in the reply that the score or bed is
20
+ generated, in plain words ("an original score generated for this film"), and name any supplied track
21
+ by its file name.
22
+ Never switch a film to `none` to get past a check: that is a downgrade and the done-check records it.
23
+
24
+ ## Score
25
+
26
+ The score is produced like a house track, from the film itself, so two films never share one.
27
+
28
+ - **Genre.** `house` (120-126 BPM, four-on-the-floor, offbeat bass), `tech-house` (124-128, rolling
29
+ sixteenth bass), `deep-house` (118-122, pads, light swing) or `garage` (130-134, broken kick, heavy
30
+ swing). The style picks one (swiss-signal house, terminalcore tech-house, tidal deep-house, paper
31
+ garage); `sound.genre` names another when the film asks for it. Launch and hero films stay in
32
+ house or tech-house.
33
+ - **Key, tempo, progression.** Seeded from the film's request, idea, turn, protagonist and beats:
34
+ one of twelve keys, major or minor, a tempo inside the genre's band and one of six progressions per
35
+ mode with sevenths and ninths. The last bar resolves home.
36
+ - **Arrangement from the beats.** The shots before `story.beat` are the intro and the build; the drop
37
+ lands on the turn, on a downbeat (the bar grid is placed so a bar line falls on the turn's `t0`);
38
+ with three or more shots after the turn the first is a break and the rest drop again; the last shot
39
+ is the outro. A riser runs into every section change (two bars into the drop), an impact lands on the
40
+ drop, a downlifter follows it, a reverse swell of the coming chord breathes into every other change,
41
+ the kick drops out for the half bar before the drop, and the snare rolls
42
+ into it.
43
+ - **Stems.** `kick`, `clap`, `hats` (closed and open), `perc`, `bass` (sub and line), `chords` (stab or
44
+ pad), `lead` (a motif from the key's pentatonic), `fx` (risers, downlifters, impacts, reverse swells)
45
+ and `events` (the on-screen events), each its own buffer with its own pattern.
46
+ - **Mix.** Per-stem gain and pan, a high-pass on every stem but kick and bass, the bass, chords and lead
47
+ ducked under the kick (sidechain, measured and reported in dB), sends to a reverb and a tempo delay
48
+ (dotted eighth left, eighth right), bus compression, then the shared master stage below.
49
+
50
+ Write `sound.plan` as the producer's brief for this film (what the drop is, where it breaks), and
51
+ the beats' `sound` fields with the cue words below. `motion.mjs sound` writes `sound/score.wav`, every
52
+ stem and both returns as `sound/stems/<name>.wav`, and `sound-cues.json` with the genre, key, tempo,
53
+ progression, sections, FX, each stem's level, the sidechain depth, the bus settings and every cue.
54
+
55
+ ## Palettes (minimal films)
56
+
57
+ `sound.palette` is `{ "timbre": "<timbre>", "key": "<pitch class>", "mode": "<major|minor>", "tempo": <60-160> }`.
58
+ The key is one of the twelve pitch classes (sharps or flats), the mode sets the chord
59
+ progression (major: I–V–vi–IV; minor: i–VI–III–VII, always resolving home on the last chord), and
60
+ the tempo sets the pulse grid in BPM. A minimal film's generated bed takes one of the house style's beds exactly
61
+ (`studio.md`); the first is the default, and the other two let two films in one style differ:
62
+
63
+ | Style | Default bed | Alternatives |
64
+ | --- | --- | --- |
65
+ | `swiss-signal` | glass, A minor, 104 | pulse-synth, D minor, 112; soft-keys, C major, 96 |
66
+ | `tidal` | felt-strings, D major, 84 | glass, F# minor, 76; soft-keys, Bb major, 72 |
67
+ | `terminalcore` | pulse-synth, E minor, 120 | glass, B minor, 132; pulse-synth, A minor, 100 |
68
+ | `paper` | soft-keys, F major, 96 | felt-strings, G major, 88; glass, C major, 108 |
36
69
 
37
- Choose the four values for this film. A reflective portrait and a fast product cut should not share a
38
- palette, and two films in a row should not sound like siblings.
70
+ Pick the bed for the film's mood and pace: a slower or tenderer film takes the slower bed, a launch
71
+ the brighter one. Two films in one style still sound like one house; the beds, the beats' cue words
72
+ and the events make each film's sound its own.
39
73
 
40
- | Timbre | Feel | Pad | Pulse | Accent voice |
74
+ | Timbre | Character | Pad | Pulse | Accents |
41
75
  | --- | --- | --- | --- | --- |
42
- | `soft-keys` | warm, close, unhurried | rounded electric-piano partials, light detune, low-passed at 2.6 kHz | a felt kick on every beat | a felt piano strike |
43
- | `glass` | bright, airy, exact | bell-like odd partials with an octave shimmer, open to 7 kHz | a small tick each beat, a sub note each bar | inharmonic bell partials |
44
- | `pulse-synth` | driving, graphic | a filtered saw pad | eighth-note bass on the chord root under a firm kick | a plucked saw, a noise snap, a pitched riser |
45
- | `felt-strings` | slow, tender, wide | bowed-string partials with vibrato | a brushed noise pulse each beat | a soft felt strike |
46
-
47
- As a starting point: intimate or reflective films lean on `soft-keys` or `felt-strings`, clean diagrams and
48
- precise explainers on `glass`, and graphic fast-cut pieces on `pulse-synth`.
49
-
50
- ## Asking for accents
76
+ | `soft-keys` | Warm, close, unhurried | Rounded electric-piano partials, gently detuned, low-passed | A felt kick on every beat | Felt piano strike for cadences; a soft noise-and-thump hit |
77
+ | `glass` | Bright, airy, precise | Bell-like odd partials with an octave shimmer, wide detune | A small tick on every beat and a sub note every bar | Inharmonic bell partials for hits and cadences |
78
+ | `pulse-synth` | Driving, graphic | Filtered saw pad | Eighth-note bass on the chord root under a firm kick | Plucked saw cadence; a noise snap hit; a pitched riser |
79
+ | `felt-strings` | Slow, tender, wide | Bowed-string partials with vibrato | A brushed noise pulse on every beat | A felt strike for cadences; a soft hit |
51
80
 
52
- The bed adds an accent only where a beat's `sound` text asks for one. It reads three kinds of word:
81
+ `soft-keys` carries the warm paper style, `felt-strings` the calm tidal one, `glass` the precise
82
+ swiss-signal one and `pulse-synth` the terminal one.
53
83
 
54
- - **hit**: hit, impact, cut, stab, accent, 타격, 히트, 컷, 강세. The hit lands on the cut nearest the beat's
55
- start when one lies within 0.5 s, else on the beat's start.
56
- - **rise**: rise, riser, swell, build, build-up, lift, 상승, 고조, 빌드업. A filtered noise swell that ends on
57
- the beat's end (snapped to a cut within 0.5 s) and starts up to 1 s before it, never before the beat.
58
- - **cadence**: cadence, resolve, resolution, close, closing, ending, final chord, 종지, 마무리, 해결. A struck
59
- tonic chord at 60 % of the beat, ringing to the beat's end, or to the film's end on the last beat.
84
+ ## Cues
60
85
 
61
- A beat that names none of these gets pad and pulse only. The cut times come from the beats on the stage
62
- path and from the brief's shots on the type path.
86
+ Accents appear only where a beat's free-text `sound` field asks for one. The words that ask are:
63
87
 
64
- `<dir>/sound-cues.json` records each cue with `kind`, `t` in seconds, `beatIndex`, `target` (the boundary or
65
- cut it serves) and `delta` (`t - target`), alongside the timbre, key, tempo, loudness, peak, sample count
66
- and the bed's SHA-256. Look question 6 ("does the sound follow the cuts?") is answered from this file: every
67
- requested accent should sit on its target within one frame, and every beat whose text asked for an accent
68
- should have one.
88
+ - **hit** — hit, impact, cut, stab, accent, 타격, 히트, 컷, 강세. The hit lands on the cut nearest
89
+ the beat's start when one is within 0.5 s, otherwise on the beat's start.
90
+ - **rise** — rise, riser, swell, build, build-up, lift, 상승, 고조, 빌드업. A filtered noise swell
91
+ that ends exactly on the beat's end boundary (the next change) and starts up to 1 s before it.
92
+ - **cadence** — cadence, resolve, resolution, close, ending, final chord, 종지, 마무리, 해결. A struck
93
+ tonic chord at the start of the beat's last 40 %, ringing into the film's end on the last beat.
69
94
 
70
- ## Levels and length
95
+ A beat whose `sound` field names none of these gets pad and pulse only.
71
96
 
72
- - The bed is 48 kHz, 16-bit stereo, exactly `round(frameCount × 48000 / fps)` samples, so it matches the
73
- picture sample for sample.
74
- - It is normalized to −16 LUFS integrated, measured in product code per ITU-R BS.1770-4 (K-weighting,
75
- 400 ms blocks with 75 % overlap, the −70 LUFS absolute and −10 LU relative gates), through a
76
- deterministic soft limiter that keeps the sample peak at or under −2 dBFS.
77
- - The pad sounds within the first quarter second; the bed never opens on silence.
78
- - A supplied or authored track is converted to the film's exact length, with a 50 ms fade where it is
79
- trimmed or padded. The encode never uses `-shortest`, so audio can never cut the picture short.
80
- - Audio is encoded as AAC at 256 kb/s.
97
+ ## Events
81
98
 
82
- ## The sound gate
99
+ Cue words tie accents to cuts. Events tie sounds to what moves inside a shot: a latch clicks when the
100
+ lid opens, a card lands, a cursor types, a progress bar completes. A score or generated bed on the stage
101
+ path lists them in `sound.events`:
83
102
 
84
- Whenever `mode` is not `none`, the renderer decodes the muxed stream and adds these rules to the gate:
85
-
86
- | Rule | Passes when |
87
- | --- | --- |
88
- | `SOUND-STREAM` | an audio stream is present |
89
- | `SOUND-DURATION` | its length is within ±0.1 s of the video |
90
- | `SOUND-PEAK` | the sample peak is at or under −0.5 dBFS |
91
- | `SOUND-HEAD` | no stretch below −50 dBFS RMS (50 ms windows) lasts longer than 1.5 s in the first 3 s |
92
- | `SOUND-LOUDNESS` | reported; a generated bed outside −16 ± 2 LUFS warns |
93
-
94
- A missing stream when sound was planned, or a silent head on a generated bed, is exit 20 `SOUND_INVALID`.
95
- A silent head on a supplied or authored track only warns, since the user's music may open quietly. An
96
- authored file outside the stage folder, or a track that cannot be read or converted, is also exit 20 with
97
- the field named.
98
-
99
- ## Hearing it before the render
100
-
101
- ```bash
102
- node "$SKILL_ROOT/scripts/motion.mjs" sound --out <dir>
103
+ ```json
104
+ "events": [{ "t": 6.42, "on": "the lid clicks open", "kind": "tap" }]
103
105
  ```
104
106
 
105
- This reads `<dir>/treatment.json` and writes `<dir>/sound/bed.wav` and `<dir>/sound-cues.json`, so the cue
106
- deltas can be checked before any frame is captured. For a supplied, authored or silent plan it only reports
107
- what the render will do. The full render rebuilds the bed itself at the film's real frame count and cut
108
- times, so the muxed bed always fits the final cut.
109
-
110
- ## The optional analysis tier
111
-
112
- On the type path a supplied track (or the brief's `audio` file) can drive shot timing through a beat grid
113
- made by librosa. That tier lives in a separate venv that is installed once, from a terminal or as a `run_command` the user allows:
107
+ - `t`: the second the event happens on screen, read from the page's own timing (the same expression
108
+ the page draws with), never guessed from the beat;
109
+ - `on`: what happens at that frame, as a viewer would see it;
110
+ - `kind`: `tap` (a short click with a pitched body: a key, a latch, a landing), `hit` (the cut hit),
111
+ `whoosh` (air that ends on the event: something flies in) or `chime` (two notes of the key:
112
+ something completes).
113
+
114
+ At least two events, and at least half of them 0.1 s or more away from every cut, so the sound follows
115
+ the picture rather than only the edit. An event never snaps to a cut: it sounds at its own `t`. Each
116
+ one appears in `sound-cues.json` as `kind: "event"` with `sound`, `on` and `fromCut`. `sound-cues.json` lists
117
+ every cue with `kind`, `t` (seconds), `beatIndex`, `target` (the beat boundary or cut it serves)
118
+ and `delta` (`t − target`), plus the palette, key, tempo, loudness, peak, sample count and the
119
+ bed's sha256. Look question 6 ("does the sound follow the cuts and the events?") is answered from
120
+ this file and the stills: each asked-for accent should sit on its cut with a delta within one frame,
121
+ every cut the treatment marks for sound should have a cue, and each event's frame should show what its
122
+ `on` says.
123
+
124
+ ## Loudness and limits
125
+
126
+ - 48 kHz, 16-bit, stereo WAV of exactly `round(frameCount × 48000 / fps)` samples.
127
+ - Integrated loudness −16 LUFS ± 2, measured in product code per ITU-R BS.1770-4 (K-weighting at
128
+ 48 kHz, 400 ms blocks with 75 % overlap, −70 LUFS absolute and −10 LU relative gates). A
129
+ deterministic lookahead limiter (5 ms ahead, both channels linked, 80 ms release) keeps the track's
130
+ sample peak at or under −2 dBFS by turning the gain down before a peak, never by bending the
131
+ waveform, so the AAC encode does not push the decoded peak over the audit's −0.5 dBFS.
132
+ - The intro is audible from the first quarter second, so the track never opens on silence.
133
+ - The muxed stream is decoded and gated when `mode` is not `none`: a stream is present, its
134
+ duration is within ±0.1 s of the video, and its sample peak is at or under −0.5 dBFS. For a
135
+ score or a generated bed, no stretch below −50 dBFS RMS (50 ms windows) may last longer than 1.5 s in the
136
+ first 3 s; that failure, or a missing stream when sound was planned, is exit 20
137
+ (`SOUND_INVALID`). For a supplied or authored track the head rule only warns.
138
+ - Audio is encoded as AAC at 256 kb/s. A supplied or authored track is padded or trimmed to the
139
+ video's duration with a 50 ms fade; the encode never uses `-shortest`, so the audio can never cut
140
+ the film short.
141
+
142
+ ## Commands
114
143
 
115
144
  ```bash
116
- node "$SKILL_ROOT/scripts/motion-runtime.mjs" install --audio
145
+ node "$SKILL_ROOT/scripts/motion.mjs" sound --out <dir>
117
146
  ```
118
147
 
119
- It needs Python 3.10 or newer (`LITGRAVITY_MOTION_PYTHON` picks the interpreter) and installs hash-pinned wheels
120
- into the LitGravity motion cache. Without it, or when analysis finds fewer than two beats, the render warns
121
- and times shots by reading time (Tier 1); the track itself is still muxed. A render never installs the tier.
148
+ reads `<dir>/treatment.json` and writes the score (`<dir>/sound/score.wav` and its stems) or a minimal
149
+ film's bed (`<dir>/sound/bed.wav`), and `<dir>/sound-cues.json`, so the track can be heard and its cues
150
+ checked before a render. The render rebuilds the track at the film's exact frame count and cut times,
151
+ so the muxed track always matches the film sample for sample. Two builds from the same treatment give
152
+ the same bytes.