@allyhub/sdk 0.1.0-alpha.8 → 0.2.0-next.0

package/docs/speech.md

@@ -0,0 +1,289 @@
+# Speech
+
+What a part says: a recording (`take()`), text to speech (`say()`) or a stretch of another video item (`take(piece)`). Its words time the part, place its layers and sounds, duck the music and make the captions. This file covers those, word references, anchors, shown-and-said text, captions and the words and edits files.
+
+```ts file=launch/film/video.ts
+import { part, say, take, video } from "@allyhub/sdk";
+
+import vo from "./vo/en.mp3";
+
+export default video({
+  format: "16x9",
+  parts: ({ s }) => [
+    part({ key: "hook", speech: take(vo).saying(s("launch.film.hook.say")) }),
+    part({
+      key: "how",
+      speech: take("./vo/en.mp3").saying(s("launch.film.how.say")).speed(1.1),
+    }),
+    part({
+      key: "host",
+      speech: take("./host.mp4")
+        .range("So here is", "every time")
+        .edits("./edits/host.json")
+        .denoise(12)
+        .roomTone({ limitDb: 4, fade: 0.06 }),
+    }),
+    part({
+      key: "cta",
+      speech: say(s("launch.film.cta.say"), { voice: "rachel", speed: 1.05 }),
+    }),
+  ],
+});
+```
+
+A path written as a string (`take("./host.mp4")`, `.edits("./edits/host.json")`) is relative to the module that wrote it, also once the part is spread into another piece ([project.md](project.md)).
+
+## A part's length
+
+A part with speech lasts lead + speech + tail: `lead` before the first word (default 0.2 s) and `tail` after the last (default 0.3 s), less any `overlap` ([J and L cuts](#j-and-l-cuts)). A part without speech lasts `dur` (default 4 s). The defaults are `PART_DEFAULTS`, changed for the project by `defaults.part` in `allyhub.config.ts` and for one video by `video({ defaults: { part } })`.
+
+## `take(file)`
+
+A recording, audio or video (an import, or a path), with its words in `<name>.words.json` beside it ([Words files](#words-files)). `allyhub words <file>` hears it on this computer and writes that file. A take without one is AK-T001.
+
+Alone, a take is the whole recording, from its first word to its last. Each method returns a new take:
+
+- `.range(from, to?)`: the stretch from the first words `from` to the end of the first `to` after them (phrases; case and punctuation ignored); without `to`, to the end. A phrase not found is AK-T003.
+- `.saying(text)`: the stretch that says this line, usually `s(key)`, found by its words, misheard words tolerated; the line's spelling is the caption. Parts that take the same file each search after the previous part's stretch. A line not found is AK-T003.
+- `.edits(path)`: a cut list, a `.json` file ([Edits files](#edits-files)). One that is not there, or does not match the format, is AK-T005: the take would play uncut.
+- `.denoise(db?)`: reduces its noise by `db` (over 0, up to 97; default 12) with ffmpeg's FFT denoiser, in the render and the preview.
+- `.roomTone(tone)`: how the part's lead and tail are filled where the take has no silence of its own round the part's words ([Room tone](#room-tone)).
+- `.speed(times)`: plays it `times` as fast, its pitch kept (0.5 to 2); its words, the part's length and everything timed by them follow. The file is not changed. A part whose `footage()` shows the take's own picture cannot change its speed (`part()` throws).
+
+With `.edits()`, `range` and `saying` look only at the words the edits keep: a phrase or line said only in removed words is AK-T006. A take a voice tool generated keeps the text it was made from in its `.gen.json`: a part whose line is not in that text is AK-T007.
+
+### Room tone
+
+A part's lead and tail play the take's own room round its words. Where that runs out, a room tone fills them:
+
+- The fill is the quietest steady stretch the build measured, or `{ from, to }` (seconds of the file, both given, at least 0.05 s apart), looped. `.roomTone(false)` leaves digital silence.
+- Its level is matched to the floor of the take's own room beside the join (the mean power of the quietest quarter of the 10 ms frames within 0.3 s), at most `limitDb` either way (0 to 60; default 6). `match: false` plays it as recorded; `gainDb` (−60 to 24) sets its gain instead. Where the take keeps under 0.1 s of its own room at a join, or its levels are not known, it plays as recorded.
+- It cross-fades with the take over `fade` seconds (0 to 1; default 0.04), equal-power.
+
+The values are `ROOM_MATCH` ([defaults.md](defaults.md)). `allyhub inspect timeline` prints each fill's gain and where it came from.
+
+## `take(piece)`
+
+A stretch of another video item of the project, imported, with a clock of its own:
+
+```ts file=scene/video.ts
+import { part, video } from "@allyhub/sdk";
+
+export default video({
+  format: "16x9",
+  deliverable: false,
+  parts: () => [
+    part({ key: "desk", dur: 6, anchors: { turn: 1.2, press: [3, 4.5] } }),
+  ],
+});
+```
+
+```ts file=short/video.ts
+import { footage, part, take, video } from "@allyhub/sdk";
+
+import scene from "../scene/video.ts";
+
+export default video({
+  format: "9x16",
+  parts: () => [
+    part({
+      key: "cut",
+      speech: take(scene).range("@turn", "@/press"),
+      layers: [footage()],
+    }),
+  ],
+});
+```
+
+- `.range(from, to?)` takes seconds of its clock, an anchor of one of its parts (`"@turn"`, `"@/turn"`, `"@turn+0.2"`) or a part's key; without `to`, to its end. A reference it does not have is AK-T003.
+- Its ends go on the frame grid, never into a word they are not in (a stretch that splits a word is a `cut-in-word` fact). The part lasts the stretch exactly, with no lead or tail; it hears the item's speech, room tone and sound effects (not its music), says its words and has its anchors.
+- `footage()` without a file draws its picture in sync, in the part's frame whatever the item's own format ([footage.md](footage.md)). `deliverable: false` marks an item that is only shown inside others.
+
+## `say(text, opts?)`
+
+Text to speech. `allyhub voice` makes the missing files with the cloud voice tool, each in `assets/media/gen/say/<hash>` with its words and its record (`--quote` prices them first). A `say` without its file is AK-T002; until it has one, the part lasts about as long as the line takes to say (`SPEECH_RATE_DEFAULTS`: 0.38 s a word, 0.22 s a Chinese, Japanese or Korean character; at least 1 s), and its anchors are placed in proportion along the line.
+
+- `voice`: the voice tool's voice id; default the tool's own.
+- `tool`: the voice tool; default `"tts-elevenlabs-multilingual-v2"` (`allyhub help ai <tool>` lists its input).
+- `params`: more input for the tool, plain JSON: fields its schema has besides the text and voice (`text` and `voiceId` throw).
+- `speed`: 0.5 to 2, default 1: plays the file faster or slower, pitch kept, as `.speed()` does. Not sent to the tool, so the same file.
+
+The file is named by a hash of the text read aloud, the voice, the tool and the params: a changed line needs a new file. Text from `s(key)` is read aloud as its said side ([Shown and said](#shown-and-said)).
+
+## Word references
+
+A word reference names a moment of a part by what is said there. A layer's `at` and `until`, a part's `still`, a sound's `at`, a footage `punchIn` and every prop declared `time()` take one; a layer reads one with `ctx.at(ref)`, in seconds from the part's start.
+
+| Reference | Moment |
+| --- | --- |
+| `"inbox"` | The start of the first time "inbox" is said in the part |
+| `"inbox@2"` | The second time |
+| `"inbox+0.2"`, `"inbox@2-0.35"` | Shifted by seconds |
+| `"@name"`, `"@/name"`, `"@name+0.2"` | An [anchor](#anchors)'s start, a stretch's end, shifted |
+| `1.8`, `"1.8"` | Seconds from the part's start |
+
+A reference may be a phrase; case and punctuation are ignored. With `say` or `saying` a reference is found in the line first, so a misheard word still lands where it is said. A reference the part does not say, or any word in a part without speech, is AK-T004.
+
+## Anchors
+
+An anchor is a name written in the line a part says, in each language's script (`script.<lang>.yaml`, [project.md](project.md)). The code refers to the name, so a reworded or translated line keeps what hangs on it.
+
+```yaml
+parts:
+  - id: how
+    say: "@{step1}Paste your form link. We @{step2}match the answers you @{have}already have@{/have}."
+```
+
+| In the line | In code | Moment |
+| --- | --- | --- |
+| `@{name}` | `"@name"` | A point: the start of the word after it (the end of the last word, at the line's end) |
+| `@{name}…@{/name}` | `"@name"`, `"@/name"` | A stretch: the start of its first word, the end of its last |
+| | `"@name+0.2"`, `"@/name-0.1"` | Shifted by seconds |
+
+```ts file=launch/how.ts
+import { custom, part, say, type MessageReader } from "@allyhub/sdk";
+
+export const how = (s: MessageReader) =>
+  part({
+    key: "how",
+    speech: say(s("launch.film.how.say")),
+    sounds: [{ at: "@step1", sound: "tick" }],
+    layers: [
+      custom({
+        at: "@step2",
+        until: "@/have+0.3",
+        mount(el, ctx) {
+          el.dataset["step"] = String(ctx.at("@step1"));
+          el.dataset["film"] = String(ctx.film?.at("@step1") ?? 0);
+        },
+        render() {},
+      }),
+    ],
+  });
+```
+
+- An anchor is looked up in the line the part says, so the speech comes from that script line: `say(s("<prefix>.<part>.say"))` or `take(…).saying(s(…))`. A name the line does not have is AK-T004.
+- A name is letters, digits, `_` and `-`, once in a line; stretches may overlap. A name written twice, an end without a start, a stretch with no words and an anchor in a plural are AK-M007. An anchor goes before a `<shown|said>` piece, not inside it.
+- An anchor lands by the line's letters matched to the words of its sound.
+- `ctx.at("@name")` is seconds from the part's start; `ctx.film.at("@name")` is film seconds and takes an anchor of any part. `allyhub inspect timeline` prints where each landed.
+
+### A part's own anchors
+
+A part names moments in seconds from its start, with no speech needed: `part({ anchors: { press: 7.1, map: [9.6, 13.4] } })`. A number is a point, `[from, to]` a stretch; `"@press"`, `"@map"`, `"@/map"` and `"@press+0.2"` work as above. A name is the line's or the part's own, not both: a name in both is AK-T004, and `"@name"` is the part's own.
+
+## Shown and said
+
+A piece of a script's `say` shown one way and said another is `<shown|said>`: `from <12|twelve> fields`, `<AI|A I>`. The line as shown is what `s()` returns, titles and captions show; the line as said is what `say` reads aloud and what `saying` looks for in a recording. Either side may be empty: `<™|>` is shown and not said, `<|[laughs]>` said and not shown. In `assets/text/<lang>.json`, the same is a `{ "display", "speak" }` value.
+
+## Captions
+
+Burned-in captions are a graphic layer in each part that has them: a starter component (`captionWord`, `captionLine`, `captionSubtitle`, added with `allyhub add`), a component of the project's, or `custom()`. In any layer:
+
+- `ctx.words()` is the part's words on its clock, `{ text, start, end, confidence? }`; empty without speech.
+- `ctx.captions(opts?)` is the cues heard over the part, on its clock:
+
+```ts fragment
+type CaptionTrackCue = {
+  start: number;
+  end: number;
+  text: string;
+  words: { text: string; start: number; end: number }[];
+};
+```
+
+| Option | Default | What it is |
+| --- | --- | --- |
+| `maxChars` | 32 (16 for Chinese, Japanese and Korean) | Most characters in a cue |
+| `maxWords` | none | Most words in a cue |
+| `keep` | none | Phrases a cue never breaks inside, matched as said; the cue round one may run over the limits |
+| `close` | 0.4 | A gap between two cues shorter than this many seconds closes |
+| `edges` | false | `true`: the first cue from the part's start, the last to its end |
+
+Cues come from the part's speech (a cut take's kept words, spelled as the script when there is one), break at sentence and clause ends, then by length, and never span two parts. In a J or L cut, the words heard under a neighbour's picture are there too. Where they go and which words they stress is the layer's code:
+
+```ts file=launch/captions.ts
+import { custom } from "@allyhub/sdk";
+import { emojiEl, emphasized, h, wordEmoji } from "@allyhub/sdk/dom";
+
+export const captions = custom({
+  mount(el, ctx) {
+    for (const cue of ctx.captions({ maxChars: 20, edges: true })) {
+      const line = h("div", { opacity: 0 });
+      line.dataset["start"] = String(cue.start);
+      line.dataset["end"] = String(cue.end);
+      const stressed = emphasized(cue.words, ["free", "two minutes"]);
+      const emoji = wordEmoji(cue.words, { free: "🎁" });
+      cue.words.forEach((w, i) => {
+        const color = stressed[i] ? "var(--ak-color-accent)" : "inherit";
+        line.append(h("span", { color }, [`${w.text} `]));
+        const e = emoji[i];
+        if (e) line.append(emojiEl(e));
+      });
+      el.append(line);
+    }
+  },
+  render(el, t) {
+    for (const line of Array.from(el.children) as HTMLElement[]) {
+      const on =
+        t >= Number(line.dataset["start"]) && t < Number(line.dataset["end"]);
+      line.style.opacity = on ? "1" : "0";
+    }
+  },
+});
+```
+
+`emphasized` and `wordEmoji` match as said (case, accents and punctuation ignored, whole words; a phrase marks each of its words, its emoji on its last). `captionTop` and `freeAreas` measure a place for them ([layers.md](layers.md)).
+
+Subtitle files (`allyhub render --type srt,vtt`) come from each voiced part's line. A piece whose layers call `ctx.captions()` has its subtitles cut as the first such layer asked; otherwise by `CAPTION_CUE_DEFAULTS`: one line a cue of at most 42 characters (16 in Chinese, Japanese and Korean), 0.8 to 6 s, 2 frames before the next.
+
+## J and L cuts
+
+`part({ overlap: { before, after } })`, seconds from 0 to 10: `before` seconds of the part's speech play under the previous part's picture, `after` seconds under the next part's. The part's picture is shorter by them. Each is at most the part's lead (or tail) plus half its speech; the first part's `before` and the last part's `after` do nothing.
+
+## Speech gain
+
+`part({ speechGainDb })` (−40 to 24, default 0) turns the part's speech up or down after it is recorded ([sound.md](sound.md#how-the-voice-was-recorded)), as an editor's clip volume: the recording's compressor does not even it out, and its room tone moves with it.
+
+## Words files
+
+`<name>.words.json` beside the recording (its extension replaced): the words said in it, in the order said, with times in seconds of the file. `allyhub words` writes it; an agent may correct it. A file that does not match the format is not read (AK-T001).
+
+```json
+{
+  "version": 1,
+  "language": "en",
+  "duration": 14.2,
+  "words": [
+    { "text": "So", "start": 0.42, "end": 0.6, "confidence": 0.98 },
+    { "text": "here", "start": 0.63, "end": 0.81 }
+  ]
+}
+```
+
+`version` is 1; `language` (a BCP 47 tag), `duration` (seconds) and `model` (what recognised it) are optional. Each word's `text` keeps its punctuation, `end` is at or after `start`, and `confidence` (0 to 1) is absent when recognition did not say. `$schema` may name a JSON Schema; any other field is an error.
+
+## Edits files
+
+A take's cut list, a JSON file named by `.edits("./edits/<name>.json")`. It removes exactly what it lists, without touching the recording; `{ "version": 1 }` removes nothing. Which words are fillers, retakes or false starts is the agent's to decide.
+
+```json
+{
+  "version": 1,
+  "take": "talk/host.mp4",
+  "remove": [{ "from": 167, "to": 189, "text": "Now second, figure out" }],
+  "sounds": [{ "from": 61.17, "to": 61.4 }],
+  "inWord": [{ "from": 12.31, "to": 12.62 }],
+  "maxPause": 0.35,
+  "pad": { "before": 0.12, "after": 0.08 }
+}
+```
+
+- `remove`: words, by their indices in the words file (both ends included), with their `text`. When the take is heard again, a range is found again by its text, nearest its old place.
+- `sounds`: stretches of the file (seconds) between words; cut only between two kept words, never into one.
+- `inWord`: stretches of the file cut even inside a kept word; each end moves only to the quietest 10 ms within 40 ms. One that reaches the first or last word of a part's stretch moves that end.
+- `maxPause`: every pause between kept words longer than it (0.05 to 10 s) is shortened to it.
+- `pad`: the silence a cut keeps, `before` it after the last kept word (default 0.12 s) and `after` it before the next kept word (default 0.08 s); never past half the silence.
+- `take`: the recording it cuts, a note for people; the code names the file.
+- `version` is 1; `$schema` may name a JSON Schema; any other field is an error.
+
+Every cut lands in the silence, at the quietest 10 ms within 40 ms, on the frame grid, with 10 ms fades. The take's words, its footage and its sound follow the kept stretches. `allyhub words <take>` prints the take's words with their indices and the sounds between them; `allyhub words edits <take> <edits>` shows what an edits file keeps and removes and measures every join.

package/docs/video.md

@@ -0,0 +1,265 @@
+# Videos
+
+A video is the default export of an item's `video.ts`: `video({ …, parts })`, its parts in order, each with its speech (or a length) and its layers. Here: `video()`, formats, `part()`, layers and their stacking, transitions, the look, the camera filming the picture, post.
+
+```ts file=launch/film/video.ts
+import { part, say, video } from "@allyhub/sdk";
+
+export default video({
+  format: "16x9",
+  parts: ({ s }) => [
+    part({ key: "intro", dur: 3 }),
+    part({ key: "pitch", speech: say(s("launch.film.pitch.say")) }),
+  ],
+});
+```
+
+## `video()`
+
+`video(opts)` returns its fields as written, with where it was written, so another piece can spread it into its own ([Another format](#another-format-reusing-a-piece)).
+
+Every piece, a video or a deck, has:
+
+| Field | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `id` | string | the item's folder, from the project's root | A stable identity ([project.md](project.md)) |
+| `title` | string, or by language | the script's `title` (`<prefix>.title`), else the file name | The name people see |
+| `format` | `FormatEntry` | `allyhub.config.ts` `defaults.format`, else `"16x9"` | What it is rendered as: one format ([Formats](#formats)) |
+| `matrix` | `Matrix` | the project's languages | Dimensions and slots: which combos are made ([batches.md](batches.md)) |
+| `meta` | `Record<string, unknown>` | none | Any key-values, plain data |
+
+A video adds:
+
+| Field | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `parts` | `(ctx) => PartSpec[]`, or a promise | required | The parts, in order |
+| `covers` | `(ctx) => PartSpec[]` | none | Parts without speech, each drawn at its `still` for the cover image (`allyhub render --type cover`); their layers mount on elements of their own |
+| `fps` | number or string | 30 | A whole number from 1 to 120, or an NTSC rate: `23.976`, `29.97`, `47.952`, `59.94`, `119.88`, or `"24000/1001"` … |
+| `transparent` | boolean | false | No background: mov, webm and png keep the alpha; mp4 and gif show black where nothing is drawn |
+| `look` | string | `"clean"` | The look's name ([The look](#the-look)) |
+| `defaults` | `{ part?: { dur?, lead?, tail? } }` | the project's, over `PART_DEFAULTS` | This video's part defaults |
+| `music` | media, or `MusicOptions` | none | [sound.md](sound.md) |
+| `mix` | `MixOptions` | `MIX_DEFAULTS` | The stems' loudness, the music's ducking and fades ([sound.md](sound.md)) |
+| `master` | LUFS, `{ lufs, truePeak }`, or `false` | the profile's loudness, else −14 LUFS; −3 dBTP | What the sound is mastered to ([sound.md](sound.md)) |
+| `mic` | a setup's name, its options, or `false` | `"studio"` | How the speech was recorded ([sound.md](sound.md)) |
+| `capture` | `CaptureOptions` | none | A camera filming the picture ([The camera](#the-camera-filming-the-picture)) |
+| `post` | `{ filter?, lut? }` | none | An ffmpeg filter chain and a `.cube` LUT over the frames ([Post](#post)) |
+| `motionBlur` | `{ samples, shutter? }` | none | [Motion blur](#motion-blur) |
+| `maxDuration` | seconds | none | The longest a combo may last; longer is AK-X006 |
+| `deliverable` | boolean | true | `false`: only shown inside another video. Rendered only when named; the check leaves out the facts about watching it as a film |
+| `loadLimit` | seconds | 10 (`LOAD_LIMIT`) | How long loading may take; longer is AK-P002 |
+| `seekLimit` | seconds | 30 (`SEEK_LIMIT`) | How long one moment may take to draw; longer is AK-P003. Loading waits for its layers' work at most 4 times as long |
+
+### The parts function's `ctx`
+
+`parts`, `covers` (and a deck's `pages`) get a `PieceContext`:
+
+| Name | What it is |
+| --- | --- |
+| `ctx.combo` | This combo: one value per dimension and, with slots, its structure and one candidate per slot (`{ lang: "en", hook: "price" }`) |
+| `ctx.s` | The combo's text: `s(key, hint?)`, `s.list(prefix)`, `s.with(key, inputs)` ([project.md](project.md)) |
+| `ctx.asset(path)` | Media at a path made at run time, relative to the piece's file; fixed paths are imports |
+| `ctx.data(path)` | A data file (CSV rows, YAML, JSON) at a path made at run time, parsed: cast it, `ctx.data(path) as Plan[]` |
+| `ctx.pool(slot)` | The file a pool slot picked in this combo, as a path `footage()` and `ctx.asset()` take ([batches.md](batches.md)) |
+| `ctx.look` | The look |
+
+### Another format: reusing a piece
+
+A piece has one format. Another format is another item that imports what it shares:
+
+```ts file=launch/film-vertical/video.ts
+import { video } from "@allyhub/sdk";
+import film from "../film/video.ts";
+
+export default video({ ...film, id: "launch/film-vertical", format: "9x16" });
+```
+
+A path written as a string (a take's, footage's, a sound's, `music`, `post.lut`) is relative to the module that wrote it, also once spread into another piece; a field the new piece writes again is relative to the new piece.
+
+## Formats
+
+| Format | Pixels | Covered edges |
+| --- | --- | --- |
+| `16x9`, `9x16`, `1x1`, `4x5` | 1920 × 1080, 1080 × 1920, 1080 × 1080, 1080 × 1350 | the preset's (`PRESETS`) |
+| a platform profile | the platform's | the platform's interface |
+| `WIDTHxHEIGHT` | each side 64 to 8192, even for a video | none |
+| `a4`, `letter` (slides only) | at 150 dpi | none |
+
+The **platform profiles** (`PROFILES`) are `tiktok`, `reels`, `shorts`, `meta-feed`, `amazon` and `linkedin`: a frame with the edges the platform's interface covers, its longest video (AK-F001), the loudness the sound is mastered to when the video sets no `master`, and how `allyhub render` encodes an mp4 for it. Every preset's and profile's numbers: [defaults.md](defaults.md). Any other format is AK-G001.
+
+A format can change its numbers with a `FormatSpec`; its name stays the format's own (combos and file names use it):
+
+```ts fragment
+format: { format: "tiktok", safe: { bottom: 520 }, maxDuration: 60, loudness: -16 }
+```
+
+`safe` (whole pixels per edge, any format; edges not given keep the format's) changes the covered edges; `maxDuration` (seconds) and `loudness` (LUFS) belong to a platform profile only.
+
+A layer reads `ctx.format` (the name) and `ctx.dims`: `{ width, height, orient, safe, profile? }`, `orient` `"landscape"`, `"portrait"` or `"square"`, `safe` the covered edges in pixels. Lay out by `ctx.dims` or `layout(ctx)` ([layers.md](layers.md#the-content-box)), not by the name: a custom `WxH` or a changed `safe` has none of its own.
+
+## Parts
+
+`part(opts)` makes a part of a video, or a page of a deck.
+
+```ts
+import { part, take } from "@allyhub/sdk";
+
+export const demo = part({
+  key: "demo",
+  title: "Demo",
+  speech: take("./vo/en.mp3").range("Paste your link", "and you're done"),
+  lead: 0.3,
+  tail: 0.5,
+  still: "done",
+  transition: { type: "push", direction: "up", dur: 0.5 },
+  overlap: { before: 0.4 },
+});
+
+export const end = part({ key: "end", dur: 3, transition: "fade" });
+```
+
+| Option | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `key` | string | required | Unique in the video (a repeat is AK-K001), stable across combos. A part whose key is a slot's name fills that slot |
+| `title` | string | its largest text at its still that not every part shows | Its name for people: the timeline, a note |
+| `slot` | string | its key, when that is a slot's name | The slot it fills, when the piece has slots ([batches.md](batches.md)) |
+| `speech` | `take(…)`, `say(…)` | none: silent | What it says ([speech.md](speech.md)) |
+| `dur` | seconds | 4 (`defaults.part.dur`) | The length of a part without speech; ignored with speech |
+| `lead`, `tail` | seconds | 0.2, 0.3 (`defaults.part`) | Before the first word, after the last |
+| `layers` | `LayerSpec[]` | none | What it shows, back to front ([Layers](#layers)) |
+| `still` | word reference, seconds, or `(dur) => seconds` | 0.4 s before its end | The moment drawn for a cover, a sheet, a page |
+| `transition` | a type's name or `TransitionSpec` | a cut | How it comes in from the part before ([Transitions](#transitions)) |
+| `overlap` | `{ before?, after? }`, seconds, 0 to 10 | none | J and L cuts: `before` seconds of its speech play under the previous part's picture, `after` under the next part's |
+| `anchors` | `{ name: seconds \| [from, to] }` | none | Named moments of the part, from its start ([speech.md](speech.md)) |
+| `sounds` | `SoundSpec[]` | none | Sound effects ([sound.md](sound.md)) |
+| `mic` | as the video's | the video's | How this part's speech was recorded |
+| `speechGainDb` | dB, −40 to 24 | 0 | Its speech turned up or down after it is recorded |
+| `post` | `{ filter }` | none | The part's own grade ([Post](#post)) |
+| `tags` | string[] | none | Labels the matrix's rules read ([batches.md](batches.md)) |
+
+`part()` throws for a value it cannot use (an empty key, an `overlap` or a gain out of range, a bad transition, anchor, `mic` or `post`), and for a take played at another speed in a part that shows the take's own picture.
+
+**A part's length.** A part with speech lasts `lead` + its speech (its first word to its last) + `tail`; its picture is shorter by its `overlap`. A part without speech lasts `dur`; with `music.snap` it ends on the music's beat ([sound.md](sound.md)). Parts follow each other on the frame grid. Lengths are worked out from the speech each time: change a take and the parts follow.
+
+Part defaults, from the weakest: `PART_DEFAULTS`, `allyhub.config.ts`'s `defaults.part`, the video's `defaults.part`, the part's own.
+
+## Layers
+
+A part's layers are drawn back to front in the order listed, footage and graphics alike: a graphic layer listed before a footage layer is under it, one between two is between them. Footage layers are `footage()` ([footage.md](footage.md)); graphic layers are made by a component or `custom()` ([layers.md](layers.md)).
+
+Every layer takes:
+
+| Option | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `at` | word reference or seconds | 0 | When it starts, from the part's start |
+| `until` | word reference or seconds | the part's end | When it stops |
+| `dur` | seconds | | Its length from `at`, when there is no `until` |
+| `z` (graphic layers) | `"front"`, `"behind-person"`, `"overlay"` | `"front"` | Where it stacks |
+
+A word reference is a word the part says (`"inbox"`, `"inbox@2"`, `"inbox+0.2"`), an anchor (`"@press"`), or seconds ([speech.md](speech.md)).
+
+**Stacking (`z`).**
+
+- `"front"`: at its place in the list.
+- `"behind-person"`: drawn right over the part's own footage (the `footage()` without a file) wherever it is listed, and under that take's speaker, who is cut out with the take's person matte ([footage.md](footage.md)).
+- `"overlay"`: over the finished picture, as an app lays captions and stickers over a filmed video: over every other layer, and not marked by `capture`, `motionBlur`, `post` or the LUT. In a transition's window each part's overlays move and fade with its picture.
+
+## Transitions
+
+Parts join with cuts. A part comes in with a transition only when it says so: `transition: "fade"`, or a type with its options.
+
+| Type | What happens | Its own options |
+| --- | --- | --- |
+| `fade` | A crossfade | |
+| `dip` | The part before fades to a colour, this part fades in from it | `color`: a CSS colour; default the look's background |
+| `slide` | This part travels in over the part before, which stays | `direction`: `"left"` (default), `"right"`, `"up"`, `"down"` |
+| `push` | This part pushes the part before out, both travelling | `direction` |
+| `wipe` | An edge travels across and uncovers this part; neither picture moves | `direction` |
+| `zoom` | The part before grows to `scale` while this part fades in, settling from `from` | `scale` (over 1, up to 4; default 1.2), `from` (0.1 to 4; default `scale`; under 1 it grows in instead) |
+| `custom` | The channels given directly | `out`, `in`, `color` |
+
+Every type takes `dur` (over 0, up to 10 s; default 0.4), `ease` (`"linear"`, `"in"`, `"out"`, `"in-out"`; default `"linear"` for fade, dip and custom, `"in-out"` for the others) and `split` (0 to 1, the share of the window before the join; default 0.5). Defaults: `TRANSITION_DEFAULTS`.
+
+- Parts keep their lengths and places: the window lies across the join. Outside its own time a part's graphics hold its first or last frame and its footage runs on in its file.
+- The whole picture transitions, footage and graphics together. In a `transparent` video a fade adds the two pictures, weighted.
+- Sound is not changed: place a sound on the join with `sounds`.
+- The first part's transition is ignored, and so is a deck's.
+
+A `custom` transition gives `out` (the part before) and `in` (this part, over it) as `{ x, y, scale, opacity, clip: { left, right, top, bottom } }`, and `color: { value?, opacity }`, a colour between them. Each channel is a number (held), `[from, to]`, or keys `[{ p, v }]` over the progress `p` (0 to 1, in order, linear between keys, after `ease`). `x` and `y` are shares of the frame's width and height (−4 to 4), `scale` is about the frame's centre (0.01 to 8), `opacity` and `clip` are 0 to 1. Channels not given rest.
+
+```ts
+import { part } from "@allyhub/sdk";
+
+export const slideIn = part({
+  key: "custom",
+  dur: 2,
+  transition: {
+    type: "custom",
+    dur: 0.6,
+    ease: "out",
+    out: { x: [0, -0.3], opacity: [1, 0] },
+    in: { x: [1, 0] },
+  },
+});
+```
+
+## The look
+
+A look is the variables layers draw with: `ctx.look`, and the same as CSS variables on the stage.
+
+| Token | CSS variable |
+| --- | --- |
+| `color.bg`, `fg`, `accent`, `muted`, `surface` | `--ak-color-bg`, `--ak-color-fg` … |
+| `font.display`, `body`, `mono`, `emoji` | `--ak-font-display` … |
+| `motion.beat`, seconds per beat | `--ak-motion-beat` |
+| `sfx`: sounds by name | |
+
+The built-in look is `clean` (`CLEAN_LOOK`; its values in [defaults.md](defaults.md)). `allyhub.config.ts`'s `look` (`{ color?, font?, motion?, sfx? }`, each field optional) is laid over it for every video and deck in the project, under the same name ([project.md](project.md)). `sfx` names audio files relative to the project's root; every look also has the synthesized `whoosh`, `tick` and `pop`, unless it gives a file of the same name. `clean`'s `font.mono` is the computer's own monospace: bring a font for code.
+
+## The camera filming the picture
+
+`capture` is what a camera filming the picture does to it, before `post`. Each mark is drawn only when given; `{}` takes that mark's defaults (`CAPTURE_DEFAULTS`). Lengths are px at 1080 lines.
+
+| Field | What it is | Range |
+| --- | --- | --- |
+| `bloom: { threshold, radius, strength }` | Light above `threshold` blurred by `radius` and added at `strength` | 0–0.99, 0–200, 0–1 |
+| `aberration` | Red and blue drawn apart at the corners by this many px, less toward the centre | 0–20 |
+| `soften` | The lens's softness, a Gaussian blur's sigma | 0–20 |
+| `vignette` | How much darker the corners are | 0–0.99 |
+| `exposure: { drift, period }` | The exposure breathing as a phone meters: stops, over seconds | drift 0–2, period over 0 |
+| `grain: { amount, size, shadows, highlights, chroma, chromaSize, static }` | `amount`: its deviation at middle grey (share of full scale); `size`: its softness; × `shadows` at black, × `highlights` at white, drawn smaller near either end so nothing clips; `chroma`: each channel's own noise, softer by `chromaSize`; `static`: the same grain every frame | amount 0–0.166 |
+| `sharpen` | The phone's sharpening: unsharp masking's amount | 0–5 |
+
+Each frame's marks are a function of its frame number in the film: a still is the render's frame, and nothing starts again at a cut. `allyhub frames compare` measures grain and edge softness against a reference's frame.
+
+## Post
+
+`post: { filter?, lut? }` runs over the frames after the camera's marks: one ffmpeg filter chain, then a 3D LUT (`.cube`) at a path relative to the module that wrote it.
+
+- One chain: no `;`, no `[labels]`, no filter that reads or writes files.
+- It gets the picture opaque as 8-bit planar RGB (`gbrp`), its `t` the film's time, and what it gives back is made opaque `gbrp` again.
+- Use `t`, not `n`: `n` counts from each segment's first frame. A chain whose frames depend on where a segment starts (`n`, a seed drawn per frame, neighbouring frames) is AK-D002; one that does not run is AK-M001.
+
+A part's `post: { filter }` is the same contract on that part's picture alone, before the camera's marks and the video's `post`: a clip's white balance or exposure.
+
+```ts
+import { part, video } from "@allyhub/sdk";
+
+export default video({
+  format: "9x16",
+  capture: { grain: {}, vignette: 0.2, soften: 1 },
+  post: { filter: "eq=contrast=1.05:saturation=1.1", lut: "./grade.cube" },
+  motionBlur: { samples: 4 },
+  parts: () => [
+    part({
+      key: "hook",
+      dur: 3,
+      post: { filter: "colortemperature=temperature=4800" },
+    }),
+  ],
+});
+```
+
+## Motion blur
+
+`motionBlur: { samples, shutter? }`: each frame blends `samples` (2 to 16) moments of the graphic layers across `shutter` of the frame's time (over 0, up to 1; default 0.5, a 180° shutter). Footage is not blurred again. `z: "overlay"` layers are not blurred.

package/node_modules/@allyhub-next/audio/dist/at-cut.d.ts

@@ -0,0 +1,52 @@
+/** Decibels of an amplitude (1 is full scale), rounded to 0.1, at least −120. */
+export declare const db: (x: number) => number;
+/** A stretch in seconds. */
+export interface Band {
+    start: number;
+    end: number;
+}
+export interface SilenceOptions {
+    /** Seconds of the first sample (default 0). */
+    t0?: number;
+    /** Silence is under this, dBFS (default −40). */
+    threshold?: number;
+    /** The RMS window, seconds (default 0.01). */
+    window?: number;
+    /** The shortest band, seconds (default 0.03). */
+    minLength?: number;
+}
+/**
+ * Stretches where the sound stays under `threshold` dBFS (RMS over
+ * `window` seconds) for at least `minLength` seconds.
+ */
+export declare function silenceBands(s: Float32Array, rate: number, o?: SilenceOptions): Band[];
+/** The sound at a cut, in dBFS and dB. */
+export interface CutSound {
+    /** RMS over the 10 ms around the cut. */
+    levelDb: number;
+    /** RMS over 20–150 ms before and after the cut. */
+    aroundDb: number;
+    /** The highest sample within 5 ms of the cut. */
+    peakDb: number;
+    /**
+     * The largest step between two samples within 2 ms of the cut, against
+     * the steps 5–150 ms around it (their 99th percentile, at least −60
+     * dBFS): above 0 the cut has a sharper edge than the sound beside it; a
+     * click is a large step in quiet sound. At least −60: in silence a step
+     * means nothing.
+     */
+    jumpDb: number;
+}
+/** The sound at sample `at` of `s`. */
+export declare function soundAtCut(s: Float32Array, rate: number, at: number): CutSound;
+/** Samples as `columns` [min, max] pairs, for drawing a waveform. */
+export declare function waveColumns(s: Float32Array, columns: number): [min: number, max: number][];
+/** The level in dBFS over windows of `window` seconds, each at its middle's time from `t0`. */
+export declare function levelCurve(s: Float32Array, rate: number, o?: {
+    t0?: number;
+    window?: number;
+}): {
+    t: number;
+    db: number;
+}[];
+//# sourceMappingURL=at-cut.d.ts.map

package/node_modules/@allyhub-next/audio/dist/at-cut.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+const p=t=>Math.round(t*1e3)/1e3;export const db=t=>t>1e-6?Math.round(20*Math.log10(t)*10)/10:-120;function f(t,l,o){const n=Math.max(0,l),a=Math.min(t.length,o);if(a<=n)return 0;let s=0;for(let h=n;h<a;h++){const u=t[h]??0;s+=u*u}return Math.sqrt(s/(a-n))}export function silenceBands(t,l,o={}){const n=o.t0??0,a=o.threshold??-40,s=Math.max(1,Math.round((o.window??.01)*l)),h=o.minLength??.03,u=[];let c;const i=e=>{c!==void 0&&(e-c)/l>=h-1e-9&&u.push({start:p(n+c/l),end:p(n+e/l)}),c=void 0};for(let e=0;e<t.length;e+=s){const M=db(f(t,e,e+s))<a;M&&c===void 0?c=e:M||i(e)}return i(t.length),u}export function soundAtCut(t,l,o){const n=r=>Math.round(r/1e3*l),a=db(f(t,o-n(5),o+n(5))),s=f(t,o-n(150),o-n(20)),h=f(t,o+n(20),o+n(150)),u=db(Math.sqrt((s*s+h*h)/2));let c=0;for(let r=Math.max(0,o-n(5));r<Math.min(t.length,o+n(5));r++)c=Math.max(c,Math.abs(t[r]??0));const i=r=>Math.abs((t[r]??0)-(t[r-1]??0));let e=0;for(let r=Math.max(1,o-n(2));r<=Math.min(t.length-1,o+n(2));r++)e=Math.max(e,i(r));const M=[];for(const[r,m]of[[o-n(150),o-n(5)],[o+n(5),o+n(150)]])for(let d=Math.max(1,r);d<Math.min(t.length,m);d++)M.push(i(d));M.sort((r,m)=>r-m);const x=M[Math.floor(M.length*.99)]??0,g=10**(-60/20);return{levelDb:a,aroundDb:u,peakDb:db(c),jumpDb:Math.max(-60,Math.round(20*Math.log10(Math.max(e,1e-9)/Math.max(x,g))*10)/10)}}export function waveColumns(t,l){const o=[],n=t.length/l;for(let a=0;a<l;a++){const s=Math.floor(a*n),h=Math.max(s+1,Math.floor((a+1)*n));let u=0,c=0;for(let i=s;i<Math.min(h,t.length);i++){const e=t[i]??0;e<u&&(u=e),e>c&&(c=e)}o.push([u,c])}return o}export function levelCurve(t,l,o={}){const n=Math.max(1,Math.round((o.window??.01)*l)),a=o.t0??0,s=[];for(let h=0;h<t.length;h+=n)s.push({t:a+(h+n/2)/l,db:db(f(t,h,Math.min(t.length,h+n)))});return s}

package/node_modules/@allyhub-next/audio/dist/decode.d.ts

@@ -0,0 +1,33 @@
+import type { MixPlan, SpeechClip, Stereo } from "./plan.js";
+import type { ClipSource } from "./voice.js";
+/** How a file is decoded for the mix: a take's noise reduction and speed, a stem's filter. */
+export interface DecodeAs {
+    denoise?: number | undefined;
+    speed?: number | undefined;
+    filter?: string | undefined;
+}
+/** One file's decoding, as a key: the same file decoded alike is decoded once. */
+export declare const decodeKey: (file: string, how: DecodeAs) => string;
+/**
+ * A decoded file as the mix asks for it: its two channels, and what of
+ * the asking it was made with (`made.speed`: the take's second s is at s
+ * / speed; a speed not made is resampled, its pitch moved). The player
+ * may have a file only as recorded until the host has made it.
+ */
+export type SoundOf = (file: string, how: DecodeAs) => {
+    src: Stereo;
+    made: DecodeAs;
+} | undefined;
+/** The speech's decoding of a clip: its denoise and its speed (pitch kept). */
+export declare const speechHow: (c: SpeechClip) => DecodeAs;
+/** Every decoding a plan asks for, so a host can make them before mixing. */
+export declare function decodings(plan: MixPlan): {
+    file: string;
+    how: DecodeAs;
+}[];
+/**
+ * Each speech clip's source found: as the host made it (sped already,
+ * `stretched`), or as recorded, to be resampled.
+ */
+export declare function clipSource(sound: SoundOf): (c: SpeechClip) => ClipSource | undefined;
+//# sourceMappingURL=decode.d.ts.map

package/node_modules/@allyhub-next/audio/dist/decode.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+export const decodeKey=(e,i)=>`${e}\0${String(i.denoise??0)}\0${String(i.speed??1)}\0${i.filter??""}`,speechHow=e=>({...e.denoise?{denoise:e.denoise}:{},...e.speed!==void 0&&e.speed!==1?{speed:e.speed}:{}});export function decodings(e){const i=new Map,t=(s,d)=>i.set(decodeKey(s,d),{file:s,how:d});for(const s of e.speech)t(s.file,speechHow(s));for(const s of e.footage)t(s.file,{});e.music&&t(e.music.file,e.music.shape?.filter?{filter:e.music.shape.filter}:{});for(const s of e.sfx)s.file!==void 0&&t(s.file,s.shape?.filter?{filter:s.shape.filter}:{});return[...i.values()]}export function clipSource(e){return i=>{const t=e(i.file,speechHow(i));if(!t)return;const s=i.speed!==void 0&&i.speed!==1?i.speed:void 0;return s!==void 0&&t.made.speed===s?{src:t.src,stretched:s}:{src:t.src}}}