@wenathlan/saddle 2.0.154 → 2.0.159

package/dist/media.d.ts

@@ -1,343 +0,0 @@
-/**
- * media.ts — media pipeline and transcode domain for saddle v6.
- *
- * the module absorbs the media-facing halves of the pool
- * pipelinememorypassage.ts (saddle v6 orchestrator) and
- * src_pipeline_memory_passage.ts (saddle v5 mttg pipeline) that were
- * still unique after the v3 consolidation:
- * - the 24-stage GPU-accelerated transcode pipeline as a pure catalog
- *   plus an executing pipeline (stage ordering, skip rules, fail-fast,
- *   abort, chunked batch concurrency, stage-count invariant 24)
- * - ffmpeg 7.1 NVENC Blackwell command synthesis: presets p1-p7, rc
- *   vbr_hq with cq 23, multipass 2, b_ref_mode 2 (b-frames as
- *   reference), temporal aq with rc-lookahead 32, bwdif_cuda,
- *   scale_cuda super, tonemap_cuda hable/bt2390 with colorspace_cuda
- *   bt2020->bt709, av1 tier high
- * - the createoptimal encoder policy of the pool encoding optimization
- *   manager: AV1 at 4K+ forces the Blackwell dual NVENC path, h264
- *   ultra-low-latency prefers QuickSync, plus the preset recommender
- *   (ultra low latency p1, low latency p2, live p3, vod av1 p5, vod
- *   hevc p6, default p4) and the per-gpu instance recommender
- * - the passage secure channel contract: transport vsock+virtio-serial,
- *   ed25519 signatures over chacha20-poly1305 sealed frames, MTU
- *   65536, 10000 Mbps rate limit, 256 concurrent streams, 150 us
- *   latency target
- * - the ~30 transcode mode taxonomy of the library-first surface
- *
- * the memory-modularizer half of the same pool files (zram, hugepages,
- * CXL type-3 tiering, CCD-aware vCPU pinning) is already absorbed in
- * virtualmemory.ts (memorymodularizer) and is intentionally not
- * duplicated here; the pipeline consumes a plan digest only.
- *
- * provenance: pool:pipelinememorypassage.ts [S6 v6, 24 stages],
- * pool:src_pipeline_memory_passage.ts [V5 src_mttg_pipeline ordering],
- * pool:mttg.config transcode section (ffmpeg 7.1.1, nvenc sdk 13.0.19),
- * pool:src_virtualization_core.cpp create_optimal (encoder policy).
- *
- * rules: lowercase identifiers, english jsdoc third person, no emoji,
- * try/catch catcher on every fallible path, node:* built-ins first,
- * zero runtime dependencies, `satisfies`/`#private` throughout, no
- * filesystem or process coupling (pure library).
- */
-/**
- * frozen media toolchain anchors. the pool registry pinned node 22.12.3
- * / ts 5.6.3 / qemu 9.1.2 which the v3 pin patch superseded; the media
- * specific values (ffmpeg release line, NVENC SDK, CUDA floor, Blackwell
- * driver) are preserved verbatim from the pool registry.
- */
-export declare const mediaversions: {
-    readonly date: '2026-08-22';
-    readonly ffmpeg: '7.1.1';
-    readonly ffmpegNote: '7.1 released 2024-09-30; 7.1.1 is the 2026-08-22 stable';
-    readonly nvencSdk: '13.0.19';
-    readonly nvencGeneration: 9;
-    readonly nvdecGeneration: 6;
-    readonly cuda: '12.8';
-    readonly cudaNote: 'Blackwell GB202 requires >= 12.8; pool registry cited 12.8.93 with an early 13.0.48 alt';
-    readonly driver: '580.82.07';
-    readonly driverNote: 'production branch for Blackwell + NVENC SDK 13.0; repo also carries 570.144 vgpu-manual anchors';
-    readonly stages: 24;
-    readonly modes: 30;
-};
-/** media pipeline failure envelope with stage and recoverability. */
-export declare class mediapipelineerror extends Error {
-    readonly code: string;
-    readonly stage?: string;
-    readonly recoverable: boolean;
-    readonly traceid: string;
-    constructor(params: {
-        code: string;
-        message: string;
-        stage?: string;
-        recoverable?: boolean;
-    });
-}
-/**
- * NVENC preset taxonomy of the Blackwell SDK: p1 is fastest, p7 is the
- * highest-quality two-pass point and p4 is the balanced 2026 default.
- */
-export type nvencpreset = 'p1' | 'p2' | 'p3' | 'p4' | 'p5' | 'p6' | 'p7';
-/** ordered preset ladder from fastest to highest quality. */
-export declare const nvencpresetladder: readonly nvencpreset[];
-/** per-preset character used by the ffmpeg builder and the recommender. */
-export declare const nvencpresets: readonly {
-    readonly preset: nvencpreset;
-    readonly speed: number;
-    readonly multipass: 'disabled' | 'qres' | 'fullres';
-    readonly use: string;
-}[];
-/** resolves one preset descriptor or undefined when out of ladder. */
-export declare function getnvencpreset(preset: nvencpreset): {
-    readonly preset: nvencpreset;
-    readonly speed: number;
-    readonly multipass: 'disabled' | 'qres' | 'fullres';
-    readonly use: string;
-};
-/**
- * the transcode mode taxonomy: 30 modes spanning codec conversion,
- * HDR tone mapping, scaling, denoise, subtitle burn, VMAF targeting,
- * rate-control strategies and packaging.
- */
-export type transcodemode = 'hevc_to_av1_b200' | 'avc_to_hevc_blackwell' | 'av1_to_hevc_hdr' | 'hevc_hdr_to_av1_sdr_tonemap' | 'av1_8k_to_4k_blackwell' | '4k_to_1080p_nvenc' | '4k_to_720p_mobile' | 'dash_hls_packaging' | 'remux_fast' | 'audio_only_aac_opus' | 'hdr10plus_dolbyvision_passthrough' | 'tonemap_hable_cuda' | 'tonemap_mobius_cuda' | 'tonemap_reinhard_cuda' | 'deinterlace_bwdif_cuda' | 'denoise_hqdn3d_cuda' | 'scale_npp_bicubic' | 'scale_npp_lanczos' | 'subburn_ass_cuda' | 'thumbnail_vmaf' | 'vmaf_target_95' | 'vmaf_target_93' | 'vmaf_target_90' | 'cqp_high_quality' | 'cbr_low_latency' | 'vbr_hq_2pass' | 'll_hq_temporal_filter' | 'fastdecode_fmp4' | 'prores_to_av1_archive' | 'av1_hdr10_to_sdr';
-/** one catalog row: mode, family and the pipeline stages it stresses. */
-export interface transcodemodeentry {
-    readonly mode: transcodemode;
-    readonly family: 'codec-conversion' | 'hdr-tonemap' | 'scale' | 'filters' | 'audio' | 'quality-metrics' | 'rate-control' | 'packaging';
-    readonly note: string;
-}
-/** the 30-mode catalog in taxonomy order. */
-export declare const transcodemodecatalog: readonly transcodemodeentry[];
-/** counts the catalog and asserts the 30-mode library-first surface. */
-export declare function transcodemodecount(): number;
-/** ffprobe 7.1 style inspection of one input. */
-export interface mediaprobe {
-    readonly durationsec: number;
-    readonly video?: {
-        readonly codec: 'h264' | 'hevc' | 'av1' | 'prores' | 'vp9';
-        readonly width: number;
-        readonly height: number;
-        readonly fps: number;
-        readonly bitdepth: 8 | 10 | 12;
-        readonly hdr: boolean;
-        readonly interlaced: boolean;
-        readonly hdr10plus?: boolean;
-        readonly dolbyvision?: boolean;
-    };
-    readonly audio: ReadonlyArray<{
-        codec: string;
-        samplerate: number;
-        channels: number;
-    }>;
-    readonly estimatedworkingsetmb: number;
-}
-/** the requested output rendering of one job. */
-export interface outputprofile {
-    readonly videocodec: 'h264' | 'hevc' | 'av1';
-    readonly audiocodec: 'aac' | 'opus' | 'ac3';
-    readonly resolution: {
-        readonly w: number;
-        readonly h: number;
-    };
-    readonly bitratekbps: number;
-    readonly preset: nvencpreset;
-    readonly tonemap: boolean;
-    readonly vmaftarget?: number;
-    readonly bframes?: number;
-    readonly gopsec?: number;
-}
-/** one queued transcode job; MTTG priority 0..3 maps to QoS classes. */
-export interface mediajob {
-    readonly id: string;
-    readonly inputpath: string;
-    readonly outputpath: string;
-    readonly mode: transcodemode;
-    readonly outputprofile: outputprofile;
-    readonly priority: 0 | 1 | 2 | 3;
-    readonly metadata?: {
-        readonly subtitlepath?: string;
-        readonly logopath?: string;
-        readonly passagevmid?: string;
-    };
-    /** digest of the host memory plan produced by virtualmemory.ts. */
-    readonly memoryplandigest?: string;
-}
-/**
- * the canonical 24 stage names of the saddle v6 pipeline, preserved
- * verbatim (numbered pool identifiers are catalog data, not new code
- * identifiers).
- */
-export type stageid = '01_ingest_audit' | '02_probe_ffprobe71' | '03_tieredmemory_reserve' | '04_hugepage_alloc_2m1g' | '05_zram_lzorle_zstd' | '06_cxl_map_v2_v3' | '07_vcpu_pin_ccd_x3d' | '08_hwaccel_detect_blackwell' | '09_hwupload_cuda' | '10DeinterlaceBwdifCuda' | '11_scale_cuda_npp' | '12TonemapBt2020Cuda' | '13DenoiseCuda' | '14_color_mgmt' | '15_nvenc_blackwell_encode' | '16QsvFallback' | '17_audio_transcode' | '18SubtitleBurn' | '19_mux_container' | '20_passage_message_vsock' | '21_qemu_balloon_notify' | '22_tiered_reclaim' | '23_mttg_slice_report' | '24_artifact_gc_finalize';
-/** one catalog row of the 24-stage table. */
-export interface stageentry {
-    readonly name: stageid;
-    readonly index: number;
-    readonly description: string;
-    readonly gpurequired: boolean;
-    /** stages that the pool marks skippable through a skipIf predicate. */
-    readonly skippable: boolean;
-}
-/**
- * the 24-stage catalog sequenced for maximum cache affinity: CCD0
- * V-Cache carries the video filter chain, CCD1 carries audio, mux and
- * io, memory stages (03-07) precede any GPU work.
- */
-export declare const stagecatalog: readonly stageentry[];
-/**
- * the alternate v5 ordering of src_mttg_pipeline.ts kept as provenance:
- * demux/decode walk, crop_pad, overlay_logo, sharpen, thumbnail and
- * upload_egress stages that the v6 line folded into other stages.
- */
-export declare const stageorderv5: readonly string[];
-/** validates the stage catalog invariant: 24 stages, indexes 1..24. */
-export declare function validatestagecatalog(): {
-    count: number;
-    ordered: boolean;
-};
-/** codec name to ffmpeg nvenc encoder mapping (Blackwell 9th gen). */
-export declare const nvencencodernames: Readonly<Record<'h264' | 'hevc' | 'av1', string>>;
-/**
- * synthesizes the ffmpeg 7.1 argv for one stage. the encode stage
- * builds the full filter chain (deinterlace, scale, tone map) plus the
- * NVENC block: preset p1..p7, rc vbr_hq, cq 23, 1.5x maxrate ceiling,
- * multipass 2, b-frames with b_ref_mode 2, temporal aq with
- * rc-lookahead 32, gpu device index and, for av1, tier high / main
- * profile. the deinterlace and scale stages emit preview null-output
- * commands at preset p1.
- */
-export declare function buildffmpegcommand(job: mediajob, probe: mediaprobe, stage: stageid, gpuid?: number): readonly string[];
-/** encoder backend vendors of the pool policy plus the software floor. */
-export type encodervendor = 'nvidianvenc' | 'intelqsv' | 'amdamf' | 'softwarex265';
-/** encoder tune axes used by the preset recommender. */
-export type encodertune = 'ultralowlatency' | 'lowlatency' | 'quality';
-/** the decision record returned by createoptimal. */
-export interface optimalencoder {
-    readonly vendor: encodervendor;
-    readonly preset: nvencpreset;
-    readonly reason: string;
-    readonly maxinstances: number;
-}
-/**
- * the createoptimal policy distilled from the pool encoding
- * optimization manager: AV1 at 4K or above forces the Blackwell NVENC
- * dual-encoder path (best AV1 quality of 2026), h264 under an
- * ultra-low-latency tune prefers QuickSync (conferencing), an amd host
- * prefers AMF for 1080p power efficiency, and everything else falls
- * back to the software x265 + SVT-AV1 pair when no gpu matches.
- */
-export declare function createoptimal(job: mediajob, probe: mediaprobe, preferred?: encodervendor): optimalencoder;
-/**
- * maps codec + tune + liveness to the preset ladder, mirroring the pool
- * recommend_preset: ultra low latency p1, low latency p2, live p3
- * (av1 needs the faster point), vod av1 p5, vod hevc p6, otherwise p4.
- */
-export declare function recommendpreset(codec: 'h264' | 'hevc' | 'av1', tune: encodertune, live: boolean): nvencpreset;
-/**
- * recommends the concurrent encode instances for one gpu: pixel count
- * throttles the session count, the software floor is 32 (the pool
- * benchmark helper skips it anyway).
- */
-export declare function recommendmaxinstances(vendor: encodervendor, codec: 'h264' | 'hevc' | 'av1', width: number, height: number): number;
-/**
- * the passage channel contract mirrored from passage.config: control
- * over vsock, data over virtio-serial, bulk over virtiofs, frames
- * sealed with chacha20-poly1305 and signed with ed25519, MTU 65536.
- */
-export interface passagechannelsettings {
-    readonly transport: 'vsock+virtio-serial' | 'vsock';
-    readonly encryption: 'chacha20-poly1305';
-    readonly auth: 'ed25519';
-    readonly control: string;
-    readonly data: string;
-    readonly bulk: string;
-    readonly mtu: 65536;
-    readonly ratelimitmbps: 10000;
-    readonly maxstreams: 256;
-    readonly latencytargetus: 150;
-}
-/** default channel endpoints (vsock cid 2 port 1024 contract). */
-export declare const defaultpassagechannel: passagechannelsettings;
-/** one sealed passage frame ready for the vsock write. */
-export interface passageframe {
-    readonly payload: Buffer;
-    readonly nonce: Buffer;
-    readonly signature: Buffer;
-    readonly truncated: boolean;
-}
-/**
- * the secure passage channel of stage 20: every message is sealed with
- * ChaCha20-Poly1305 (RFC 8439, reusing the security.ts AEAD helpers)
- * and signed with a per-channel ed25519 key pair; frames larger than
- * the 65536 MTU are split and marked truncated so the peer can
- * reassemble over the 256-stream budget.
- */
-export declare class passagesecurechannel {
-    #private;
-    readonly settings: passagechannelsettings;
-    constructor(settings?: passagechannelsettings);
-    /** exports the spki public key peers use to verify signatures. */
-    publickey(): Buffer;
-    /** seals and signs one message, splitting at the 65536 MTU. */
-    seal(message: string | Buffer, key?: Buffer): readonly passageframe[];
-    /** verifies and opens one frame back into plaintext. */
-    open(frame: passageframe, key?: Buffer): Buffer;
-    /** deterministically derives the symmetric frame key for the channel. */
-    framekey(): Buffer;
-}
-/** per-stage measurement record. */
-export interface stagerecord {
-    readonly stage: stageid;
-    readonly index: number;
-    readonly skipped: boolean;
-    readonly success: boolean;
-    readonly gpurequired: boolean;
-    readonly error?: string;
-}
-/** result of one job executed through the 24 stages. */
-export interface jobresult {
-    readonly jobid: string;
-    readonly success: boolean;
-    readonly metrics: readonly stagerecord[];
-    readonly ffmpegpreview: readonly string[];
-    readonly passageframes: number;
-}
-/**
- * the executing 24-stage pipeline. stages 03-07 validate the memory
- * plan digest handed over by virtualmemory.ts (no planner duplication),
- * the gpu stages synthesize real ffmpeg argv through the builder, and
- * stage 20 pushes one sealed passage frame per notification message.
- * fail-fast is honored: the first non-recoverable failure stops the
- * walk, recoverable failures continue unless failfast is disabled.
- */
-export declare class mediapipeline {
-    #private;
-    readonly failfast: boolean;
-    readonly channel: passagesecurechannel;
-    constructor(options?: {
-        failfast?: boolean;
-        channel?: passagesecurechannel;
-    });
-    /**
-     * executes one job through the 24 stages. probe drives every skip
-     * rule: interlaced inputs keep stage 10, HDR sources with a tone-map
-     * request keep stage 12, subtitle and logo paths keep stage 18, and
-     * a Blackwell vendor keeps stage 16 skipped (qsv fallback).
-     */
-    executejob(job: mediajob, probe: mediaprobe, signal?: AbortSignal): jobresult;
-    /** chunked batch execution honoring a max concurrency. */
-    executebatch(jobs: readonly mediajob[], probes: readonly mediaprobe[], maxconcurrent?: number): readonly jobresult[];
-}
-/**
- * filename-hint prober mirroring the pool probeMedia heuristic: names
- * carrying hdr/10bit probe as HDR, interlaced names as interlaced and
- * 4k/2160 names as 3840x2160.
- */
-export declare function probefromname(inputpath: string): mediaprobe;
-/** provenance row for the compute/domain absorption index. */
-export declare const mediafeatureindex: readonly {
-    id: string;
-    origin: string;
-    name: string;
-    exportname: string;
-}[];
-/** default export keeps the pool orchestrator naming lineage visible. */
-export default mediapipeline;