@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/composition/audio/audioMix.js

@@ -1,61 +0,0 @@
-/**
- * AUDIO_MIX — the one SSOT for audio design policy (spec 2026-07-20
- * time-synced-sfx-audio-design §5). Consumed by the director's sfxCompile
- * (placement) AND the evaluation audio floors (grading) so the resolver and the
- * grader can never disagree on what "too dense" means.
- *
- * The content-kind split is the restraint rule: real footage (a transcript with
- * words exists) gets the left column BY CONSTRUCTION — podcasts / talking-head
- * content cannot be opted into generated-tier density except via the explicit
- * `dense` intensity.
- */
-/** Density policy per content kind at each intensity. `off` emits nothing (the
- *  resolver returns [] before consulting this table). `dense` on real footage is
- *  the explicit opt-in that unlocks the generated-tier caps. */
-export const SFX_DENSITY = {
-    "real-footage": {
-        light: { maxHitsPer30s: 3, minSpacingSec: 2.5, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -18 },
-        standard: { maxHitsPer30s: 3, minSpacingSec: 2.5, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -18 },
-        dense: { maxHitsPer30s: 8, minSpacingSec: 1.2, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
-    },
-    generated: {
-        light: { maxHitsPer30s: 4, minSpacingSec: 2.0, perElementTicks: false, maxTicksPerGraphic: 0, hitDb: -14 },
-        standard: { maxHitsPer30s: 8, minSpacingSec: 1.2, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
-        dense: { maxHitsPer30s: 12, minSpacingSec: 0.8, perElementTicks: true, maxTicksPerGraphic: 5, hitDb: -12 },
-    },
-};
-/** Default intensity per content kind when brief/brand express audio intent but
- *  no explicit sfx intensity. */
-export const DEFAULT_SFX_INTENSITY = {
-    "real-footage": "light",
-    generated: "standard",
-};
-/** Speech-collision policy (real footage only — generated content has no speech
- *  unless VO ships): a hit whose transient lands inside a speech word ±150ms is
- *  attenuated a further -6 dB; risers that would UNDERLAP speech are dropped. */
-export const SPEECH_COLLISION = {
-    windowMs: 150,
-    attenuateDb: -6,
-};
-/** Music bed defaults (spec §6): base level, fades, duck. */
-export const MUSIC_BED = {
-    volumeDb: -21,
-    fadeInMs: 500,
-    fadeOutMs: 1200,
-    duck: { duckDb: -12, attackMs: 150, releaseMs: 400 },
-};
-/** Ambience bed defaults (audio-substrate P0). Like a music bed — it LOOPS to
- *  fill the timeline — but the founder ruling is that ambience HOLDS under VO: it
- *  sits at the BOTTOM of the mix (a further −5 dB below the music bed) and is
- *  NEVER duck-stamped (no `duck` key — the absence IS the contract; the render's
- *  duck pass only ever acts on music/vo roles). No beat map, no anchor semantics. */
-export const AMBIENCE_BED = {
-    volumeDb: -26,
-    fadeInMs: 500,
-    fadeOutMs: 1200,
-};
-/** Dedicated audio track ids — separate tracks so the no-overlap invariant never
- *  fights bed-vs-hit, and so eval can address each role's track. */
-export const SFX_TRACK_ID = "track-audio-sfx";
-export const MUSIC_TRACK_ID = "track-audio-music";
-export const AMBIENCE_TRACK_ID = "track-audio-ambience";

package/dist/_members/composition/audio/index.js

@@ -1,5 +0,0 @@
-export * from "./audioMix";
-export * from "./mixStaging";
-export * from "./pack";
-export * from "./musicPack";
-export * from "./palette";

package/dist/_members/composition/audio/mixStaging.js

@@ -1,195 +0,0 @@
-/**
- * ROLE_DEFAULT_GAIN_DB — engine default level per role (dB relative to source),
- * calibrated to the doctrine's ≥6 dB-VO-over-bed rule:
- *
- *   vo        0 dB  — the clarity reference; the mix anchors on speech.
- *   sfx      −6 dB  — punctuation: audible under VO, never masks it.
- *   music   −16 dB  WHEN VO is present anywhere in the composition — a ≥16 dB bed
- *                   keeps speech intelligible with peak headroom (the 1.5 dB
- *                   memoir mush becomes ≥16 dB of separation).
- *            −8 dB  WHEN no VO clip exists — a music-driven montage must not bury
- *                   its own bed, so it sits forward. (This conditional is the
- *                   load-bearing one.)
- *   ambience −22 dB — bottom of the mix; HOLDS under VO (never ducks).
- */
-export const ROLE_DEFAULT_GAIN_DB = {
-    vo: 0,
-    sfx: -6,
-    music: { withVo: -16, withoutVo: -8 },
-    ambience: -22,
-};
-/** The clarity hierarchy, loudest-first. Lower index = should sit higher in the
- *  mix. Used by the inversion advisory. */
-export const ROLE_HIERARCHY = ["vo", "sfx", "music", "ambience"];
-/** Resolve the engine default level (dB) for a role. `music` is conditional on
- *  whether the composition contains any VO. */
-export function roleDefaultGainDb(role, voPresent) {
-    switch (role) {
-        case "vo":
-            return ROLE_DEFAULT_GAIN_DB.vo;
-        case "sfx":
-            return ROLE_DEFAULT_GAIN_DB.sfx;
-        case "music":
-            return voPresent ? ROLE_DEFAULT_GAIN_DB.music.withVo : ROLE_DEFAULT_GAIN_DB.music.withoutVo;
-        case "ambience":
-            return ROLE_DEFAULT_GAIN_DB.ambience;
-    }
-}
-/**
- * True when ANY clip in ANY enabled track declares `audioRole: 'vo'`. VO can be a
- * dedicated audio clip OR a talking-head video clip's own audio, so this scans
- * every track kind (not just audio) — the music-conditional default depends on it.
- */
-export function compositionHasVo(composition) {
-    for (const track of composition.tracks) {
-        if (track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue;
-            const src = c.source;
-            if (src.kind === "media" && src.audioRole === "vo")
-                return true;
-        }
-    }
-    return false;
-}
-/**
- * Effective level (dB relative to source) of a media clip source under the mix
- * policy: authored `volumeDb` wins; else authored linear `volume` converted to
- * dB (`20·log10`); else the role default. A role-less source has no policy level
- * (returns undefined — it stays at unity, out of the hierarchy comparison).
- */
-export function effectiveClipGainDb(source, voPresent) {
-    if (source.volumeDb !== undefined)
-        return source.volumeDb;
-    if (source.volume !== undefined) {
-        // volume 0 → −Infinity dB (silence); never a false "louder-than" in a compare.
-        return source.volume <= 0 ? -Infinity : 20 * Math.log10(source.volume);
-    }
-    if (source.audioRole !== undefined)
-        return roleDefaultGainDb(source.audioRole, voPresent);
-    return undefined;
-}
-/**
- * Authored sfx transients (audio-substrate P0, Phase 4 — the AV-sync floor): every
- * clip whose source is a media clip tagged `audioRole: 'sfx'`, as {clipId, startMs}
- * where startMs is the clip's authored timeline position (`startTime`, seconds → ms).
- * Sorted earliest-first. These are the "expected transients" the delivered-mix onset
- * analysis matches against — an sfx hit that lands nowhere near a detected onset has
- * drifted. PURE (no I/O); the render policy (cap, fail/advisory) lives in the director.
- */
-export function sfxTransients(composition) {
-    const out = [];
-    for (const track of composition.tracks) {
-        if (track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue;
-            const src = c.source;
-            if (src.kind === "media" && src.audioRole === "sfx") {
-                out.push({ clipId: c.id, startMs: Math.round(c.startTime * 1000) });
-            }
-        }
-    }
-    return out.sort((a, b) => a.startMs - b.startMs);
-}
-/**
- * Detect a composition with NO deliberate audio at all — no audio-family
- * track content, no role-tagged media clip, and every video media clip muted
- * (or all silent stills/cards). "Silence is a level" only when someone CHOSE
- * it: a marker of kind "intentional-silence" suppresses the advisory.
- *
- * ADVISORY only — pushed onto the render `warnings[]` channel, never blocks.
- * Craft basis: video-craft-standards cross-cutting rule "audio is decided,
- * never defaulted" (three clean-agent trials shipped silent reels because
- * nothing asked the question — 2026-07-30).
- */
-export function detectNoAudioTrack(composition) {
-    if ((composition.markers ?? []).some((m) => m.kind === "intentional-silence"))
-        return [];
-    for (const track of composition.tracks) {
-        if (track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue;
-            const src = c.source;
-            if (src.kind !== "media")
-                continue;
-            // Any role-tagged clip (music/vo/sfx/ambience) counts as decided audio.
-            if (src.audioRole !== undefined)
-                return [];
-            // An unmuted media clip on an audio track, or an unmuted video clip,
-            // carries source audio into the mix.
-            if (track.kind === "audio" && src.muted !== true)
-                return [];
-            if (track.kind === "video" && src.muted !== true)
-                return [];
-        }
-    }
-    return [
-        "no_audio_track — the composition has no audio: no music/vo/sfx/ambience clip and " +
-            "every media clip is muted. If silence is deliberate, add a marker " +
-            '{kind:"intentional-silence"} to suppress this; otherwise add a bed or ambience ' +
-            "(search_resources kind:sfx, audioRole:\"music\") before the final render.",
-    ];
-}
-/**
- * Detect hierarchy inversions across the ROLES PRESENT in the composition and
- * return one advisory string per offending (higher-role, lower-role) pair. An
- * inversion is a lower-priority role's LOUDEST clip sitting above a
- * higher-priority role's QUIETEST clip (e.g. any music clip above any vo clip).
- *
- * ADVISORY only — the caller pushes these onto the render `warnings[]` channel;
- * they NEVER block a render. Because engine defaults are hierarchy-correct by
- * construction, only AUTHORED levels can trip this.
- */
-export function detectMixHierarchyInversion(composition) {
-    const voPresent = compositionHasVo(composition);
-    // Collect the effective level of every role-tagged media clip, grouped by role.
-    const byRole = new Map();
-    for (const track of composition.tracks) {
-        if (track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue;
-            const src = c.source;
-            if (src.kind !== "media" || src.audioRole === undefined)
-                continue;
-            const effectiveDb = effectiveClipGainDb(src, voPresent);
-            if (effectiveDb === undefined)
-                continue;
-            const list = byRole.get(src.audioRole) ?? [];
-            list.push({ clipId: c.id, role: src.audioRole, effectiveDb });
-            byRole.set(src.audioRole, list);
-        }
-    }
-    const advisories = [];
-    // Walk every ordered (higher, lower) role pair present. rank(higher) < rank(lower).
-    for (let i = 0; i < ROLE_HIERARCHY.length; i++) {
-        const higherRole = ROLE_HIERARCHY[i];
-        const higherClips = byRole.get(higherRole);
-        if (!higherClips || higherClips.length === 0)
-            continue;
-        // Quietest higher-role clip — the ceiling a lower role must stay below.
-        const quietestHigher = higherClips.reduce((a, b) => (b.effectiveDb < a.effectiveDb ? b : a));
-        for (let j = i + 1; j < ROLE_HIERARCHY.length; j++) {
-            const lowerRole = ROLE_HIERARCHY[j];
-            const lowerClips = byRole.get(lowerRole);
-            if (!lowerClips || lowerClips.length === 0)
-                continue;
-            const loudestLower = lowerClips.reduce((a, b) => (b.effectiveDb > a.effectiveDb ? b : a));
-            if (loudestLower.effectiveDb > quietestHigher.effectiveDb) {
-                advisories.push(`mix_hierarchy_inverted: ${lowerRole} clip "${loudestLower.clipId}" ` +
-                    `(${loudestLower.effectiveDb.toFixed(1)} dB) sits above ${higherRole} clip ` +
-                    `"${quietestHigher.clipId}" (${quietestHigher.effectiveDb.toFixed(1)} dB) — ` +
-                    `${higherRole} should lead ${lowerRole} in the mix. Levels are advisory; ` +
-                    `set volumeDb on the clips to override.`);
-            }
-        }
-    }
-    return advisories;
-}

package/dist/_members/composition/audio/musicPack.generated.js

@@ -1,136 +0,0 @@
-export const MUSIC_PACK_VERSION = "v1";
-export const MUSIC_PACK_ENTRIES = [
-    {
-        "bedId": "awake-electronic",
-        "genre": "electronic",
-        "mood": [
-            "energetic",
-            "driving"
-        ],
-        "bpm": 89.1,
-        "bpmMethod": "detected",
-        "durationSec": 57.314,
-        "description": "driving electronic bed, steady pulse — energetic underscore",
-        "attribution": "driving electronic bed, steady pulse — energetic underscore — by cynicmusic (https://opengameart.org/content/awake-megawall-10) — License: Creative Commons 0",
-        "sha256": "85d44a98775e51ed321c968116ddfb044dd6dd18cf13f971a34b1d541258b7de",
-        "source": {
-            "url": "https://opengameart.org/content/awake-megawall-10",
-            "author": "cynicmusic",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "bossa-nova",
-        "genre": "jazz",
-        "mood": [
-            "playful",
-            "jazzy"
-        ],
-        "bpm": 129.2,
-        "bpmMethod": "detected",
-        "durationSec": 59.611,
-        "description": "jazzy bossa-nova bed, syncopated groove — light and cheerful",
-        "attribution": "jazzy bossa-nova bed, syncopated groove — light and cheerful — by Joth (https://opengameart.org/content/bossa-nova) — License: Creative Commons 0",
-        "sha256": "ca311e561e7bb4671579e8f6a765ab823dc7ad00b9c3c458812a879945bd1067",
-        "source": {
-            "url": "https://opengameart.org/content/bossa-nova",
-            "author": "Joth",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "cave-dark",
-        "genre": "ambient",
-        "mood": [
-            "dark",
-            "brooding"
-        ],
-        "bpm": 136,
-        "bpmMethod": "detected",
-        "durationSec": 280,
-        "description": "dark brooding cave ambience — long, atmospheric bed",
-        "attribution": "dark brooding cave ambience — long, atmospheric bed — by Brandon75689 (https://opengameart.org/content/cave-theme) — License: Creative Commons 0",
-        "sha256": "90c9753d8765603ca00e4ed55a52ea5a3648ed03cd334006a5fa4d1e71adec79",
-        "source": {
-            "url": "https://opengameart.org/content/cave-theme",
-            "author": "Brandon75689",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "creepy-forest",
-        "genre": "ambient",
-        "mood": [
-            "eerie",
-            "tense"
-        ],
-        "bpm": 136,
-        "bpmMethod": "detected",
-        "durationSec": 216,
-        "description": "eerie tense forest ambience — unsettling atmospheric bed",
-        "attribution": "eerie tense forest ambience — unsettling atmospheric bed — by Augmentality (Brandon Morris) (https://opengameart.org/content/creepy-forest-f) — License: Creative Commons 0",
-        "sha256": "15f970c6f659dbe2f4c0345e30211e13712ae0c90a6de81ea993c9a4f83dfb35",
-        "source": {
-            "url": "https://opengameart.org/content/creepy-forest-f",
-            "author": "Augmentality (Brandon Morris)",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "crystal-cave-calm",
-        "genre": "ambient",
-        "mood": [
-            "calm",
-            "mysterious"
-        ],
-        "bpm": 99.4,
-        "bpmMethod": "detected",
-        "durationSec": 49.563,
-        "description": "calm crystalline ambient bed, gentle motion",
-        "attribution": "calm crystalline ambient bed, gentle motion — by cynicmusic (https://opengameart.org/content/crystal-cave-song18) — License: Creative Commons 0",
-        "sha256": "927a0a0c3e312ea079e13eb3d7e73889ef0174dc72399413e60f7967386659d4",
-        "source": {
-            "url": "https://opengameart.org/content/crystal-cave-song18",
-            "author": "cynicmusic",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "enchanted-tiki",
-        "genre": "world",
-        "mood": [
-            "playful",
-            "tropical"
-        ],
-        "bpm": 103.4,
-        "bpmMethod": "detected",
-        "durationSec": 117.398,
-        "description": "playful tropical bed, marimba-led — light and warm",
-        "attribution": "playful tropical bed, marimba-led — light and warm — by cynicmusic (https://opengameart.org/content/enchanted-tiki-86) — License: Creative Commons 0",
-        "sha256": "df3da48e199494b83df63bbec6eea4b3e57131c1ab0183bd70fbc13539447c93",
-        "source": {
-            "url": "https://opengameart.org/content/enchanted-tiki-86",
-            "author": "cynicmusic",
-            "license": "CC0"
-        }
-    },
-    {
-        "bedId": "menu-bright",
-        "genre": "electronic",
-        "mood": [
-            "bright",
-            "upbeat"
-        ],
-        "bpm": 117.5,
-        "bpmMethod": "detected",
-        "durationSec": 47.722,
-        "description": "bright upbeat electronic bed — clean, forward energy",
-        "attribution": "bright upbeat electronic bed — clean, forward energy — by mrpoly (https://opengameart.org/content/menu-music) — License: Creative Commons 0",
-        "sha256": "cb7cf40ea0c8a83e280adef0301843e3960427744306737f9a6ebe1760b2302a",
-        "source": {
-            "url": "https://opengameart.org/content/menu-music",
-            "author": "mrpoly",
-            "license": "CC0"
-        }
-    }
-];

package/dist/_members/composition/audio/musicPack.js

@@ -1,36 +0,0 @@
-/**
- * The CueFrame MUSIC-BED pack — a CLOSED, versioned catalog of CC0 music beds
- * (audio-substrate Phase 2). The music-tier twin of the SFX pack (pack.ts): a
- * Map built once from the generated entries; unknown ids fail loud; no runtime
- * search, no network.
- *
- * Bytes live at content-addressed shared R2 keys `packs/music/v1/{bedId}.mp3`
- * (cross-org shared-bytes model, one copy ever); each entry records sha256 +
- * full provenance (source URL, author, license). Entries are written by the
- * curation script (services/scripts/curate-music-pack.mjs), which normalizes
- * every bed to −16 LUFS integrated (ffmpeg loudnorm — the music loudness anchor,
- * NOT the sfx −6 dBFS peak rule) — hand-editing musicPack.generated.ts is a bug.
- *
- * LICENSE: CC0 ONLY — a hard constraint, not a preference (same as the SFX
- * pack). Beds embed into customers' videos that they redistribute and monetize
- * at scale through the API (multi-tenant sublicensing by machine); only CC0
- * survives that. The curation script audits each source's license PAGE and fails
- * loud on anything it cannot verify as CC0.
- */
-import { MUSIC_PACK_ENTRIES, MUSIC_PACK_VERSION } from "./musicPack.generated";
-const registry = new Map(MUSIC_PACK_ENTRIES.map((e) => [e.bedId, e]));
-export { MUSIC_PACK_VERSION, MUSIC_PACK_ENTRIES };
-/** R2 key for a music bed's shared bytes. */
-export function musicPackR2Key(bedId) {
-    return `packs/music/${MUSIC_PACK_VERSION}/${bedId}.mp3`;
-}
-/** Look up a bed — FAIL LOUD on an unknown id (closed registry; a typo'd bedId
- *  must never silently place silence). */
-export function getMusicPackEntry(bedId) {
-    const e = registry.get(bedId);
-    if (!e) {
-        throw new Error(`music-pack: unknown bedId '${bedId}' (pack ${MUSIC_PACK_VERSION}, ${registry.size} beds). ` +
-            `The catalog is closed — beds enter only via the curation script.`);
-    }
-    return e;
-}