@bendyline/squisq 2.11.7 → 2.11.9

package/dist/mediaEdit/index.d.ts

@@ -0,0 +1,467 @@
+import { ah as MediaCut, O as Doc, af as MediaClip, ch as MediaFxOpId, ci as MediaFxChain } from '../Doc-DmElSKmg.js';
+export { cj as MEDIA_EDIT_PARAMS, ck as MEDIA_FX_ORDER, cl as MEDIA_FX_SPECS, ag as MediaCrop, cm as MediaEditParamKey, cn as MediaEditParamValues, ai as MediaEdits, co as MediaFxOp, cp as formatMediaNumber, cq as hasRenderableFx, cr as mediaEditHtmlAttribute, cs as mediaEditValuesFromAttributes, ct as mediaEditValuesFromParams, cu as mediaRenderKey, cv as normalizeMediaCrop, cw as normalizeMediaCuts, cx as parseMediaCrop, cy as parseMediaCuts, cz as parseMediaEdits, cA as parseMediaFx, cB as serializeMediaCrop, cC as serializeMediaCuts, cD as serializeMediaEdits, cE as serializeMediaFx } from '../Doc-DmElSKmg.js';
+import '../types-Be6sBUBx.js';
+
+/**
+ * Source time ↔ played time for a media clip with a trim window and cuts.
+ *
+ * A clip plays its source from `clipStart` to `clipEnd` (the trim window)
+ * with every cut range skipped. "Played time" is seconds since the clip
+ * started playing: 0 at `clipStart`, advancing through the kept ranges back
+ * to back. Everything time-indexed against a source file (narration word
+ * timings, block ranges, a companion clip's cuts) goes through this map, so
+ * one function decides what a cut does to time.
+ *
+ * Pure and dependency-free.
+ */
+
+interface MediaTimeMapInput {
+    /** Source in-point in seconds. Default 0. */
+    clipStart?: number;
+    /** Source out-point in seconds. Default: the source's end (unbounded). */
+    clipEnd?: number;
+    /** Removed source ranges (any order; normalized here). */
+    cuts?: readonly MediaCut[];
+    /** Known source length; caps an unbounded trim window. */
+    sourceDuration?: number;
+}
+interface MediaTimeMap {
+    /** Trim window start (source seconds). */
+    readonly windowStart: number;
+    /** Trim window end (source seconds); `Infinity` when unknown. */
+    readonly windowEnd: number;
+    /** Cuts clamped into the window, normalized. */
+    readonly cuts: readonly MediaCut[];
+    /** True when at least one cut falls inside the window. */
+    readonly hasCuts: boolean;
+    /** Played length; `Infinity` when the window end is unknown. */
+    readonly playedDuration: number;
+    /** The kept source ranges, in order (the last may end at `Infinity`). */
+    keptRanges(): MediaCut[];
+    /** Played time of a source instant, or null outside the window or inside a cut. */
+    sourceToPlayed(sourceSec: number): number | null;
+    /**
+     * Like {@link sourceToPlayed} but total: an instant inside a cut maps to the
+     * cut's boundary, before the window to 0, after it to the played end. Use
+     * for range endpoints (a block that ends inside a cut ends at the cut).
+     */
+    snapSourceToPlayed(sourceSec: number): number;
+    /** Source instant at a played time (clamped into the played range). */
+    playedToSource(playedSec: number): number;
+}
+declare function createMediaTimeMap(input: MediaTimeMapInput): MediaTimeMap;
+
+/**
+ * Render store — where derived (processed) audio lives, and how to find it.
+ *
+ * A signal recipe (`fx`) is rendered into an audio-only file that is
+ * sample-aligned with the source's audio track: same start, same length,
+ * never cut. Renders live in a hidden `.mediaEdits/` folder beside the rest
+ * of the document's media, so they travel with the document (copy, zip, git)
+ * and every surface — player, export, CLI — can reuse them. They are a cache:
+ * the recipe in the markdown is the source of truth, and any render can be
+ * deleted and regenerated.
+ *
+ * Layout (paths relative to the media root a `MediaProvider` resolves):
+ *
+ *   .mediaEdits/<stem>.<key>.<ext>    the rendered audio (webm/Opus or wav)
+ *   .mediaEdits/<stem>.<key>.json     its manifest
+ *
+ * `<key>` is {@link mediaRenderKey}(src, fx), so availability is readable from
+ * a directory listing alone; manifests are read only for staleness and GC.
+ *
+ * Pure and dependency-free.
+ */
+
+/** Folder (under the media root) holding renders and manifests. */
+declare const MEDIA_RENDER_DIR = ".mediaEdits";
+/** Manifest schema version. */
+declare const MEDIA_RENDER_MANIFEST_VERSION = 1;
+/** Renders unreferenced for at least this long are eligible for GC. */
+declare const MEDIA_RENDER_GC_AGE_DAYS = 7;
+interface MediaRenderAnalysis {
+    /** Integrated loudness before the loudness stage, LUFS. */
+    integratedLufs?: number;
+    /** Gain the loudness stage applied, dB. */
+    appliedGainDb?: number;
+    /** Breaths the de-breath stage attenuated. */
+    breathCount?: number;
+}
+interface MediaRenderManifest {
+    version: typeof MEDIA_RENDER_MANIFEST_VERSION;
+    /** The source reference exactly as the document writes it. */
+    src: string;
+    key: string;
+    /** Canonical known-op `fx` the render applied. */
+    fx: string;
+    /** Recipe tokens the rendering engine did not understand (not applied). */
+    ignoredOps: string[];
+    /** Render file path, relative to the media root. */
+    file: string;
+    mimeType: string;
+    /** Source byte size at render time (staleness check), when known. */
+    sourceSize: number | null;
+    /** Source audio duration in seconds at render time, when known. */
+    sourceDuration: number | null;
+    /** Engine identifier, e.g. `squisq-media-edit/1`. */
+    engine: string;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    analysis?: MediaRenderAnalysis;
+}
+/** A render the index found in a listing. */
+interface MediaRenderEntry {
+    key: string;
+    /** Render file path as listed (may carry the media folder prefix). */
+    path: string;
+    /** Manifest path, when a manifest was listed beside it. */
+    manifestPath: string | null;
+    size: number;
+}
+/** Filesystem-safe stem from a source reference's basename (`take.webm` → `take`). */
+declare function mediaRenderStem(src: string): string;
+declare function mediaRenderFilePath(src: string, key: string, extension: string): string;
+declare function mediaRenderManifestPath(src: string, key: string): string;
+interface ParsedMediaRenderPath {
+    stem: string;
+    key: string;
+    extension: string;
+    isManifest: boolean;
+}
+/**
+ * Recognize a render or manifest path, with or without a leading media
+ * folder (`notes_files/.mediaEdits/take.1a2b3c4d5e6f.webm`).
+ */
+declare function parseMediaRenderPath(path: string): ParsedMediaRenderPath | null;
+declare function isMediaRenderPath(path: string): boolean;
+/**
+ * Index a media listing by render key. Entries that are not renders are
+ * ignored; a render whose manifest is missing is still indexed (it plays),
+ * with `manifestPath: null`.
+ */
+declare function buildMediaRenderIndex(entries: ReadonlyArray<{
+    name: string;
+    size: number;
+}>): Map<string, MediaRenderEntry>;
+/** Validate manifest JSON; null when malformed or from an unknown version. */
+declare function parseMediaRenderManifest(text: string): MediaRenderManifest | null;
+declare function serializeMediaRenderManifest(manifest: MediaRenderManifest): string;
+/**
+ * Why a render no longer matches its source, or null when it is current.
+ *
+ * - `source-changed` — the source file's size differs from render time
+ *   (a re-recorded take under the same name).
+ * - `engine-upgraded` — the render skipped ops the current engine now knows,
+ *   so re-rendering would apply them.
+ */
+declare function mediaRenderStaleness(manifest: MediaRenderManifest, current: {
+    sourceSize?: number | null;
+    knownOps?: readonly MediaFxOpId[];
+}): 'source-changed' | 'engine-upgraded' | null;
+/** Every media clip in a doc (block-anchored and document-anchored). */
+declare function collectDocMediaClips(doc: Doc): MediaClip[];
+/** The render key a clip needs, or null when its recipe renders nothing. */
+declare function mediaClipRenderKey(clip: MediaClip): string | null;
+/** Render keys referenced by the doc's current recipes. */
+declare function referencedMediaRenderKeys(doc: Doc): Set<string>;
+/** Render key for a raw `src` + `fx` string pair (for callers holding strings). */
+declare function mediaRenderKeyFor(src: string, fx: string | undefined): string | null;
+/**
+ * Paths eligible for garbage collection: renders (and their manifests) whose
+ * key no current recipe references and whose manifest is older than
+ * `olderThanDays`. A render without a manifest has no age, so it is collected
+ * only once unreferenced — it cannot be the cache of a pending undo, because
+ * every render this engine writes carries a manifest.
+ */
+declare function selectMediaRendersForGc(index: ReadonlyMap<string, MediaRenderEntry>, referencedKeys: ReadonlySet<string>, manifests: ReadonlyMap<string, MediaRenderManifest>, now?: Date, olderThanDays?: number): string[];
+
+/**
+ * Breath detection for spoken-word recordings.
+ *
+ * A breath is unvoiced, noise-like energy that sits in a pause: quieter than
+ * speech, louder than the room, lasting roughly 0.12–1 s, and — unlike an
+ * unvoiced consonant (s, f, sh, h) — not wedged tightly between voiced frames.
+ * Detection runs on 10 ms frames:
+ *
+ * - `rmsDb`     full-band level.
+ * - `voicing`   peak normalized autocorrelation in the 70–400 Hz pitch range,
+ *               on a low-passed, decimated copy (cheap enough for long takes).
+ * - `zcr`       zero-crossing rate; sibilants cross far more often than breaths.
+ *
+ * Levels are relative to the take itself (a speech level from voiced frames
+ * and a noise floor from the quietest frames), so the detector adapts to mic
+ * gain. The result is attenuation regions — the chain turns them into a gain
+ * envelope and never deletes audio, so timing is untouched.
+ */
+interface BreathFrame {
+    /** Frame center, seconds. */
+    t: number;
+    rmsDb: number;
+    /** 0 (noise) … 1 (strongly periodic). */
+    voicing: number;
+    zcr: number;
+}
+interface BreathRegion {
+    start: number;
+    end: number;
+}
+interface BreathAnalyzer {
+    /** Feed mono samples (any block size). */
+    push(mono: Float32Array): void;
+    /** Frames analyzed so far. */
+    frames(): BreathFrame[];
+}
+declare function createBreathAnalyzer(sampleRate: number): BreathAnalyzer;
+interface BreathDetectOptions {
+    /** 0 (only obvious breaths) … 1 (aggressive). Default 0.5. */
+    sensitivity?: number;
+    /** Shortest breath, seconds. Default 0.12. */
+    minDurationSec?: number;
+    /** Longest breath, seconds. Default 1.0. */
+    maxDurationSec?: number;
+}
+/** Find breath regions in analyzed frames. */
+declare function detectBreaths(frames: readonly BreathFrame[], options?: BreathDetectOptions): BreathRegion[];
+/**
+ * Gain at time `t` for attenuating `regions` by `reductionDb` (≤ 0), ramping
+ * over `rampSec` INSIDE each region so surrounding speech is never touched.
+ */
+declare function breathGainAt(regions: readonly BreathRegion[], reductionDb: number, t: number, rampSec?: number): number;
+/** Multiply a block starting at `startSec` by the breath envelope, in place. */
+declare function applyBreathEnvelope(channels: readonly Float32Array[], sampleRate: number, startSec: number, regions: readonly BreathRegion[], reductionDb: number): void;
+
+/**
+ * Denoiser seam. Core defines the contract; engines (an RNNoise WASM build,
+ * later possibly DeepFilterNet) live with the renderer, which injects a
+ * factory. Keeping the model out of core keeps core dependency-free and lets
+ * each surface ship the engine as a bundled asset.
+ */
+interface Denoiser {
+    /** Samples per frame the model consumes (RNNoise: 480 at 48 kHz). */
+    readonly frameSize: number;
+    /** Sample rate the model runs at. The chain feeds exactly this rate. */
+    readonly sampleRate: number;
+    /** Samples by which the model's output lags its input (beyond frame buffering). */
+    readonly latency: number;
+    /** Denoise one frame in place. Samples are floats in ±1. */
+    processFrame(frame: Float32Array): void;
+    dispose(): void;
+}
+type DenoiserFactory = () => Promise<Denoiser>;
+/**
+ * Streaming wrapper for one channel: accepts any block size, returns a block
+ * of the same size, delayed by {@link DenoiseStage.latency}. `strength`
+ * blends the denoised signal with the equally delayed dry signal (RNNoise has
+ * no strength control of its own), so partial settings never comb-filter.
+ */
+interface DenoiseStage {
+    readonly latency: number;
+    process(block: Float32Array): Float32Array;
+    dispose(): void;
+}
+declare function createDenoiseStage(denoiser: Denoiser, strength: number): DenoiseStage;
+
+/**
+ * The media-edit signal chain: high-pass → denoise → de-breath → loudness
+ * (+ true-peak limiter), in that fixed order.
+ *
+ * Two passes over the source, so memory stays bounded for long takes:
+ *
+ * 1. **Analyze** — run high-pass + denoise, collect breath features and
+ *    K-weighted loudness per 100 ms step. Breaths are detected over the whole
+ *    take (levels are relative to it), and the loudness the output WILL have
+ *    after breath attenuation is predicted by re-weighting each step by the
+ *    envelope's mean square, so no second analysis pass is needed.
+ * 2. **Render** — run high-pass + denoise again (deterministic), apply the
+ *    breath envelope and the loudness gain, limit, write.
+ *
+ * Every stage's latency is compensated: output sample n is source sample n,
+ * and the output is exactly as long as the input. That is the render
+ * contract (renders are sample-aligned with the source), and it is what lets
+ * cuts and trims apply identically to picture and processed sound.
+ *
+ * Pure: the source, the denoiser, and the sink are injected.
+ */
+
+/** The rate the chain runs at (RNNoise's native rate). Sources are resampled to it. */
+declare const MEDIA_FX_SAMPLE_RATE = 48000;
+/** Engine identifier recorded in render manifests. */
+declare const MEDIA_FX_ENGINE = "squisq-media-edit/1";
+/** True-peak ceiling after the loudness stage, dBTP. */
+declare const MEDIA_FX_TRUE_PEAK_CEILING_DB = -1;
+interface MediaFxSource {
+    /** Must equal {@link MEDIA_FX_SAMPLE_RATE}; the engine resamples first. */
+    sampleRate: number;
+    channels: number;
+    /** A fresh stream of the whole source, as per-channel blocks. Called once per pass. */
+    open(): AsyncIterable<Float32Array[]>;
+    /** Total frames, when known (for progress). */
+    frames?: number;
+}
+interface MediaFxAnalysis {
+    /** Integrated loudness entering the loudness stage (after breath attenuation), LUFS. */
+    integratedLufs: number | null;
+    /** Gain the loudness stage applies, dB. */
+    loudnessGainDb: number;
+    /** Breath regions in take seconds. */
+    breaths: BreathRegion[];
+}
+interface MediaFxOptions {
+    fx: MediaFxChain;
+    source: MediaFxSource;
+    /** Required for `denoise`; without it the op is skipped and reported in `ignoredOps`. */
+    denoiser?: DenoiserFactory;
+    /** Take time (s) of the source's first sample — nonzero for region previews. */
+    startSec?: number;
+    onProgress?: (fraction: number) => void;
+    signal?: AbortSignal;
+}
+interface MediaFxRenderOptions extends MediaFxOptions {
+    write: (block: Float32Array[]) => void | Promise<void>;
+    /** Whole-take analysis to reuse (region previews); skips the analysis pass. */
+    analysis?: MediaFxAnalysis;
+}
+interface MediaFxRenderResult {
+    analysis: MediaFxAnalysis;
+    /** Frames written (always the source length). */
+    frames: number;
+    /** Recipe tokens not applied (unknown ops, or denoise with no denoiser). */
+    ignoredOps: string[];
+    /** Smallest limiter gain (1 = the limiter never engaged). */
+    limiterMinGain: number;
+    /**
+     * Integrated loudness of what was written, when the recipe has a loudness
+     * target. Limiting can pull it below the target; callers may re-render with
+     * a corrected gain (see {@link correctedLoudnessAnalysis}).
+     */
+    outputLufs: number | null;
+}
+/** Analysis pass only: breaths and the loudness gain a render would apply. */
+declare function analyzeMediaFx(options: MediaFxOptions): Promise<MediaFxAnalysis>;
+/** Render the chain: analyze (unless given), then process and write the whole source. */
+declare function renderMediaFx(options: MediaFxRenderOptions): Promise<MediaFxRenderResult>;
+/** Largest deviation from the loudness target accepted without a corrective pass, LU. */
+declare const MEDIA_FX_LOUDNESS_TOLERANCE = 0.5;
+/**
+ * When a render missed its loudness target by more than the tolerance (the
+ * limiter shaved peaks after the gain was chosen), the analysis to re-render
+ * with: the same breaths, gain nudged by the miss. Null when no correction is
+ * needed or possible.
+ */
+declare function correctedLoudnessAnalysis(fx: MediaFxChain, result: MediaFxRenderResult): MediaFxAnalysis | null;
+
+/**
+ * Streaming sample-rate conversion (windowed sinc, arbitrary ratio).
+ *
+ * The chain runs at 48 kHz (the denoiser's rate); sources recorded by
+ * MediaRecorder already are, but MP3/M4A imports are often 44.1 kHz. The
+ * kernel is symmetric, so output sample j is exactly time j / outRate — the
+ * conversion adds no delay, which the time-aligned render contract requires.
+ * A Blackman-windowed sinc, tabulated and linearly interpolated, low-passed
+ * at the lower Nyquist when downsampling.
+ */
+interface Resampler {
+    readonly inRate: number;
+    readonly outRate: number;
+    /** Convert a block; returns however many output samples are now determined. */
+    process(input: Float32Array): Float32Array;
+    /** Emit the remaining output (call once, after the last block). */
+    flush(): Float32Array;
+}
+declare function createResampler(inRate: number, outRate: number, halfTaps?: number): Resampler;
+
+/**
+ * Integrated loudness per ITU-R BS.1770-4 (the measurement EBU R128 uses).
+ *
+ * Each channel is K-weighted (a +4 dB high shelf, then an RLB high-pass),
+ * mean-square energy is taken over 400 ms blocks overlapping by 75 %, and
+ * blocks are gated twice: absolutely at −70 LUFS, then relatively at 10 LU
+ * below the absolute-gated loudness. Streaming: energy accumulates per 100 ms
+ * step, so memory is ten numbers per second regardless of signal length.
+ *
+ * The K-weighting filters are derived per sample rate and reproduce the
+ * standard's 48 kHz coefficients, so any sample rate measures correctly.
+ */
+interface LoudnessMeter {
+    /** Feed one block of per-channel samples (equal lengths). */
+    push(channels: readonly Float32Array[]): void;
+    /**
+     * Per-100 ms-step mean-square sums across channels (K-weighted), for
+     * callers that re-weight steps (e.g. to predict the effect of a gain
+     * envelope without re-running the signal). Complete steps only.
+     */
+    stepPowers(): readonly number[];
+    /** Integrated loudness in LUFS so far; −Infinity for silence or too-short input. */
+    integrated(): number;
+}
+declare function createLoudnessMeter(sampleRate: number, channelCount: number): LoudnessMeter;
+/**
+ * Gated integrated loudness from per-100 ms-step mean-square sums (as
+ * {@link LoudnessMeter.stepPowers} produces). Exposed so a caller can rescale
+ * steps — e.g. by a gain envelope's mean square per step — and re-measure.
+ */
+declare function integratedLoudnessFromSteps(steps: readonly number[]): number;
+
+/**
+ * Look-ahead true-peak limiter (streaming, multi-channel, linked).
+ *
+ * Peaks are estimated between samples by 4× polyphase windowed-sinc
+ * interpolation, so the ceiling holds for the reconstructed waveform, not
+ * just the stored samples. The gain needed at each instant is the sliding
+ * minimum of `ceiling / peak` over the next `lookahead` samples, box-smoothed
+ * over the same length — every smoothing window that averages into sample
+ * `t` also saw `t`'s own requirement, so the smoothed gain never exceeds it.
+ * A one-pole release then lets gain recover slowly. The signal is delayed by
+ * the look-ahead; {@link Limiter.flush} drains the tail.
+ */
+interface LimiterOptions {
+    sampleRate: number;
+    channels: number;
+    /** Ceiling in dBTP. Default −1. */
+    ceilingDb?: number;
+    /** Look-ahead in ms. Default 5. */
+    lookaheadMs?: number;
+    /** Release time constant in ms. Default 80. */
+    releaseMs?: number;
+}
+interface Limiter {
+    /** Delay the limiter adds, in samples. */
+    readonly latency: number;
+    /** Process a block; returns the (delayed) limited output of the same length. */
+    process(channels: readonly Float32Array[]): Float32Array[];
+    /** Drain the delayed tail (`latency` samples per channel). */
+    flush(): Float32Array[];
+    /** Smallest gain applied so far (1 = never limited). */
+    minGain(): number;
+}
+declare function createLimiter(options: LimiterOptions): Limiter;
+
+/**
+ * Pause tightening: find long silences in a take and propose cuts that shorten
+ * each to a natural length.
+ *
+ * Works on the breath analyzer's 10 ms frames. A frame is quiet when it is
+ * unvoiced and close to the take's noise floor; anything louder — speech,
+ * consonants, and breaths — is activity and is never cut, so a cut never lands
+ * in the middle of a sound. Each quiet run longer than `maxPauseSec` keeps
+ * `keepSec` of silence, split evenly around the cut, and loses the middle.
+ * Cuts are in source seconds, ready for a `cuts=` recipe.
+ */
+
+interface PauseTightenOptions {
+    /** Pauses longer than this are shortened. Default 0.8 s. */
+    maxPauseSec?: number;
+    /** Silence left in place of a shortened pause. Default 0.4 s. */
+    keepSec?: number;
+    /** Shorter cuts are not worth a seam. Default 0.25 s. */
+    minCutSec?: number;
+}
+declare const PAUSE_TIGHTEN_DEFAULTS: Readonly<{
+    maxPauseSec: 0.8;
+    keepSec: 0.4;
+    minCutSec: 0.25;
+}>;
+/** Cuts that shorten every long pause in the take. */
+declare function detectPauseCuts(frames: readonly BreathFrame[], options?: PauseTightenOptions): MediaCut[];
+
+export { type BreathAnalyzer, type BreathDetectOptions, type BreathFrame, type BreathRegion, type DenoiseStage, type Denoiser, type DenoiserFactory, type Limiter, type LimiterOptions, type LoudnessMeter, MEDIA_FX_ENGINE, MEDIA_FX_LOUDNESS_TOLERANCE, MEDIA_FX_SAMPLE_RATE, MEDIA_FX_TRUE_PEAK_CEILING_DB, MEDIA_RENDER_DIR, MEDIA_RENDER_GC_AGE_DAYS, MEDIA_RENDER_MANIFEST_VERSION, MediaCut, type MediaFxAnalysis, MediaFxChain, MediaFxOpId, type MediaFxOptions, type MediaFxRenderOptions, type MediaFxRenderResult, type MediaFxSource, type MediaRenderAnalysis, type MediaRenderEntry, type MediaRenderManifest, type MediaTimeMap, type MediaTimeMapInput, PAUSE_TIGHTEN_DEFAULTS, type ParsedMediaRenderPath, type PauseTightenOptions, type Resampler, analyzeMediaFx, applyBreathEnvelope, breathGainAt, buildMediaRenderIndex, collectDocMediaClips, correctedLoudnessAnalysis, createBreathAnalyzer, createDenoiseStage, createLimiter, createLoudnessMeter, createMediaTimeMap, createResampler, detectBreaths, detectPauseCuts, integratedLoudnessFromSteps, isMediaRenderPath, mediaClipRenderKey, mediaRenderFilePath, mediaRenderKeyFor, mediaRenderManifestPath, mediaRenderStaleness, mediaRenderStem, parseMediaRenderManifest, parseMediaRenderPath, referencedMediaRenderKeys, renderMediaFx, selectMediaRendersForGc, serializeMediaRenderManifest };