node-av 1.1.0 → 1.3.0

package/dist/lib/native-types.d.ts

@@ -5,14 +5,7 @@
  * This file contains all TypeScript interfaces for the native C++ FFmpeg bindings.
  * These interfaces represent the exact API surface exposed by the C++ layer.
  *
- * IMPORTANT:
- * - These are internal interfaces - users should use the wrapper classes in lib/
- * - All interfaces map 1:1 to C++ binding implementations
- * - Properties marked as readonly only have getters in C++
- * - Resource-owning classes provide both free() and Symbol.dispose for cleanup
- *
  * @internal
- * @packageDocumentation
  */
 import type { AVDictFlag, AVFilterCmdFlag, AVFilterConstants, AVFilterFlag, AVFrameSideDataType, AVHWDeviceType, AVHWFrameTransferDirection, AVIOFlag, AVOptionFlag, AVOptionType, AVPacketSideDataType, AVPixelFormat, AVSeekFlag, AVSeekWhence, SWSFlag } from '../constants/constants.js';
 import type { AVChromaLocation, AVCodecCap, AVCodecFlag, AVCodecFlag2, AVCodecID, AVColorPrimaries, AVColorRange, AVColorSpace, AVColorTransferCharacteristic, AVDiscard, AVDisposition, AVFormatFlag, AVMediaType, AVPacketFlag, AVPictureType, AVProfile, AVSampleFormat, AVStreamEventFlag } from '../constants/index.js';
