rvlib-shipkit 2.5.0 → 2.7.0

package/src/trailer/build.ts

@@ -629,10 +629,11 @@ function shelve(l: Loaded, takes: readonly Take[]): void {
 
 /** the cache trimmed after a stitch, said in one line */
 async function pruneAfter(root: string, say: Say): Promise<void> {
-    const { prune, sayPruned } = await import('./prune.ts')
+    const { pruneIfMoved, sayPruned } = await import('./prune.ts')
     // the cut is written: a prune that fails is said, never the build's failure
     try {
-        for (const line of sayPruned(await prune(root, { dry: false }), false, true)) say(line)
+        const p = await pruneIfMoved(root)
+        for (const line of p === null ? ['cache prune skipped: nothing it reads moved since the last one'] : sayPruned(p, false, true)) say(line)
     } catch (e) {
         say(`WARN the cache prune failed, the cut is written: ${(e as Error).message}`)
     }

package/src/trailer/grammar.ts

@@ -167,11 +167,12 @@ export interface Title {
 export type TitlePlace = 'top' | 'middle' | 'bottom'
 export const placeOf = (ti: Pick<Title, 'place' | 'style'>): TitlePlace => ti.place ?? (ti.style === 'short' ? 'middle' : ti.style === 'progress' ? 'top' : 'bottom')
 
-/** a colour as a line writes it: `#rgb`, `#rrggbb`, or one of the look's (titles.ts resolves it) */
+/** a colour as a line writes it: `#rgb`, `#rrggbb`, `#rrggbbaa`, or one of the look's (titles.ts resolves it) */
 export const LOOK_COLOURS = ['light', 'edge', 'accent'] as const
 
 /** a title's look over its style's: its face (a font file or a Google Fonts family), weight, size in pixels of a frame
- *  1080 tall, fill, and its outline, shadow and glow, each a size in those pixels and a colour */
+ *  1080 tall, fill (a gradient's colours each `colour[@share]`, top to bottom), and its outline, inner stroke, drop,
+ *  shadow (and its fall) and glow, each a size in those pixels and a colour; a logo's layout (LOGO_WORDS) */
 export interface TitleFx {
     font?: string
     weight?: number
@@ -179,10 +180,25 @@ export interface TitleFx {
     color?: string
     gradient?: string[]
     outline?: { px: number; color?: string }
-    shadow?: { px: number; color?: string }
+    inner?: { px: number; color?: string }
+    drop?: { px: number; color?: string }
+    shadow?: { px: number; color?: string; dy?: number }
     glow?: { px: number; color?: string }
+    /** the widest share of the frame's width the word takes */
+    fit?: number
+    /** the subtitle's height to the word's */
+    sub?: number
+    /** the space between the word and its subtitle, a share of the word's height */
+    gap?: number
+    /** the word's middle at this share of the frame's height (default: the whole block's middle at 0.48) */
+    middle?: number
+    /** the soft shade round the logo, its radius a share of the frame's longer side; 0 for none */
+    shade?: number
 }
 
+/** the look words only a logo title reads */
+export const LOGO_WORDS = ['fit', 'sub', 'gap', 'middle', 'shade'] as const
+
 /** how a made sound is made (design call 9): its seed, the voice or engine it is made `by`, its length (`for`), an sfx
  *  trimmed to its first `hit` */
 export interface SoundGen {
@@ -403,8 +419,8 @@ interface Word {
 
 /** a line's words: a quoted run is one word (quoted), `#` outside quotes ends the line. Only double quotes quote, as in
  *  the full language, so a word opening on a single quote is refused: it would reach a command with the quotes inside */
-/** a hex colour at `k` (`#rgb`, `#rrggbb`, then the word's end or a comma): a word, never a comment */
-const colourAt = (line: string, k: number): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6})(?=[\s,"]|$)/i.test(line.slice(k))
+/** a hex colour at `k` (`#rgb`, `#rrggbb`, `#rrggbbaa`, then the word's end, a comma or a gradient place `@`): a word, never a comment */
+const colourAt = (line: string, k: number): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})(?=[\s,"@]|$)/i.test(line.slice(k))
 
 export function tokens(line: string): { words: Word[] } | { error: string } {
     const words: Word[] = []
@@ -511,9 +527,9 @@ const sizeWord = (what: string, w: Word | undefined, lo: number, hi: number): [n
     return [x, y]
 }
 
-/** a colour word: `#rgb`, `#rrggbb`, or the look's light, edge or accent */
+/** a colour word: `#rgb`, `#rrggbb`, `#rrggbbaa` (its last two digits the alpha), or the look's light, edge or accent */
 const colour = (k: string, text: string | undefined): string => {
-    if (!text || !/^(#[0-9a-f]{3}|#[0-9a-f]{6}|light|edge|accent)$/i.test(text)) return bad(`${k} wants a colour: #rgb, #rrggbb, ${LOOK_COLOURS.join(', ')}${text ? `, got ${text}` : ''}`)
+    if (!text || !/^(#[0-9a-f]{3}|#[0-9a-f]{6}|#[0-9a-f]{8}|light|edge|accent)$/i.test(text)) return bad(`${k} wants a colour: #rgb, #rrggbb, #rrggbbaa, ${LOOK_COLOURS.join(', ')}${text ? `, got ${text}` : ''}`)
     return text
 }
 /** `<px>[,<colour>]`: an outline, a shadow or a glow, its size in pixels of a frame 1080 tall */
@@ -524,8 +540,19 @@ const sized = (w: Word | undefined, k: string): { px: number; color?: string } =
     if (!Number.isFinite(px) || px < 0 || px > 300 || more !== undefined) return bad(`${k} wants <px>[,<colour>], its size 0 to 300, got ${w.text}`)
     return { px, ...(c !== undefined ? { color: colour(k, c) } : {}) }
 }
+/** `<px>[,<colour>[,<fall>]]`: a shadow's blur, its colour and how far it falls (default a third of its blur) */
+const shadowWord = (w: Word | undefined, k: string): { px: number; color?: string; dy?: number } => {
+    const [head, ...fall] = w && !w.quoted ? w.text.split(',') : []
+    const wrong = (): never => bad(`${k} wants <px>[,<colour>[,<fall>]], its fall 0 to 300, got ${w!.text}`)
+    if (fall.length > 2) return wrong()
+    const base = sized(w && fall.length === 2 ? { ...w, text: `${head},${fall[0]}` } : w, k)
+    if (fall.length < 2) return base
+    const dy = Number(fall[1])
+    if (!/^\d+(\.\d+)?$/.test(fall[1]!) || dy > 300) return wrong()
+    return { ...base, dy }
+}
 /** a title's look words, in TitleFx */
-const FX_WORDS = ['font', 'weight', 'size', 'color', 'gradient', 'outline', 'shadow', 'glow'] as const
+const FX_WORDS = ['font', 'weight', 'size', 'color', 'gradient', 'outline', 'inner', 'drop', 'shadow', 'glow', ...LOGO_WORDS] as const
 const TITLE_WORDS: Record<string, (w: Word | undefined, k: string) => unknown> = {
     style: (w, k) => word(k, w, /^[a-z][a-z0-9-]*$/),
     at: when,
@@ -544,12 +571,23 @@ const TITLE_WORDS: Record<string, (w: Word | undefined, k: string) => unknown> =
     color: (w, k) => colour(k, w && !w.quoted ? w.text : undefined),
     gradient: (w, k) => {
         const cs = w && !w.quoted ? w.text.split(',') : []
-        if (cs.length < 2 || cs.length > 4) bad(`${k} wants two to four colours, top to bottom: light,accent`)
-        return cs.map((c) => colour(k, c))
+        if (cs.length < 2 || cs.length > 4) bad(`${k} wants two to four colours, top to bottom: light,accent (a colour's place colour@0.6)`)
+        return cs.map((c) => {
+            const [col, at] = c.split('@')
+            if (at !== undefined && !/^(0(\.\d+)?|1(\.0+)?)$/.test(at)) bad(`${k}: a colour's place is a share from 0 to 1, got ${c}`)
+            return at === undefined ? colour(k, col) : `${colour(k, col)}@${at}`
+        })
     },
     outline: sized,
-    shadow: sized,
+    inner: sized,
+    drop: sized,
+    shadow: shadowWord,
     glow: sized,
+    fit: (w, k) => num(k, w, 0.1, 1),
+    sub: (w, k) => num(k, w, 0.05, 1),
+    gap: (w, k) => num(k, w, 0, 1),
+    middle: (w, k) => num(k, w, 0, 1),
+    shade: (w, k) => num(k, w, 0, 2),
 }
 
 /** a title's words, in order, each `+<preset>` in place; `in` and `out` take a move and, when the next word is a
@@ -589,6 +627,11 @@ function readTitleWords(raw: Word[], presets: ReadonlyMap<string, Word[]>, what
 /** a title's look words out of read values */
 const fxOf = (v: Record<string, unknown>): TitleFx => Object.fromEntries(FX_WORDS.filter((k) => v[k] !== undefined).map((k) => [k, v[k]])) as TitleFx
 const builtInStyle = (st: string): st is TitleStyle => (TITLE_STYLES as readonly string[]).includes(st)
+/** a logo word on a title of another style fails: nothing would read it */
+const logoOnly = (style: TitleStyle, fx: TitleFx | undefined): void => {
+    const odd = LOGO_WORDS.filter((w) => fx?.[w] !== undefined)
+    if (style !== 'logo' && odd.length > 0) bad(`title ${odd.join(', ')}: a logo's words, this title is ${style}`)
+}
 
 /** the brand's text styles (`trailer.styles`, each a title's words by name) laid under each title: the defaults of
  *  its built in style, then the brand style it names, then its own words, a later one winning. A brand style names
@@ -621,6 +664,7 @@ export function resolveStyles(t: Pick<Trailer, 'shots'>, styles: Readonly<Record
                 const under = { ...defaults, ...named }
                 ti.style = base as TitleStyle
                 const fx = { ...fxOf(under), ...ti.fx }
+                logoOnly(ti.style, fx)
                 if (Object.keys(fx).length > 0) ti.fx = fx
                 if (under.place && !ti.place) ti.place = under.place as 'top' | 'bottom'
                 if (under.in && !ti.in) ti.in = under.in as Move
@@ -1323,6 +1367,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                         ...(p.out ? { out: p.out as Move } : {}),
                     }
                     const fx = fxOf(p)
+                    if (!ti.named) logoOnly(ti.style, fx)
                     if (Object.keys(fx).length > 0) ti.fx = fx
                     if (ti.knock !== undefined && ti.out) bad('title: knock is its exit, give out or knock, not both')
                     ti.at = landAt(p.at, n, s, (v) => (ti.at = v))

package/src/trailer/look.ts

@@ -8,18 +8,26 @@ export interface TrailerLookInput {
     light?: string
     /** the dark edge under words over footage (default: the ground's edge) */
     edge?: string
+    /** the soft band of shade behind a `line` title's words (default: the edge) */
+    band?: string
     /** the key colour: the caption's dot, a `line` title's `*word*`, the corner chip (default: the palette's accent) */
     accent?: string
-    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) */
-    plate?: { fill?: string; line?: string; ink?: string }
-    /** the corner chip (default: the accent, ink of the palette's bg) */
-    chip?: { fill?: string; ink?: string }
+    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) and the soft drop under it
+     *  and under the chip (default: the edge) */
+    plate?: { fill?: string; line?: string; ink?: string; shadow?: string }
+    /** the corner chip (default: the accent, ink of the palette's bg, an outline a shade darker than its fill) */
+    chip?: { fill?: string; ink?: string; line?: string }
     /** the face: a font file (repo relative, .ttf .otf .woff2) or a family the machine has, and its heavy weight */
     font?: { file?: string; family?: string; weight?: number }
-    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present) */
-    logo?: string
-    /** the words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left out */
-    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string }
+    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present);
+     *  `false`: the word alone */
+    logo?: string | false
+    /** a `logo` title's subtitle: its colour (default: the light) and the colour of its soft glow (default: the edge) */
+    subtitle?: { color?: string; glow?: string }
+    /** the words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left
+     *  out; `band` the shade behind them (default: their edge), `lit` the glow round a progress bar's newest notch
+     *  (default: their accent) */
+    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string; band?: string; lit?: string }
     /** the vertical short's look (a `vertical` cut), each part `false` to leave it out (vertical.ts) */
     vertical?: VerticalLookInput
     /** text styles by name, each a title line's words (`style big font "Bebas Neue" in letters`): a title's `style`
@@ -44,13 +52,15 @@ export interface TrailerLook {
     ground: [string, string]
     light: string
     edge: string
+    band: string
     accent: string
-    plate: { fill: string; line: string; ink: string }
-    chip: { fill: string; ink: string }
+    plate: { fill: string; line: string; ink: string; shadow: string }
+    chip: { fill: string; ink: string; line: string }
     font: { file: string | null; family: string; weight: number }
     logo: string | null
+    subtitle: { color: string; glow: string }
     /** the short's words: their face and colours */
-    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string }
+    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string; band: string; lit: string }
 }
 
 export interface BrandLike {
@@ -108,20 +118,25 @@ export function lookOf(brand: BrandLike | null, webLogo: string | null = null):
     const light = i.light ?? (luminance(p.ink) > 0.45 ? p.ink : '#ffffff')
     const edge = i.edge ?? (luminance(ground[1]) < 0.2 ? ground[1] : darker(p.bg, 0.8))
     const accent = i.accent ?? p.accent
+    const chipFill = i.chip?.fill ?? p.accent
     const sh = i.short ?? {}
+    const shortEdge = sh.edge ?? edge
+    const shortAccent = sh.accent ?? accent
     const shortFont = sh.font ? { file: sh.font.file ?? null, family: sh.font.family ?? (sh.font.file ? 'TrailerShortFace' : font.family), weight: sh.font.weight ?? font.weight } : font
     return {
         ground,
         light,
         edge,
+        band: i.band ?? edge,
         accent,
-        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink },
-        chip: { fill: i.chip?.fill ?? p.accent, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff') },
+        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink, shadow: i.plate?.shadow ?? alpha(edge, 0.4) },
+        chip: { fill: chipFill, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff'), line: i.chip?.line ?? darker(chipFill, 0.15) },
         font: { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 },
-        logo: i.logo ?? webLogo,
-        short: { font: shortFont, light: sh.light ?? light, edge: sh.edge ?? edge, accent: sh.accent ?? accent },
+        logo: i.logo === false ? null : (i.logo ?? webLogo),
+        subtitle: { color: i.subtitle?.color ?? light, glow: i.subtitle?.glow ?? edge },
+        short: { font: shortFont, light: sh.light ?? light, edge: shortEdge, accent: shortAccent, band: sh.band ?? shortEdge, lit: sh.lit ?? shortAccent },
     }
 }
 
 /** the look a short's words wear: the look with the short's face and colours in place */
-export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent })
+export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent, band: look.short.band })

