@catlabtech/webcvt-transcode 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+import { Backend, FormatDescriptor, ConvertOptions, ConvertResult, BackendRegistry, WebcvtError } from '@catlabtech/webcvt-core';
+
+/**
+ * TranscodeBackend — the WebCodecs-first audio transcode backend.
+ *
+ * `canHandle` is two-stage + cached: (1) the static {@link TRANSCODE_MATRIX}
+ * gate rejects off-matrix pairs in O(1) with no probing; (2) both-sided
+ * concrete codec probes (`probeAudioDecoder` for the input, `probeAudioCodec`
+ * for the output) confirm the runtime actually supports the pair — this is what
+ * makes Safari-audio and no-WebCodecs runtimes fall through to ffmpeg-wasm.
+ * Probe results are memoised per session.
+ *
+ * `convert` runs the four-phase pipeline demux → decode → encode → mux, enforces
+ * the input cap first, honours `options.signal`, and closes codecs on exit.
+ */
+
+declare class TranscodeBackend implements Backend {
+    #private;
+    readonly name = "webcodecs-transcode";
+    readonly priority = 0;
+    canHandle(input: FormatDescriptor, output: FormatDescriptor): Promise<boolean>;
+    convert(input: Blob, output: FormatDescriptor, options: ConvertOptions): Promise<ConvertResult>;
+}
+/**
+ * Construct a TranscodeBackend and register it with the given registry (or
+ * core's `defaultRegistry` when omitted). Returns the backend so the caller can
+ * later `registry.unregister('webcodecs-transcode')`. Nothing registers on
+ * import — call this explicitly.
+ */
+declare function registerTranscodeBackend(registry?: BackendRegistry): TranscodeBackend;
+
+/**
+ * Typed error classes for @catlabtech/webcvt-transcode.
+ *
+ * All extend core's {@link WebcvtError} with a `TRANSCODE_`-prefixed code, so
+ * callers can catch by `instanceof` or match on `.code`. Never throw a bare
+ * `Error` from this package.
+ */
+
+/**
+ * Thrown when the requested conversion is not in the transcode backend's
+ * capability set (off-matrix pair, or a codec whose runtime probe failed).
+ * `convert()` should never be reached for an unsupported pair — `canHandle`
+ * gates it — but this guards the defensive path.
+ */
+declare class TranscodeUnsupportedError extends WebcvtError {
+    constructor(from: string, to: string);
+}
+/**
+ * Thrown when the input Blob exceeds the buffer-all input cap. The whole
+ * pipeline is buffer-all today (every serializer takes a complete in-memory
+ * model), so a hard cap protects against OOM.
+ */
+declare class TranscodeInputTooLargeError extends WebcvtError {
+    constructor(size: number, max: number);
+}
+/** Thrown when demuxing the input container fails or yields no audio. */
+declare class TranscodeDemuxError extends WebcvtError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Wraps a decode/encode failure surfaced by codec-webcodecs. */
+declare class TranscodeCodecError extends WebcvtError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when muxing the encoded output container fails. */
+declare class TranscodeMuxError extends WebcvtError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/**
+ * Static v1 capability matrix + codec/bitrate resolution for the audio
+ * transcode paths.
+ *
+ * `canHandle` is two-stage: this frozen matrix is the cheap O(1) first gate
+ * (rejects off-matrix pairs like `→ mp3`/`→ mp4` and every video pair before
+ * any `isConfigSupported` round-trip), and the concrete both-sided codec probe
+ * is the second gate (see backend.ts). See docs/design-notes/transcode.md §D.
+ */
+/** Codec token for a demux/mux side. `'pcm'` = raw PCM (wav), no WebCodecs. */
+type SideCodec = 'pcm' | 'opus' | 'aac' | 'flac' | 'mp3';
+/** Output container family we can mux from scratch. */
+type OutputContainer = 'wav' | 'ogg' | 'webm' | 'aac' | 'flac';
+interface OutputTarget {
+    readonly container: OutputContainer;
+    /** Codec the WebCodecs encoder must produce (`'pcm'` = interleave, no encode). */
+    readonly codec: SideCodec;
+}
+/**
+ * MIME → input codec for the containers this stage can demux. `audio/ogg` is
+ * assumed to carry Opus (Vorbis-in-Ogg decode needs a multi-packet setup
+ * description and is deferred). mp4/m4a/webm/mkv audio-track extraction is
+ * deferred to the video stage (shared demuxers).
+ */
+declare const INPUT_CODECS: Readonly<Record<string, SideCodec>>;
+/**
+ * MIME → output target. `→ mp3` and `→ ogg(vorbis)` are intentionally absent
+ * (no WebCodecs encoder); `→ mp4/m4a` is absent (no from-scratch mp4 muxer yet).
+ */
+declare const OUTPUT_TARGETS: Readonly<Record<string, OutputTarget>>;
+/**
+ * Frozen set of `"${inputMime}|${outputMime}"` keys — the full product of every
+ * decodable input against every muxable output. This is the static gate.
+ */
+declare const TRANSCODE_MATRIX: ReadonlySet<string>;
+/** Build the matrix key for a pair. */
+declare function matrixKey(inputMime: string, outputMime: string): string;
+/** Lookup the input codec for a MIME, or `undefined` if not decodable here. */
+declare function inputCodecFor(mime: string): SideCodec | undefined;
+/** Lookup the output target for a MIME, or `undefined` if not muxable here. */
+declare function outputTargetFor(mime: string): OutputTarget | undefined;
+/** Demuxable container family (its sample/block iterators feed the pipeline). */
+type ContainerFamily = 'mp4' | 'webm' | 'mkv';
+/** WebCodecs video codec token for a demux/mux side. */
+type VideoSideCodec = 'h264' | 'vp9' | 'vp8' | 'av1' | 'hevc';
+/**
+ * Container input MIME → family. Covers the video containers (video/mp4,
+ * video/webm, video/x-matroska) and the audio-only projections that share a
+ * demuxer (audio/mp4 = m4a, audio/webm). A container input can be transcoded
+ * to a video target (its video track) OR have its audio track routed into the
+ * existing audio matrix. Kept out of INPUT_CODECS so `inputCodecFor('video/mp4')`
+ * stays `undefined` (a container is not one audio codec).
+ */
+declare const CONTAINER_INPUTS: Readonly<Record<string, ContainerFamily>>;
+/** Output container family for a video target (VP9 default, VP8 fallback). */
+interface VideoTarget {
+    readonly container: 'webm' | 'mkv';
+}
+/**
+ * Video output MIME → container. `→ mp4` is intentionally absent (no from-scratch
+ * mp4 muxer yet — deferred to a later stage). The encoder codec (VP9 preferred,
+ * VP8 fallback) is resolved at convert time by probing, not fixed here.
+ */
+declare const VIDEO_TARGETS: Readonly<Record<string, VideoTarget>>;
+/**
+ * Assumed audio-track codec per container family, used only by `canHandle`
+ * probing (the true codec is known after demux). mp4 audio is ~always AAC and
+ * webm/mkv audio is ~always Opus. A mismatch (e.g. Vorbis-in-webm) is rejected
+ * at demux — the same optimistic-probe contract the ogg(opus) input already uses.
+ */
+declare const CONTAINER_AUDIO_CODEC: Readonly<Record<ContainerFamily, Exclude<SideCodec, 'pcm'>>>;
+/** Assumed video-track codec per family, for `canHandle` decoder probing. */
+declare const CONTAINER_VIDEO_CODEC: Readonly<Record<ContainerFamily, VideoSideCodec>>;
+/** Lookup the container family for an input MIME, or `undefined`. */
+declare function containerFamilyFor(mime: string): ContainerFamily | undefined;
+/** Lookup the video output target for a MIME, or `undefined`. */
+declare function videoTargetFor(mime: string): VideoTarget | undefined;
+/** Default quality when `ConvertOptions.quality` is omitted (mid-ladder). */
+declare const DEFAULT_QUALITY = 0.7;
+/**
+ * Buffer-all input cap. Every serializer takes a complete in-memory model, so a
+ * hard cap protects against OOM. 256 MiB per the design note's conservative
+ * default; revisit when a streaming muxer exists (decoded PCM expands well
+ * beyond the compressed input size).
+ */
+declare const MAX_INPUT_BYTES: number;
+/**
+ * Map `quality` (0–1) to a codec bitrate in bits/s. The ladder is piecewise so
+ * the default `quality = 0.7` lands exactly on the mid-ladder figure from the
+ * design note (Opus 128 kbps, AAC 128 kbps stereo), with q=0 and q=1 at the
+ * ladder ends. Mono is scaled to ~0.6×. Lossless FLAC returns `undefined`
+ * (bitrate is not applicable).
+ */
+declare function resolveBitrate(codec: SideCodec, quality: number, channels: number): number | undefined;
+/**
+ * Map video geometry + `quality` to a VP9/VP8 bitrate in bits/s. Resolution
+ * drives the base (design note ladder: 720p ≈ 3 Mbps for VP9), scaled ±40% by
+ * quality around the default `0.7`, with VP8 at ≈1.3× VP9. Clamped to a sane
+ * floor so tiny test clips still get a positive bitrate.
+ */
+declare function resolveVideoBitrate(width: number, height: number, quality: number, codec: 'vp9' | 'vp8'): number;
+
+export { CONTAINER_AUDIO_CODEC, CONTAINER_INPUTS, CONTAINER_VIDEO_CODEC, type ContainerFamily, DEFAULT_QUALITY, INPUT_CODECS, MAX_INPUT_BYTES, OUTPUT_TARGETS, type OutputContainer, type OutputTarget, type SideCodec, TRANSCODE_MATRIX, TranscodeBackend, TranscodeCodecError, TranscodeDemuxError, TranscodeInputTooLargeError, TranscodeMuxError, TranscodeUnsupportedError, VIDEO_TARGETS, type VideoSideCodec, type VideoTarget, containerFamilyFor, inputCodecFor, matrixKey, outputTargetFor, registerTranscodeBackend, resolveBitrate, resolveVideoBitrate, videoTargetFor };