@@ -27,23 +20,23 @@ import type { ChannelLayout, CodecProfile, FilterPad, IRational } from './types.
  */
 export interface NativePacket extends Disposable {
     readonly __brand: 'NativePacket';
-    alloc(): void;
-    free(): void;
-    ref(src: NativePacket): number;
-    unref(): void;
-    clone(): NativePacket | null;
-    rescaleTs(srcTb: IRational, dstTb: IRational): void;
-    makeRefcounted(): number;
-    makeWritable(): number;
+    readonly size: number;
     streamIndex: number;
     pts: bigint;
     dts: bigint;
     duration: bigint;
     pos: bigint;
-    readonly size: number;
     flags: AVPacketFlag;
     data: Buffer | null;
     isKeyframe: boolean;
+    alloc(): void;
+    free(): void;
+    ref(src: NativePacket): number;
+    unref(): void;
+    clone(): NativePacket | null;
+    rescaleTs(srcTb: IRational, dstTb: IRational): void;
+    makeRefcounted(): number;
+    makeWritable(): number;
     getSideData(type: AVPacketSideDataType): Buffer | null;
     addSideData(type: AVPacketSideDataType, data: Buffer): number;
     newSideData(type: AVPacketSideDataType, size: number): Buffer;
@@ -60,17 +53,11 @@ export interface NativePacket extends Disposable {
  */
 export interface NativeFrame extends Disposable {
     readonly __brand: 'NativeFrame';
-    alloc(): void;
-    free(): void;
-    ref(src: NativeFrame): number;
-    unref(): void;
-    clone(): NativeFrame | null;
-    getBuffer(align?: number): number;
-    allocBuffer(): number;
-    makeWritable(): number;
-    copyProps(src: NativeFrame): number;
-    copy(src: NativeFrame): number;
-    fromBuffer(buffer: Buffer): number;
+    readonly channels: number;
+    readonly linesize: number[];
+    readonly data: Buffer[] | null;
+    readonly extendedData: Buffer[] | null;
+    readonly isWritable: boolean;
     format: AVPixelFormat | AVSampleFormat;
     width: number;
     height: number;
@@ -84,20 +71,26 @@ export interface NativeFrame extends Disposable {
     sampleAspectRatio: IRational;
     sampleRate: number;
     channelLayout: ChannelLayout;
-    readonly channels: number;
-    readonly linesize: number[];
     colorRange: AVColorRange;
     colorPrimaries: AVColorPrimaries;
     colorTrc: AVColorTransferCharacteristic;
     colorSpace: AVColorSpace;
     chromaLocation: AVChromaLocation;
-    readonly data: Buffer[] | null;
-    readonly extendedData: Buffer[] | null;
     hwFramesCtx: NativeHardwareFramesContext | null;
+    alloc(): void;
+    free(): void;
+    ref(src: NativeFrame): number;
+    unref(): void;
+    clone(): NativeFrame | null;
+    getBuffer(align?: number): number;
+    allocBuffer(): number;
+    makeWritable(): number;
+    copyProps(src: NativeFrame): number;
+    copy(src: NativeFrame): number;
+    fromBuffer(buffer: Buffer): number;
     hwframeTransferData(dst: NativeFrame, flags?: number): Promise<number>;
     isHwFrame(): boolean;
     isSwFrame(): boolean;
-    readonly isWritable: boolean;
     getSideData(type: AVFrameSideDataType): Buffer | null;
     newSideData(type: AVFrameSideDataType, size: number): Buffer;
     removeSideData(type: AVFrameSideDataType): void;
@@ -145,23 +138,15 @@ export interface NativeCodec {
  */
 export interface NativeCodecContext extends Disposable {
     readonly __brand: 'NativeCodecContext';
-    allocContext3(codec?: NativeCodec | null): void;
-    freeContext(): void;
-    open2(codec?: NativeCodec | null, options?: NativeDictionary | null): Promise<number>;
-    close(): number;
-    parametersToContext(params: NativeCodecParameters): number;
-    parametersFromContext(params: NativeCodecParameters): number;
-    flushBuffers(): void;
-    sendPacket(packet: NativePacket | null): Promise<number>;
-    receiveFrame(frame: NativeFrame): Promise<number>;
-    sendFrame(frame: NativeFrame | null): Promise<number>;
-    receivePacket(packet: NativePacket): Promise<number>;
+    readonly delay: number;
+    readonly hasBFrames: number;
+    readonly frameNumber: number;
+    readonly isOpen: boolean;
     codecType: AVMediaType;
     codecId: AVCodecID;
     bitRate: bigint;
     timeBase: IRational;
     pktTimebase: IRational;
-    readonly delay: number;
     flags: AVCodecFlag;
     flags2: AVCodecFlag2;
     extraData: Buffer | null;
@@ -174,7 +159,6 @@ export interface NativeCodecContext extends Disposable {
     pixelFormat: AVPixelFormat;
     maxBFrames: number;
     mbDecision: number;
-    readonly hasBFrames: number;
     sampleAspectRatio: IRational;
     framerate: IRational;
     colorRange: AVColorRange;
@@ -186,7 +170,6 @@ export interface NativeCodecContext extends Disposable {
     channels: number;
     sampleFormat: AVSampleFormat;
     frameSize: number;
-    readonly frameNumber: number;
     channelLayout: ChannelLayout;
     qMin: number;
     qMax: number;
@@ -195,8 +178,19 @@ export interface NativeCodecContext extends Disposable {
     rcMinRate: bigint;
     hwDeviceCtx: NativeHardwareDeviceContext | null;
     hwFramesCtx: NativeHardwareFramesContext | null;
+    allocContext3(codec?: NativeCodec | null): void;
+    freeContext(): void;
+    open2(codec?: NativeCodec | null, options?: NativeDictionary | null): Promise<number>;
+    open2Sync(codec?: NativeCodec | null, options?: NativeDictionary | null): number;
+    close(): number;
+    parametersToContext(params: NativeCodecParameters): number;
+    parametersFromContext(params: NativeCodecParameters): number;
+    flushBuffers(): void;
+    sendPacket(packet: NativePacket | null): Promise<number>;
+    receiveFrame(frame: NativeFrame): Promise<number>;
+    sendFrame(frame: NativeFrame | null): Promise<number>;
+    receivePacket(packet: NativePacket): Promise<number>;
     setHardwarePixelFormat(hwFormat: AVPixelFormat, swFormat?: AVPixelFormat): void;
-    readonly isOpen: boolean;
     [Symbol.dispose](): void;
 }
 /**
@@ -223,17 +217,11 @@ export interface NativeCodecParser {
  */
 export interface NativeCodecParameters extends Disposable {
     readonly __brand: 'NativeCodecParameters';
-    alloc(): void;
-    free(): void;
-    copy(dst: NativeCodecParameters): number;
-    fromContext(codecContext: NativeCodecContext): number;
-    toContext(codecContext: NativeCodecContext): number;
-    toJSON(): Record<string, any>;
+    readonly extradataSize: number;
     codecType: AVMediaType;
     codecId: AVCodecID;
     codecTag: number;
     extradata: Buffer | null;
-    readonly extradataSize: number;
     format: AVPixelFormat | AVSampleFormat;
     bitRate: bigint;
     profile: AVProfile;
@@ -250,6 +238,12 @@ export interface NativeCodecParameters extends Disposable {
     channelLayout: ChannelLayout;
     channels: number;
     sampleRate: number;
+    alloc(): void;
+    free(): void;
+    copy(dst: NativeCodecParameters): number;
+    fromContext(codecContext: NativeCodecContext): number;
+    toContext(codecContext: NativeCodecContext): number;
+    toJSON(): Record<string, any>;
     [Symbol.dispose](): void;
 }
 /**
@@ -299,11 +293,11 @@ export interface NativeIOContext extends AsyncDisposable {
     readonly eof: boolean;
     readonly error: number;
     readonly seekable: number;
-    maxPacketSize: number;
-    direct: number;
     readonly pos: bigint;
     readonly bufferSize: number;
     readonly writeFlag: boolean;
+    maxPacketSize: number;
+    direct: number;
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
@@ -353,6 +347,7 @@ export interface NativeOutputFormat {
 export interface NativeStream {
     readonly __brand: 'NativeStream';
     readonly index: number;
+    readonly attachedPic: NativePacket | null;
     id: number;
     codecpar: NativeCodecParameters;
     timeBase: IRational;
@@ -365,7 +360,6 @@ export interface NativeStream {
     avgFrameRate: IRational;
     rFrameRate: IRational;
     metadata: NativeDictionary | null;
-    readonly attachedPic: NativePacket | null;
     eventFlags: AVStreamEventFlag;
 }
 /**
@@ -378,6 +372,24 @@ export interface NativeStream {
  */
 export interface NativeFormatContext extends AsyncDisposable {
     readonly __brand: 'NativeFormatContext';
+    readonly startTime: bigint;
+    readonly duration: bigint;
+    readonly bitRate: bigint;
+    readonly iformat: NativeInputFormat | null;
+    readonly nbStreams: number;
+    readonly streams: NativeStream[] | null;
+    readonly nbPrograms: number;
+    readonly pbBytes: bigint;
+    readonly probeScore: number;
+    url: string | null;
+    flags: AVFormatFlag;
+    probesize: bigint;
+    maxAnalyzeDuration: bigint;
+    metadata: NativeDictionary | null;
+    oformat: NativeOutputFormat | null;
+    pb: NativeIOContext | null;
+    strictStdCompliance: number;
+    maxStreams: number;
     allocContext(): void;
     allocOutputContext2(oformat: NativeOutputFormat | null, formatName: string | null, filename: string | null): number;
     freeContext(): void;
@@ -400,24 +412,6 @@ export interface NativeFormatContext extends AsyncDisposable {
         streamIndex: number;
         decoder: NativeCodec | null;
     };
-    url: string | null;
-    readonly startTime: bigint;
-    readonly duration: bigint;
-    readonly bitRate: bigint;
-    flags: AVFormatFlag;
-    probesize: bigint;
-    maxAnalyzeDuration: bigint;
-    metadata: NativeDictionary | null;
-    readonly iformat: NativeInputFormat | null;
-    oformat: NativeOutputFormat | null;
-    pb: NativeIOContext | null;
-    readonly nbStreams: number;
-    readonly streams: NativeStream[] | null;
-    strictStdCompliance: number;
-    maxStreams: number;
-    readonly nbPrograms: number;
-    readonly pbBytes: bigint;
-    readonly probeScore: number;
     [Symbol.dispose](): void;
 }
 /**
@@ -425,8 +419,11 @@ export interface NativeFormatContext extends AsyncDisposable {
  *
  * Provides error code translation and string representation.
  * Maps FFmpeg error codes to human-readable messages.
+ *
+ * @internal
  */
 export interface NativeFFmpegError {
+    readonly __brand: 'NativeFFmpegError';
     readonly code: number;
     readonly message: string;
 }
@@ -440,6 +437,8 @@ export interface NativeFFmpegError {
  */
 export interface NativeAudioFifo extends Disposable {
     readonly __brand: 'NativeAudioFifo';
+    readonly size: number;
+    readonly space: number;
     alloc(sampleFmt: AVSampleFormat, channels: number, nbSamples: number): void;
     free(): void;
     write(data: Buffer | Buffer[], nbSamples: number): Promise<number>;
@@ -448,8 +447,6 @@ export interface NativeAudioFifo extends Disposable {
     drain(nbSamples: number): void;
     reset(): void;
     realloc(nbSamples: number): number;
-    readonly size: number;
-    readonly space: number;
 }
 /**
  * Native SwsContext binding interface
@@ -524,6 +521,13 @@ export interface NativeFilter {
  */
 export interface NativeFilterContext extends Disposable {
     readonly __brand: 'NativeFilterContext';
+    readonly filter: NativeFilter | null;
+    readonly graph: NativeFilterGraph | null;
+    readonly nbInputs: number;
+    readonly nbOutputs: number;
+    readonly ready: number;
+    name: string | null;
+    hwDeviceCtx: NativeHardwareDeviceContext | null;
     init(options?: NativeDictionary | null): number;
     initStr(args?: string | null): number;
     link(srcPad: number, dst: NativeFilterContext, dstPad: number): number;
@@ -550,13 +554,6 @@ export interface NativeFilterContext extends Disposable {
     buffersinkGetChannelLayout(): ChannelLayout;
     buffersinkGetSampleAspectRatio(): IRational;
     free(): void;
-    name: string | null;
-    readonly filter: NativeFilter | null;
-    readonly graph: NativeFilterGraph | null;
-    readonly nbInputs: number;
-    readonly nbOutputs: number;
-    readonly ready: number;
-    hwDeviceCtx: NativeHardwareDeviceContext | null;
     [Symbol.dispose](): void;
 }
 /**
@@ -569,6 +566,11 @@ export interface NativeFilterContext extends Disposable {
  */
 export interface NativeFilterGraph extends Disposable {
     readonly __brand: 'NativeFilterGraph';
+    readonly nbFilters: number;
+    readonly filters: NativeFilterContext[] | null;
+    threadType: AVFilterConstants;
+    nbThreads: number;
+    scaleSwsOpts: string | null;
     alloc(): void;
     free(): void;
     createFilter(filter: NativeFilter, name: string, args?: string | null): NativeFilterContext | null;
@@ -585,11 +587,6 @@ export interface NativeFilterGraph extends Disposable {
         response: string | null;
     };
     queueCommand(target: string, cmd: string, arg: string, ts: number, flags?: AVFilterCmdFlag): number;
-    readonly nbFilters: number;
-    readonly filters: NativeFilterContext[] | null;
-    threadType: AVFilterConstants;
-    nbThreads: number;
-    scaleSwsOpts: string | null;
     [Symbol.dispose](): void;
 }
 /**
@@ -602,12 +599,12 @@ export interface NativeFilterGraph extends Disposable {
  */
 export interface NativeFilterInOut extends Disposable {
     readonly __brand: 'NativeFilterInOut';
-    alloc(): void;
-    free(): void;
     name: string | null;
     filterCtx: NativeFilterContext | null;
     padIdx: number;
     next: NativeFilterInOut | null;
+    alloc(): void;
+    free(): void;
     [Symbol.dispose](): void;
 }
 /**
@@ -615,9 +612,13 @@ export interface NativeFilterInOut extends Disposable {
  *
  * Hardware device context for hardware acceleration.
  * Direct mapping to FFmpeg's AVHWDeviceContext.
+ *
+ * @internal
  */
 export interface NativeHardwareDeviceContext extends Disposable {
     readonly __brand: 'NativeHardwareDeviceContext';
+    readonly type: AVHWDeviceType;
+    readonly hwctx: bigint | null;
     alloc(type: AVHWDeviceType): void;
     init(): number;
     create(type: AVHWDeviceType, device: string | null, options: any | null): number;
@@ -632,8 +633,6 @@ export interface NativeHardwareDeviceContext extends Disposable {
         maxHeight: number;
     } | null;
     free(): void;
-    readonly type: AVHWDeviceType;
-    readonly hwctx: bigint | null;
     [Symbol.dispose](): void;
 }
 /**
@@ -641,9 +640,17 @@ export interface NativeHardwareDeviceContext extends Disposable {
  *
  * Hardware frames context for hardware acceleration.
  * Direct mapping to FFmpeg's AVHWFramesContext.
+ *
+ * @internal
  */
 export interface NativeHardwareFramesContext extends Disposable {
     readonly __brand: 'NativeHardwareFramesContext';
+    readonly deviceRef: NativeHardwareDeviceContext | null;
+    format: AVPixelFormat;
+    swFormat: AVPixelFormat;
+    width: number;
+    height: number;
+    initialPoolSize: number;
     alloc(device: NativeHardwareDeviceContext): void;
     init(): number;
     getBuffer(frame: NativeFrame, flags?: number): number;
@@ -652,16 +659,15 @@ export interface NativeHardwareFramesContext extends Disposable {
     map(dst: NativeFrame, src: NativeFrame, flags?: number): number;
     createDerived(format: AVPixelFormat, derivedDevice: NativeHardwareDeviceContext, source: NativeHardwareFramesContext, flags?: number): number;
     free(): void;
-    format: AVPixelFormat;
-    swFormat: AVPixelFormat;
-    width: number;
-    height: number;
-    initialPoolSize: number;
-    readonly deviceRef: NativeHardwareDeviceContext | null;
     [Symbol.dispose](): void;
 }
 /**
- * Native BitStreamFilter (avcodec)
+ * Native AVBitStreamFilter binding interface
+ *
+ * Represents a bitstream filter definition for modifying packet data.
+ * This is an immutable descriptor - actual filtering happens via BitStreamFilterContext.
+ * Used for tasks like H.264 annexb conversion, adding/removing metadata, or format adjustments.
+ *
  * @internal
  */
 export interface NativeBitStreamFilter {
@@ -670,11 +676,21 @@ export interface NativeBitStreamFilter {
     readonly codecIds: number[] | null;
 }
 /**
- * Native BitStreamFilterContext (avcodec)
+ * Native AVBSFContext binding interface
+ *
+ * The main interface for bitstream filtering operations.
+ * Processes packets without full decode/encode, modifying headers, metadata, or format.
+ * Must be allocated with a filter, initialized, and properly disposed after use.
+ *
  * @internal
  */
 export interface NativeBitStreamFilterContext extends Disposable {
     readonly __brand: 'NativeBitStreamFilterContext';
+    readonly inputCodecParameters: NativeCodecParameters | null;
+    readonly outputCodecParameters: NativeCodecParameters | null;
+    readonly outputTimeBase: IRational | null;
+    readonly filter: NativeBitStreamFilter | null;
+    inputTimeBase: IRational;
     alloc(filter: NativeBitStreamFilter): number;
     init(): number;
     free(): void;
@@ -682,11 +698,6 @@ export interface NativeBitStreamFilterContext extends Disposable {
     sendPacket(packet: NativePacket | null): Promise<number>;
     receivePacket(packet: NativePacket): Promise<number>;
     isInitialized(): boolean;
-    readonly inputCodecParameters: NativeCodecParameters | null;
-    readonly outputCodecParameters: NativeCodecParameters | null;
-    inputTimeBase: IRational;
-    readonly outputTimeBase: IRational | null;
-    readonly filter: NativeBitStreamFilter | null;
     [Symbol.dispose](): void;
 }
 /**
@@ -721,6 +732,7 @@ export interface NativeOption {
 }
 /**
  * Interface for classes that wrap native objects
+ *
  * @internal
  */
 export interface NativeWrapper<T> {

package/dist/lib/native-types.js

@@ -5,14 +5,7 @@
  * This file contains all TypeScript interfaces for the native C++ FFmpeg bindings.
  * These interfaces represent the exact API surface exposed by the C++ layer.
  *
- * IMPORTANT:
- * - These are internal interfaces - users should use the wrapper classes in lib/
- * - All interfaces map 1:1 to C++ binding implementations
- * - Properties marked as readonly only have getters in C++
- * - Resource-owning classes provide both free() and Symbol.dispose for cleanup
- *
  * @internal
- * @packageDocumentation
  */
 export {};
 //# sourceMappingURL=native-types.js.map

package/dist/lib/native-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"native-types.js","sourceRoot":"","sources":["../../src/lib/native-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"native-types.js","sourceRoot":"","sources":["../../src/lib/native-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}