package/src/trailer/prune.ts

@@ -1,7 +1,8 @@
 // the trailer's cache kept small (wiki build/trailer.md, The cache): what the cuts of every trailer folder still use
-// stays, the rest goes. Runs after every stitch and by hand (`sk trailer prune [--dry]`). What a cut uses is named by the
-// build's own key functions; a file younger than an hour is never deleted: another build may be writing or reading it
-import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+// stays, the rest goes. Runs after a stitch when what it reads moved, and by hand (`sk trailer prune [--dry]`). What a
+// cut uses is named by the build's own key functions; a file younger than an hour is never deleted: another build may
+// be writing or reading it
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { basename, join, relative } from 'node:path'
 import { cutFiles, load } from './build.ts'
 import { SCORE, musicCues } from './grammar.ts'
@@ -159,12 +160,10 @@ function filesUnder(dir: string): string[] {
     return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)]))
 }
 
-/** plans every folder's prune, then deletes unless `dry` */
-export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
-    const now = o.now ?? Date.now()
-    const [{ trailerCache }, { viewsToDrop }] = await Promise.all([import('./footage.ts'), import('../review/trailer-desk.ts')])
-    const cache = join(trailerCache(root, 'footage'), '..')
-    const live = await liveSet(root)
+const cacheOf = async (root: string): Promise<string> => join((await import('./footage.ts')).trailerCache(root, 'footage'), '..')
+
+/** each folder's files that go, as of `now`; `now` Infinity names the files only their age keeps too */
+function planOf(cache: string, live: Live, views: readonly string[], now: number): [string, Doomed[]][] {
     const whole = live.broken.length === 0
     // titles/ holds the vertical's drawings too: only a title's and a card's files are the prune's
     const ownTitle = (n: string): boolean => /^(title|card)-[0-9a-f]{16}\./.test(n)
@@ -177,10 +176,58 @@ export async function prune(root: string, o: { dry: boolean; now?: number }): Pr
     ]
     const dead = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name)) : []
     for (const d of dead) plan.push([`${d.name}/ (dead)`, filesUnder(join(cache, d.name)).map(doomed)])
