@camstack/addon-decoder-ffmpeg 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+import * as _camstack_types from '@camstack/types';
+import { BaseAddon, DecoderHwAccelConfig, IDecoderCapProvider, ProviderRegistration, FrameFormat, DecoderStats, IDecoderProvider, IScopedLogger, DecoderSessionConfig, IDecoderSession, HwAccelBackend, IKernelHwAccel, EncodedPacket, DecodedFrame, Unsubscribe } from '@camstack/types';
+
+/** Cap-compatible frame shape — format must match DecodedFrameSchema enum values. */
+type CapDecodedFrame = {
+    data: Uint8Array<ArrayBuffer>;
+    width: number;
+    height: number;
+    format: FrameFormat;
+    timestamp: number;
+};
+/** Cap-compatible session config — matches DecoderSessionConfigSchema output type. */
+type CapDecoderSessionConfig = {
+    codec: string;
+    maxFps: number;
+    outputFormat: FrameFormat;
+    scale: number;
+    width?: number;
+    height?: number;
+};
+/** Cap-compatible encoded packet — data is Uint8Array matching EncodedPacketSchema. */
+type CapEncodedPacket = {
+    type: 'video' | 'audio';
+    data: Uint8Array<ArrayBuffer>;
+    pts: number;
+    dts: number;
+    keyframe: boolean;
+    codec: string;
+};
+/**
+ * FFmpeg decoder addon — H264/HEVC/MJPEG decode via ffmpeg child
+ * process.
+ *
+ * Phase 2d of the pipeline-settings migration — ffmpeg decoder owns
+ * its own `hwaccel` choice + `probedBestHwaccel` hint. Sessions
+ * resolve the effective backend from this addon's global settings
+ * instead of the orchestrator's legacy `AgentPipelineSettings.hwaccel`.
+ * Session constructor still appends `-hwaccel <name>` to the ffmpeg
+ * argv as before.
+ *
+ * Implements the sessionId-based IDecoderCapProvider cap interface.
+ * Sessions are managed internally via a Map; frames are polled via
+ * RingBuffer.
+ */
+declare class DecoderFfmpegAddon extends BaseAddon<DecoderHwAccelConfig> implements IDecoderCapProvider {
+    private readonly sessions;
+    private readonly frameBuffers;
+    private readonly unsubscribers;
+    private readonly sessionMeta;
+    constructor();
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    /**
+     * Resolve the effective hwaccel backend for a new session. Reads
+     * this addon's own `hwaccel` setting. `'auto'` defers to the
+     * session's local resolver (`ctx.kernel.hwaccel`).
+     */
+    private resolveHwAccelPref;
+    /**
+     * Re-run the platform probe on this host and persist the detected
+     * backend as `probedBestHwaccel`. Operator `hwaccel` setting is not
+     * touched — only the hint.
+     */
+    reprobeHwaccel(): Promise<{
+        backend: string;
+    }>;
+    supportsCodec(input: {
+        codec: string;
+    }): Promise<boolean>;
+    getInfo(): Promise<{
+        id: string;
+        name: string;
+        isPullMode?: boolean;
+        priority?: number;
+    }>;
+    createSession(config: CapDecoderSessionConfig): Promise<{
+        sessionId: string;
+        nodeId: string;
+    }>;
+    destroySession(input: {
+        sessionId: string;
+    }): Promise<void>;
+    listActiveSessions(): Promise<readonly {
+        sessionId: string;
+        codec: string;
+        outputFormat: string;
+        createdAtMs: number;
+    }[]>;
+    pushPacket(input: {
+        sessionId: string;
+        packet: CapEncodedPacket;
+    }): Promise<void>;
+    openStream(input: {
+        sessionId: string;
+        url: string;
+    }): Promise<void>;
+    pullFrames(input: {
+        sessionId: string;
+        maxCount: number;
+    }): Promise<CapDecodedFrame[]>;
+    updateConfig(input: {
+        sessionId: string;
+        config: Partial<CapDecoderSessionConfig>;
+    }): Promise<void>;
+    getStats(input: {
+        sessionId: string;
+    }): Promise<DecoderStats>;
+    protected onShutdown(): Promise<void>;
+}
+
+declare class FfmpegDecoderProvider implements IDecoderProvider {
+    readonly id = "ffmpeg";
+    readonly name = "FFmpeg Decoder";
+    readonly isPullMode = false;
+    /** Software decoder — used as fallback when hardware decoders are unavailable. */
+    readonly priority = 50;
+    private logger;
+    setLogger(logger: IScopedLogger): void;
+    supportsCodec(input: {
+        codec: string;
+    }): Promise<boolean>;
+    createSession(config: DecoderSessionConfig): Promise<IDecoderSession>;
+}
+
+type HwAccelPref = 'auto' | 'none' | HwAccelBackend;
+interface FfmpegDecoderSessionOptions {
+    /** Addon-level hwaccel preference — per-agent. Default `'auto'`. */
+    readonly hwaccel?: HwAccelPref;
+    /** Kernel hwaccel resolver — `ctx.kernel.hwaccel` passed from the addon. */
+    readonly hwaccelResolver?: IKernelHwAccel;
+}
+declare class FfmpegDecoderSession implements IDecoderSession {
+    private config;
+    private frameDropper;
+    private process;
+    private frameCallbacks;
+    private outputBuffer;
+    private destroyed;
+    private readonly logger;
+    /** When openStream() is used, we read from RTSP directly (not push mode) */
+    private pullMode;
+    private cachedWidth;
+    private cachedHeight;
+    private inputPackets;
+    private outputFrames;
+    private droppedFrames;
+    private totalDecodeTimeMs;
+    private decodeCount;
+    private startTime;
+    private readonly hwaccelPref;
+    private readonly hwaccelResolver;
+    /** The backend we actually passed to ffmpeg `-hwaccel` — `'none'` = software. */
+    private activeHwAccel;
+    /**
+     * Backend resolution is async (calls into `ctx.kernel.hwaccel`), but
+     * `pushPacket` is sync — we kick the resolve off in the constructor
+     * and cache the result. By the time the first keyframe arrives
+     * (~30ms for RTSP), the resolver has completed (it's ultimately
+     * `os.platform()` + file checks → sub-ms). If `ensurePushProcess`
+     * fires before resolve settles, it skips hwaccel for that spawn;
+     * reconnect loop gets the flag on subsequent sessions.
+     */
+    private resolvedBackend;
+    constructor(config: DecoderSessionConfig, logger?: IScopedLogger, options?: FfmpegDecoderSessionOptions);
+    /**
+     * Resolve the preferred backend for this host and return the first
+     * hit, or `null` when software is requested / nothing available.
+     * FFmpeg CLI accepts the `-hwaccel <name>` identifier directly.
+     */
+    private resolveHwAccelBackend;
+    /**
+     * Open an RTSP stream directly — ffmpeg reads from the URL and outputs JPEG frames.
+     * This avoids the raw h264 pipe which loses SPS/PPS metadata on some cameras.
+     */
+    openStream(url: string): Promise<void>;
+    private ensurePushProcess;
+    private killFfmpeg;
+    private handleOutputData;
+    private emitFrame;
+    pushPacket(packet: EncodedPacket): void;
+    onFrame(callback: (frame: DecodedFrame) => void): Unsubscribe;
+    updateConfig(update: Partial<DecoderSessionConfig>): void;
+    destroy(): Promise<void>;
+    getStats(): DecoderStats;
+}
+
+declare class FrameDropper {
+    private intervalMs;
+    private lastPassedAt;
+    constructor(maxFps: number);
+    shouldKeep(): boolean;
+    setMaxFps(maxFps: number): void;
+}
+
+export { DecoderFfmpegAddon, FfmpegDecoderProvider, FfmpegDecoderSession, FrameDropper };

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+import * as _camstack_types from '@camstack/types';
+import { BaseAddon, DecoderHwAccelConfig, IDecoderCapProvider, ProviderRegistration, FrameFormat, DecoderStats, IDecoderProvider, IScopedLogger, DecoderSessionConfig, IDecoderSession, HwAccelBackend, IKernelHwAccel, EncodedPacket, DecodedFrame, Unsubscribe } from '@camstack/types';
+
+/** Cap-compatible frame shape — format must match DecodedFrameSchema enum values. */
+type CapDecodedFrame = {
+    data: Uint8Array<ArrayBuffer>;
+    width: number;
+    height: number;
+    format: FrameFormat;
+    timestamp: number;
+};
+/** Cap-compatible session config — matches DecoderSessionConfigSchema output type. */
+type CapDecoderSessionConfig = {
+    codec: string;
+    maxFps: number;
+    outputFormat: FrameFormat;
+    scale: number;
+    width?: number;
+    height?: number;
+};
+/** Cap-compatible encoded packet — data is Uint8Array matching EncodedPacketSchema. */
+type CapEncodedPacket = {
+    type: 'video' | 'audio';
+    data: Uint8Array<ArrayBuffer>;
+    pts: number;
+    dts: number;
+    keyframe: boolean;
+    codec: string;
+};
+/**
+ * FFmpeg decoder addon — H264/HEVC/MJPEG decode via ffmpeg child
+ * process.
+ *
+ * Phase 2d of the pipeline-settings migration — ffmpeg decoder owns
+ * its own `hwaccel` choice + `probedBestHwaccel` hint. Sessions
+ * resolve the effective backend from this addon's global settings
+ * instead of the orchestrator's legacy `AgentPipelineSettings.hwaccel`.
+ * Session constructor still appends `-hwaccel <name>` to the ffmpeg
+ * argv as before.
+ *
+ * Implements the sessionId-based IDecoderCapProvider cap interface.
+ * Sessions are managed internally via a Map; frames are polled via
+ * RingBuffer.
+ */
+declare class DecoderFfmpegAddon extends BaseAddon<DecoderHwAccelConfig> implements IDecoderCapProvider {
+    private readonly sessions;
+    private readonly frameBuffers;
+    private readonly unsubscribers;
+    private readonly sessionMeta;
+    constructor();
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    /**
+     * Resolve the effective hwaccel backend for a new session. Reads
+     * this addon's own `hwaccel` setting. `'auto'` defers to the
+     * session's local resolver (`ctx.kernel.hwaccel`).
+     */
+    private resolveHwAccelPref;
+    /**
+     * Re-run the platform probe on this host and persist the detected
+     * backend as `probedBestHwaccel`. Operator `hwaccel` setting is not
+     * touched — only the hint.
+     */
+    reprobeHwaccel(): Promise<{
+        backend: string;
+    }>;
+    supportsCodec(input: {
+        codec: string;
+    }): Promise<boolean>;
+    getInfo(): Promise<{
+        id: string;
+        name: string;
+        isPullMode?: boolean;
+        priority?: number;
+    }>;
+    createSession(config: CapDecoderSessionConfig): Promise<{
+        sessionId: string;
+        nodeId: string;
+    }>;
+    destroySession(input: {
+        sessionId: string;
+    }): Promise<void>;
+    listActiveSessions(): Promise<readonly {
+        sessionId: string;
+        codec: string;
+        outputFormat: string;
+        createdAtMs: number;
+    }[]>;
+    pushPacket(input: {
+        sessionId: string;
+        packet: CapEncodedPacket;
+    }): Promise<void>;
+    openStream(input: {
+        sessionId: string;
+        url: string;
+    }): Promise<void>;
+    pullFrames(input: {
+        sessionId: string;
+        maxCount: number;
+    }): Promise<CapDecodedFrame[]>;
+    updateConfig(input: {
+        sessionId: string;
+        config: Partial<CapDecoderSessionConfig>;
+    }): Promise<void>;
+    getStats(input: {
+        sessionId: string;
+    }): Promise<DecoderStats>;
+    protected onShutdown(): Promise<void>;
+}
+
+declare class FfmpegDecoderProvider implements IDecoderProvider {
+    readonly id = "ffmpeg";
+    readonly name = "FFmpeg Decoder";
+    readonly isPullMode = false;
+    /** Software decoder — used as fallback when hardware decoders are unavailable. */
+    readonly priority = 50;
+    private logger;
+    setLogger(logger: IScopedLogger): void;
+    supportsCodec(input: {
+        codec: string;
+    }): Promise<boolean>;
+    createSession(config: DecoderSessionConfig): Promise<IDecoderSession>;
+}
+
+type HwAccelPref = 'auto' | 'none' | HwAccelBackend;
+interface FfmpegDecoderSessionOptions {
+    /** Addon-level hwaccel preference — per-agent. Default `'auto'`. */
+    readonly hwaccel?: HwAccelPref;
+    /** Kernel hwaccel resolver — `ctx.kernel.hwaccel` passed from the addon. */
+    readonly hwaccelResolver?: IKernelHwAccel;
+}
+declare class FfmpegDecoderSession implements IDecoderSession {
+    private config;
+    private frameDropper;
+    private process;
+    private frameCallbacks;
+    private outputBuffer;
+    private destroyed;
+    private readonly logger;
+    /** When openStream() is used, we read from RTSP directly (not push mode) */
+    private pullMode;
+    private cachedWidth;
+    private cachedHeight;
+    private inputPackets;
+    private outputFrames;
+    private droppedFrames;
+    private totalDecodeTimeMs;
+    private decodeCount;
+    private startTime;
+    private readonly hwaccelPref;
+    private readonly hwaccelResolver;
+    /** The backend we actually passed to ffmpeg `-hwaccel` — `'none'` = software. */
+    private activeHwAccel;
+    /**
+     * Backend resolution is async (calls into `ctx.kernel.hwaccel`), but
+     * `pushPacket` is sync — we kick the resolve off in the constructor
+     * and cache the result. By the time the first keyframe arrives
+     * (~30ms for RTSP), the resolver has completed (it's ultimately
+     * `os.platform()` + file checks → sub-ms). If `ensurePushProcess`
+     * fires before resolve settles, it skips hwaccel for that spawn;
+     * reconnect loop gets the flag on subsequent sessions.
+     */
+    private resolvedBackend;
+    constructor(config: DecoderSessionConfig, logger?: IScopedLogger, options?: FfmpegDecoderSessionOptions);
+    /**
+     * Resolve the preferred backend for this host and return the first
+     * hit, or `null` when software is requested / nothing available.
+     * FFmpeg CLI accepts the `-hwaccel <name>` identifier directly.
+     */
+    private resolveHwAccelBackend;
+    /**
+     * Open an RTSP stream directly — ffmpeg reads from the URL and outputs JPEG frames.
+     * This avoids the raw h264 pipe which loses SPS/PPS metadata on some cameras.
+     */
+    openStream(url: string): Promise<void>;
+    private ensurePushProcess;
+    private killFfmpeg;
+    private handleOutputData;
+    private emitFrame;
+    pushPacket(packet: EncodedPacket): void;
+    onFrame(callback: (frame: DecodedFrame) => void): Unsubscribe;
+    updateConfig(update: Partial<DecoderSessionConfig>): void;
+    destroy(): Promise<void>;
+    getStats(): DecoderStats;
+}
+
+declare class FrameDropper {
+    private intervalMs;
+    private lastPassedAt;
+    constructor(maxFps: number);
+    shouldKeep(): boolean;
+    setMaxFps(maxFps: number): void;
+}
+
+export { DecoderFfmpegAddon, FfmpegDecoderProvider, FfmpegDecoderSession, FrameDropper };