-    plan.push(['trailer-view/', viewsToDrop(root).filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
-    if (!o.dry) {
+    plan.push(['trailer-view/', views.filter((f) => existsSync(f) && now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
+    return plan
+}
+
+/** what the last whole prune read, and when the first file it spared for its age comes of age */
+interface Stamp {
+    key: string
+    until: number
+}
+
+const stampFile = (cache: string): string => join(cache, 'prune.json')
+
+/** what the prune reads that a build can change: every cut's text, every file name in the cache's folders, the views
+ *  to drop. The same key and no spared file of age: the prune would find what it found */
+async function pruneKey(root: string, cache: string): Promise<string> {
+    const [{ cutFiles }, { viewsToDrop }] = await Promise.all([import('./build.ts'), import('../review/trailer-desk.ts')])
+    const h = new Bun.CryptoHasher('sha1')
+    for (const f of cutFiles(root)) h.update(`${f}\0`).update(readFileSync(f)).update('\0')
+    const folders = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory()) : []
+    for (const d of folders.map((e) => e.name).sort()) h.update(`${d}/\0${filesUnder(join(cache, d)).sort().join('\0')}\0`)
+    h.update(viewsToDrop(root).sort().join('\0'))
+    return h.digest('hex')
+}
+
+/** the prune after a build: skipped while nothing it reads moved and no file it spared has come of age */
+export async function pruneIfMoved(root: string, now = Date.now()): Promise<Pruned | null> {
+    const cache = await cacheOf(root)
+    let s: Stamp | null = null
+    try {
+        s = JSON.parse(readFileSync(stampFile(cache), 'utf8')) as Stamp
+    } catch {}
+    if (s !== null && now < s.until && s.key === (await pruneKey(root, cache))) return null
+    return prune(root, { dry: false, now })
+}
+
+/** plans every folder's prune, then deletes unless `dry`; a whole prune writes its stamp */
+export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
+    const now = o.now ?? Date.now()
+    const { viewsToDrop } = await import('../review/trailer-desk.ts')
+    const cache = await cacheOf(root)
+    const live = await liveSet(root)
+    const views = viewsToDrop(root)
+    const plan = planOf(cache, live, views, now)
+    if (!o.dry && existsSync(cache)) {
         for (const [, ds] of plan) for (const d of ds) rmSync(d.file, { force: true })
-        for (const d of dead) rmSync(join(cache, d.name), { recursive: true, force: true })
+        for (const d of readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name))) rmSync(join(cache, d.name), { recursive: true, force: true })
+        rmSync(stampFile(cache), { force: true })
+        if (live.broken.length === 0) {
+            const spared = planOf(cache, live, views, Number.POSITIVE_INFINITY).flatMap(([, ds]) => ds.filter((d) => existsSync(d.file)))
+            const until = Math.min(Number.MAX_SAFE_INTEGER, ...spared.map((d) => statSync(d.file).mtimeMs + RENDER_GRACE_MS))
+            writeFileSync(stampFile(cache), JSON.stringify({ key: await pruneKey(root, cache), until } satisfies Stamp))
+        }
     }
     return {
         freed: plan.map(([folder, ds]) => ({ folder, files: ds.length, bytes: ds.reduce((n, d) => n + (d.linked ? 0 : d.bytes), 0), linked: ds.reduce((n, d) => n + (d.linked ? d.bytes : 0), 0) })),

package/src/trailer/score/dsp.ts

@@ -126,45 +126,105 @@ function staticCurve(c: CompressorDef): { saturate: (x: number) => number; makeu
     return { saturate, makeup: (1 / saturate(1)) ** 0.6 }
 }
 
-/** a stereo compressor in place, 6 ms of lookahead: the gain follows the louder channel, falling at `attack` and
- *  rising at `release`, in dB */
+/** the release a browser compressor takes at 15, 10, 5 and 0 dB from its target, shares of its release time */
+const RELEASE_ZONES = [0.09, 0.16, 0.42, 0.98] as const
+/** a browser compressor sets its envelope's rate once a division of this many frames */
+const DIVISION = 32
+
+/** a stereo compressor in place, as a browser's (its dynamics compressor kernel): 6 ms of lookahead; a detector on the
+ *  louder channel's attenuation that lets go over 2.5 ms; a gain that attacks at a rate set by the deepest attenuation
+ *  it chases and releases faster the more it compresses (a curve through the four release zones); a sine warp on the
+ *  gain, the makeup on top */
 export function compress(l: Float32Array, r: Float32Array, rate: number, c: CompressorDef): void {
     const { saturate, makeup } = staticCurve(c)
-    const n = l.length
-    // the curve sampled in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
+    // the attenuation in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
     const lo = -60
     const step = 0.05
     const table = new Float32Array(Math.ceil((24 - lo) / step) + 2)
     for (let i = 0; i < table.length; i++) {
         const x = lin(lo + i * step)
-        table[i] = dbOf(saturate(x) / x)
+        table[i] = -dbOf(saturate(x) / x)
     }
-    compressRun(l, r, n, Math.round(0.006 * rate), Math.exp(-1 / (Math.max(1e-4, c.attack) * rate)), Math.exp(-1 / (Math.max(1e-4, c.release) * rate)), table, lo, step, makeup)
+    const [y1, y2, y3, y4] = RELEASE_ZONES.map((z) => z * rate * c.release) as [number, number, number, number]
+    // the 4th order polynomial through (0, y1), (1, y2), (2, y3), (3, y4), the browser's own coefficients
+    const poly: Poly = [
+        0.9999999999999998 * y1 + 1.8432219684323923e-16 * y2 - 1.9373394351676423e-16 * y3 + 8.824516011816245e-18 * y4,
+        -1.5788320352845888 * y1 + 2.3305837032074286 * y2 - 0.9141194204840429 * y3 + 0.1623677525612032 * y4,
+        0.5334142869106424 * y1 - 1.272736789213631 * y2 + 0.9258856042207512 * y3 - 0.18656310191776226 * y4,
+        0.08783463138207234 * y1 - 0.1694162967925622 * y2 + 0.08588057951595272 * y3 - 0.00429891410546283 * y4,
+        -0.042416883008123074 * y1 + 0.1115693827987602 * y2 - 0.09764676325265872 * y3 + 0.028494263462021576 * y4,
+    ]
+    compressRun(l, r, { delay: Math.round(0.006 * rate), attack: Math.max(0.001, c.attack) * rate, detectorRelease: 0.0025 * rate, poly, table, lo, step, makeup })
+}
+
+type Poly = [number, number, number, number, number]
+
+interface Kernel {
+    /** frames of lookahead */
+    delay: number
+    /** frames */
+    attack: number
+    detectorRelease: number
+    poly: Poly
+    /** attenuation in dB by input dB, from `lo` a `step` apart */
+    table: Float32Array
+    lo: number
+    step: number
+    makeup: number
 }
 
-function compressRun(l: Float32Array, r: Float32Array, n: number, delay: number, att: number, rel: number, table: Float32Array, lo: number, step: number, makeup: number): void {
-    const dl = new Float32Array(delay)
-    const dr = new Float32Array(delay)
-    let env = 0
+function compressRun(l: Float32Array, r: Float32Array, k: Kernel): void {
+    const n = l.length
+    const dl = new Float32Array(k.delay)
+    const dr = new Float32Array(k.delay)
+    const { table, lo, step } = k
     const last = table.length - 1
-    for (let i = 0; i < n; i++) {
-        const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
-        let target = 0
-        if (x > 1e-3) {
-            const p = (20 * Math.log10(x) - lo) / step
-            const j = Math.min(last - 1, Math.max(0, p | 0))
-            const f = Math.min(1, Math.max(0, p - j))
-            target = table[j]! + (table[j + 1]! - table[j]!) * f
+    const [ka, kb, kc, kd, ke] = k.poly
+    let detector = 0
+    let gain = 1
+    let maxAttackDb = -1
+    for (let d0 = 0; d0 < n; d0 += DIVISION) {
+        // pre warped so the sine warp below lands on the detector's gain
+        const desired = Math.asin(Math.min(1, detector)) / (Math.PI / 2)
+        let envRate: number
+        if (desired > gain) {
+            maxAttackDb = -1
+            let diff = dbOf(gain / desired)
+            if (!Number.isFinite(diff)) diff = -1
+            const x = 0.25 * (Math.min(0, Math.max(-12, diff)) + 12)
+            const frames = ka + kb * x + kc * x * x + kd * x * x * x + ke * x * x * x * x
+            envRate = lin(5 / frames)
+        } else {
+            let diff = desired > 0 ? dbOf(gain / desired) : 1
+            if (!Number.isFinite(diff)) diff = 1
+            if (maxAttackDb === -1 || maxAttackDb < diff) maxAttackDb = diff
+            envRate = 1 - (0.25 / Math.max(0.5, maxAttackDb)) ** (1 / k.attack)
+        }
+        const end = Math.min(n, d0 + DIVISION)
+        for (let i = d0; i < end; i++) {
+            const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
+            let att = 1
+            let attDb = 0
+            if (x > 1e-4) {
+                const p = (20 * Math.log10(x) - lo) / step
+                const j = Math.min(last - 1, Math.max(0, p | 0))
+                const f = Math.min(1, Math.max(0, p - j))
+                attDb = table[j]! + (table[j + 1]! - table[j]!) * f
+                att = lin(-attDb)
+            }
+            const release = lin(Math.max(2, attDb) / k.detectorRelease) - 1
+            detector = Math.min(1, detector + (att - detector) * (att > detector ? release : 1))
+            if (envRate < 1) gain += (desired - gain) * envRate
+            else gain = Math.min(1, gain * envRate)
+            const g = k.makeup * Math.sin((Math.PI / 2) * gain)
+            const at = i % k.delay
+            const yl = dl[at]!
+            const yr = dr[at]!
+            dl[at] = l[i]!
+            dr[at] = r[i]!
+            l[i] = yl * g
+            r[i] = yr * g
         }
-        env = target < env ? target + (env - target) * att : target + (env - target) * rel
-        const g = makeup * 10 ** (env / 20)
-        const k = i % delay
-        const yl = dl[k]!
-        const yr = dr[k]!
-        dl[k] = l[i]!
-        dr[k] = r[i]!
-        l[i] = yl * g
-        r[i] = yr * g
     }
 }
 

package/src/trailer/score/pattern.ts

@@ -3,7 +3,7 @@
 
 /** oscillator families: chiptune roots (pulse, wave, noise) plus the smoother modern ones; `gm` a General MIDI
  *  program the soundfont plays (gm.ts) */
-export type Osc = 'pulse' | 'saw' | 'triangle' | 'sine' | 'wave' | 'noise' | 'gm'
+export type Osc = 'pulse' | 'saw' | 'triangle' | 'square' | 'sine' | 'wave' | 'noise' | 'gm'
 
 export interface InstrumentDef {
     osc: Osc

package/src/trailer/score/synth.ts

@@ -74,6 +74,14 @@ function sawCoefficients(): Coefficients {
     return { real, imag }
 }
 
+/** the browser's own square wave, which a score names by its web audio type; never softened */
+function squareCoefficients(): Coefficients {
+    const real = new Float64Array(HARMONICS + 1)
+    const imag = new Float64Array(HARMONICS + 1)
+    for (let k = 1; k <= HARMONICS; k += 2) imag[k] = 4 / (Math.PI * k)
+    return { real, imag }
+}
+
 function triangleCoefficients(): Coefficients {
     const real = new Float64Array(HARMONICS + 1)
     const imag = new Float64Array(HARMONICS + 1)
@@ -186,6 +194,7 @@ class Waves {
                 : osc === 'saw' ? sawCoefficients()
                 : osc === 'wave' ? waveCoefficients(inst.wave!)
                 : osc === 'triangle' ? triangleCoefficients()
+                : osc === 'square' ? squareCoefficients()
                 : { real: new Float64Array(2), imag: Float64Array.of(0, 1) }
             t = tableOf(c, bandHz(band), tone, this.rate)
             this.tables.set(key, t)
@@ -204,11 +213,21 @@ interface Pitch {
 
 const pitchAt = (p: Pitch, t: number): number => (p.over <= 0 || t >= p.over ? p.to : p.from * (p.to / p.from) ** (Math.max(0, t) / p.over))
 
-/** one oscillator voice added into `buf`: a table read at a moving pitch, its detune and vibrato in cents */
-function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, table: Float32Array, p: Pitch, cents: number, vib: InstrumentDef['vibrato'] | null, gain: number): void {
+/** a browser renders in blocks of this many frames */
+const QUANTUM = 128
+/** an oscillator's frequency before its first automation event: the browser's default */
+const DEFAULT_HZ = 440
+
+/** one oscillator voice added into `buf`: a table read at a moving pitch, its detune and vibrato in cents. `lead` is
+ *  how far into its 128 frame block the note starts: in that first block a browser oscillator reads its frequency from
+ *  the block's start, so it runs at the default 440 Hz for `lead` frames and its pitch curve lags by `lead` frames. That
+ *  sets the phase every later frame carries, and two notes of one pitch that overlap add or cancel by it */
+function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, table: Float32Array, p: Pitch, cents: number, vib: InstrumentDef['vibrato'] | null, gain: number, lead: number): void {
     const LN = Math.LN2 / 1200
     const steady = p.over <= 0 && !vib
     const fixed = (p.to * Math.exp(cents * LN)) / rate
+    const early = (DEFAULT_HZ * Math.exp(cents * LN)) / rate
+    const first = lead > 0 ? QUANTUM - lead : 0
     let phase = Math.max(0, t0) * (p.over <= 0 ? p.to : p.from) * Math.exp(cents * LN)
     phase -= Math.floor(phase)
     for (let i = 0; i < n; i++) {
@@ -216,9 +235,11 @@ function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, t
         const j = x | 0
         const v = table[j]!
         buf[i] = buf[i]! + gain * (v + (table[j + 1]! - v) * (x - j))
+        const at = i < first ? i - lead : i
         let inc = fixed
-        if (!steady) {
-            const t = t0 + i / rate
+        if (at < 0) inc = early
+        else if (!steady) {
+            const t = t0 + at / rate
             let c = cents
             if (vib) {
                 const on = Math.max(0, vib.delay)
@@ -232,15 +253,21 @@ function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, t
     }
 }
 
-/** a noise buffer looped at a moving playback rate, added into `buf` */
-function noiseRun(buf: Float32Array, n: number, t0: number, rate: number, src: Float32Array, p: Pitch): void {
+/** a noise buffer looped at a moving playback rate, added into `buf`. A browser buffer source's playbackRate is k-rate:
+ *  held for each 128 frame block at the block's start. In the block the note starts inside (`lead` frames in) it is the
+ *  default 1; the note's events take hold at the next block, so its sweep starts there and still ends at its own time */
+function noiseRun(buf: Float32Array, n: number, t0: number, rate: number, src: Float32Array, p: Pitch, lead: number): void {
+    const first = (QUANTUM - lead) % QUANTUM
+    const sweep: Pitch = { from: p.from, to: p.to, over: p.over - first / rate }
     let pos = 0
+    let inc = 1
     const len = src.length
     for (let i = 0; i < n; i++) {
+        if (i >= first && (i - first) % QUANTUM === 0) inc = pitchAt(sweep, t0 + (i - first) / rate)
         const j = pos | 0
         const v = src[j % len]!
         buf[i] = buf[i]! + v + (src[(j + 1) % len]! - v) * (pos - j)
-        pos += pitchAt(p, t0 + i / rate)
+        pos += inc
         if (pos >= len) pos -= len
     }
 }
@@ -264,18 +291,20 @@ function playNote(bus: Bus, waves: Waves, inst: InstrumentDef, note: ScheduledNo
     if (peak <= 0) return
     const pts = envPoints(inst.env, note.dur, peak)
     const length = (pts[pts.length - 1]?.[0] ?? note.dur) + 0.02
-    const i0 = Math.max(0, Math.ceil(note.time * rate))
-    const i1 = Math.min(bus.l.length, Math.ceil((note.time + length) * rate))
+    // on its sample frame, as the game rounds a note's time: a hair past one (a sum's float noise) is that frame
+    const start = Math.round(note.time * rate)
+    const i0 = Math.max(0, start)
+    const i1 = Math.min(bus.l.length, Math.ceil((start / rate + length) * rate))
     const n = i1 - i0
     if (n <= 0) return
     if (scratch.buf.length < n) scratch.buf = new Float32Array(n)
     const buf = scratch.buf
     buf.fill(0, 0, n)
-    const t0 = i0 / rate - note.time
+    const t0 = (i0 - start) / rate
     if (inst.osc === 'noise') {
         const r0 = Math.max(0.05, Math.min(8, hz / NOISE_REF_HZ))
         const pitch: Pitch = inst.sweep ? { from: r0, to: Math.max(0.02, r0 * 2 ** (inst.sweep.semis / 12)), over: Math.max(1e-4, inst.sweep.time) } : { from: r0, to: r0, over: 0 }
-        noiseRun(buf, n, t0, rate, inst.noise === 'metal' ? waves.metal : waves.white, pitch)
+        noiseRun(buf, n, t0, rate, inst.noise === 'metal' ? waves.metal : waves.white, pitch, i0 % QUANTUM)
     } else {
         const voices = Math.max(1, Math.min(4, inst.unison ?? (inst.detune ? 2 : 1)))
         const spread = inst.detune ?? 0
@@ -288,7 +317,7 @@ function playNote(bus: Bus, waves: Waves, inst: InstrumentDef, note: ScheduledNo
         const table = waves.table(inst, hz)
         for (let v = 0; v < voices; v++) {
             const cents = voices === 1 ? spread : spread * ((2 * v) / (voices - 1) - 1)
-            oscillatorRun(buf, n, t0, rate, table, pitch, cents, vib, 1 / Math.sqrt(voices))
+            oscillatorRun(buf, n, t0, rate, table, pitch, cents, vib, 1 / Math.sqrt(voices), i0 % QUANTUM)
         }
     }
     applyEnvelope(buf, n, t0, rate, pts)