node-av 0.0.1

package/dist/lib/codec-parser.js

@@ -0,0 +1,193 @@
+import { bindings } from './binding.js';
+/**
+ * Codec parser for splitting elementary streams into frames.
+ *
+ * Parsers split raw byte streams (currently only video) into coded frames.
+ * Many decoders require that coded video frames are preceded by a start code,
+ * and this parser splits the stream at these boundaries. Parsers are essential
+ * for handling raw elementary streams from sources like network streams or
+ * raw video files without container format.
+ *
+ * Direct wrapper around AVCodecParserContext.
+ *
+ * @example
+ * ```typescript
+ * import { CodecParser, CodecContext, Packet, FFmpegError } from 'node-av';
+ * import { AV_CODEC_ID_H264, AV_NOPTS_VALUE } from 'node-av/constants';
+ *
+ * const parser = new CodecParser();
+ * parser.init(AV_CODEC_ID_H264);
+ *
+ * // Parse raw H.264 stream
+ * const packet = new Packet();
+ * packet.alloc();
+ *
+ * const bytesConsumed = parser.parse2(
+ *   codecContext,
+ *   packet,
+ *   inputBuffer,
+ *   AV_NOPTS_VALUE,
+ *   AV_NOPTS_VALUE,
+ *   0
+ * );
+ *
+ * if (packet.size > 0) {
+ *   // We have a complete frame in packet
+ *   const ret = await codecContext.sendPacket(packet);
+ *   FFmpegError.throwIfError(ret, 'sendPacket');
+ * }
+ *
+ * parser.close();
+ * ```
+ *
+ * @see {@link CodecContext} For decoding parsed packets
+ * @see {@link Packet} For storing parsed frame data
+ */
+export class CodecParser {
+    native;
+    /**
+     * Create a new CodecParser instance.
+     *
+     * The parser is uninitialized - you must call init() before use.
+     * No FFmpeg resources are allocated until init() is called.
+     *
+     * Direct wrapper around AVCodecParserContext allocation.
+     *
+     * @example
+     * ```typescript
+     * import { CodecParser } from 'node-av';
+     * import { AV_CODEC_ID_MPEG1VIDEO } from 'node-av/constants';
+     *
+     * const parser = new CodecParser();
+     * parser.init(AV_CODEC_ID_MPEG1VIDEO);
+     * // parser is now ready for use
+     * ```
+     */
+    constructor() {
+        this.native = new bindings.CodecParser();
+    }
+    /**
+     * Initialize the parser with a specific codec ID.
+     *
+     * Allocates and initializes the AVCodecParserContext for the specified codec.
+     * Must be called before parse2() can be used.
+     *
+     * Direct mapping to av_parser_init()
+     *
+     * @param codecId - AVCodecID of the codec to parse
+     *
+     * @throws {Error} Parser for codec ID not found
+     *
+     * @example
+     * ```typescript
+     * import { CodecParser } from 'node-av';
+     * import { AV_CODEC_ID_H264, AV_CODEC_ID_HEVC } from 'node-av/constants';
+     *
+     * const parser = new CodecParser();
+     *
+     * // Initialize for H.264
+     * parser.init(AV_CODEC_ID_H264);
+     * // Parser is now ready to parse H.264 streams
+     *
+     * // For HEVC/H.265
+     * const hevcParser = new CodecParser();
+     * hevcParser.init(AV_CODEC_ID_HEVC);
+     * ```
+     *
+     * @see {@link parse2} For parsing data after initialization
+     */
+    init(codecId) {
+        this.native.init(codecId);
+    }
+    /**
+     * Parse a buffer and extract packets from elementary stream.
+     *
+     * Parses the input buffer and extracts complete coded frames. The parser
+     * maintains internal state to handle partial frames across multiple calls.
+     * The parser may combine multiple frames into one packet or split one frame
+     * into multiple packets, depending on the codec and stream format.
+     *
+     * Direct mapping to av_parser_parse2()
+     *
+     * @param codecContext - Codec context (used for stream parameters)
+     * @param packet - Packet to fill with parsed data
+     * @param data - Input buffer containing elementary stream data
+     * @param pts - Presentation timestamp of the first byte in data
+     * @param dts - Decoding timestamp of the first byte in data
+     * @param pos - Byte position of the first byte in data in the stream
+     *
+     * @returns Number of bytes consumed from the input buffer:
+     *   - >0: Number of bytes consumed from input
+     *   - 0: More data needed to complete a frame
+     *
+     * @example
+     * ```typescript
+     * import { CodecParser, CodecContext, Packet, FFmpegError } from 'node-av';
+     * import { AV_NOPTS_VALUE } from 'node-av/constants';
+     * import * as fs from 'fs';
+     *
+     * const inbuf = Buffer.alloc(4096);
+     * const bytesRead = fs.readSync(fd, inbuf, 0, 4096, null);
+     *
+     * let offset = 0;
+     * while (offset < bytesRead) {
+     *   const consumed = parser.parse2(
+     *     codecContext,
+     *     packet,
+     *     inbuf.subarray(offset),
+     *     AV_NOPTS_VALUE,
+     *     AV_NOPTS_VALUE,
+     *     0
+     *   );
+     *
+     *   offset += consumed;
+     *
+     *   if (packet.size > 0) {
+     *     // Complete packet ready for decoding
+     *     const ret = await codecContext.sendPacket(packet);
+     *     FFmpegError.throwIfError(ret, 'sendPacket');
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link init} Must be called before parse2
+     * @see {@link close} Should be called when done parsing
+     */
+    parse2(codecContext, packet, data, pts, dts, pos) {
+        return this.native.parse2(codecContext.getNative(), packet.getNative(), data, pts, dts, pos);
+    }
+    /**
+     * Close the parser and free all resources.
+     *
+     * Releases all resources associated with the parser context.
+     * After calling close(), the parser instance should not be used anymore.
+     *
+     * Direct mapping to av_parser_close()
+     *
+     * @example
+     * ```typescript
+     * import { CodecParser } from 'node-av';
+     *
+     * const parser = new CodecParser();
+     * // ... use parser ...
+     *
+     * parser.close();
+     * // Parser resources are now freed
+     * // Do not use parser after this point
+     * ```
+     */
+    close() {
+        this.native.close();
+    }
+    /**
+     * @internal
+     * Get the underlying native codec parser object.
+     * This method is for internal use by other FFmpeg classes.
+     *
+     * @returns The underlying native codec parser object
+     */
+    getNative() {
+        return this.native;
+    }
+}
+//# sourceMappingURL=codec-parser.js.map

package/dist/lib/codec-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-parser.js","sourceRoot":"","sources":["../../src/lib/codec-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAOxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAoB;IAElC;;;;;;;;;;;;;;;;;OAiBG;IACH;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAI,CAAC,OAAkB;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,MAAM,CAAC,YAA0B,EAAE,MAAc,EAAE,IAAY,EAAE,GAAW,EAAE,GAAW,EAAE,GAAW;QACpG,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC/F,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/lib/codec.d.ts

@@ -0,0 +1,432 @@
+import { Rational } from './rational.js';
+import type { AVCodecCap, AVCodecID, AVHWDeviceType, AVMediaType, AVPixelFormat, AVSampleFormat } from './constants.js';
+import type { NativeCodec, NativeWrapper } from './native-types.js';
+import type { ChannelLayout, CodecProfile } from './types.js';
+/**
+ * Codec (encoder/decoder) definition.
+ *
+ * Represents a codec implementation for encoding or decoding media.
+ * Provides codec information, capabilities, and supported formats.
+ * This is an immutable descriptor - actual encoding/decoding happens via CodecContext.
+ *
+ * Direct mapping to FFmpeg's AVCodec.
+ *
+ * @example
+ * ```typescript
+ * import { Codec } from 'node-av';
+ * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+ *
+ * // Find decoder by ID
+ * const h264Decoder = Codec.findDecoder(AV_CODEC_ID_H264);
+ * if (!h264Decoder) throw new Error('H264 decoder not found');
+ *
+ * // Find encoder by name
+ * const x264Encoder = Codec.findEncoderByName('libx264');
+ * if (!x264Encoder) throw new Error('x264 encoder not found');
+ *
+ * // Check codec capabilities
+ * console.log(`Codec: ${h264Decoder.name}`);
+ * console.log(`Long name: ${h264Decoder.longName}`);
+ * console.log(`Type: ${h264Decoder.type}`);
+ * console.log(`Is decoder: ${h264Decoder.isDecoder()}`);
+ *
+ * // Get supported formats
+ * const pixelFormats = h264Decoder.pixelFormats;
+ * console.log(`Supported pixel formats: ${pixelFormats}`);
+ *
+ * // Iterate through all codecs
+ * let iter = null;
+ * while (true) {
+ *   const result = Codec.iterateCodecs(iter);
+ *   if (!result) break;
+ *   console.log(`Found codec: ${result.codec.name}`);
+ *   iter = result.opaque;
+ * }
+ * ```
+ */
+export declare class Codec implements NativeWrapper<NativeCodec> {
+    private native;
+    /**
+     * Constructor is internal - use static factory methods.
+     *
+     * Codecs are global immutable objects managed by FFmpeg.
+     * Use the static find methods to obtain codec instances.
+     *
+     * @internal
+     *
+     * @param native - Native AVCodec to wrap
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * // Don't use constructor directly
+     * // const codec = new Codec(); // Wrong
+     *
+     * // Use static factory methods instead
+     * const decoder = Codec.findDecoder(AV_CODEC_ID_H264); // Correct
+     * const encoder = Codec.findEncoderByName('libx264'); // Correct
+     * ```
+     */
+    constructor(native: NativeCodec);
+    /**
+     * Create a Codec instance from a native codec object.
+     * @internal Used by the bindings layer
+     */
+    static fromNative(native: NativeCodec | null): Codec | null;
+    /**
+     * Find a registered decoder with a matching codec ID.
+     *
+     * Searches for a decoder that can decode the specified codec format.
+     *
+     * Direct mapping to avcodec_find_decoder()
+     *
+     * @param id - AVCodecID of the requested decoder
+     *
+     * @returns Codec object or null if no decoder found
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * const decoder = Codec.findDecoder(AV_CODEC_ID_H264);
+     * if (!decoder) {
+     *   throw new Error('H.264 decoder not available');
+     * }
+     * ```
+     *
+     * @see {@link findDecoderByName} To find by name
+     * @see {@link findEncoder} To find encoder
+     */
+    static findDecoder(id: AVCodecID): Codec | null;
+    /**
+     * Find a registered decoder with the specified name.
+     *
+     * Searches for a decoder by its exact name.
+     * Useful for selecting specific decoder implementations.
+     *
+     * Direct mapping to avcodec_find_decoder_by_name()
+     *
+     * @param name - Name of the requested decoder
+     *
+     * @returns Codec object or null if no decoder found
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     *
+     * const decoder = Codec.findDecoderByName('h264');
+     * // Can also use specific implementations:
+     * const cudaDecoder = Codec.findDecoderByName('h264_cuvid'); // NVIDIA hardware decoder
+     * ```
+     *
+     * @see {@link findDecoder} To find by codec ID
+     */
+    static findDecoderByName(name: string): Codec | null;
+    /**
+     * Find a registered encoder with a matching codec ID.
+     *
+     * Searches for an encoder that can encode to the specified codec format.
+     *
+     * Direct mapping to avcodec_find_encoder()
+     *
+     * @param id - AVCodecID of the requested encoder
+     *
+     * @returns Codec object or null if no encoder found
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * const encoder = Codec.findEncoder(AV_CODEC_ID_H264);
+     * if (!encoder) {
+     *   throw new Error('H.264 encoder not available');
+     * }
+     * ```
+     *
+     * @see {@link findEncoderByName} To find by name
+     * @see {@link findDecoder} To find decoder
+     */
+    static findEncoder(id: AVCodecID): Codec | null;
+    /**
+     * Find a registered encoder with the specified name.
+     *
+     * Searches for an encoder by its exact name.
+     * Useful for selecting specific encoder implementations.
+     *
+     * Direct mapping to avcodec_find_encoder_by_name()
+     *
+     * @param name - Name of the requested encoder
+     *
+     * @returns Codec object or null if no encoder found
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     *
+     * // Find specific encoder implementation
+     * const x264 = Codec.findEncoderByName('libx264');    // Software H.264 encoder
+     * const nvenc = Codec.findEncoderByName('h264_nvenc'); // NVIDIA hardware encoder
+     * const vaapi = Codec.findEncoderByName('h264_vaapi'); // VAAPI hardware encoder
+     * ```
+     *
+     * @see {@link findEncoder} To find by codec ID
+     */
+    static findEncoderByName(name: string): Codec | null;
+    /**
+     * Get list of all available codecs.
+     *
+     * Returns all registered codecs in the system.
+     * Internally uses av_codec_iterate() to collect all codecs.
+     *
+     * @returns Array of all registered codecs
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AVMEDIA_TYPE_VIDEO } from 'node-av/constants';
+     *
+     * const codecs = Codec.getCodecList();
+     * const videoEncoders = codecs.filter(c =>
+     *   c.type === AVMEDIA_TYPE_VIDEO && c.isEncoder()
+     * );
+     * console.log(`Found ${videoEncoders.length} video encoders`);
+     * ```
+     *
+     * @note This loads all codecs at once. For large codec lists,
+     *       consider using iterateCodecs() instead.
+     *
+     * @see {@link iterateCodecs} For memory-efficient iteration
+     */
+    static getCodecList(): Codec[];
+    /**
+     * Iterate through codecs one by one.
+     *
+     * Memory-efficient codec iteration.
+     * Processes codecs one at a time instead of loading all at once.
+     *
+     * Direct mapping to av_codec_iterate()
+     *
+     * @param opaque - Iterator state (null to start, or value from previous call)
+     *
+     * @returns Object with codec and next iterator state, or null when done
+     *
+     * @example
+     * ```typescript
+     * import { Codec } from 'node-av';
+     * import { AVMEDIA_TYPE_VIDEO } from 'node-av/constants';
+     *
+     * let opaque = null;
+     * while (true) {
+     *   const result = Codec.iterateCodecs(opaque);
+     *   if (!result) break;
+     *
+     *   const codec = result.codec;
+     *   if (codec.type === AVMEDIA_TYPE_VIDEO && codec.isEncoder()) {
+     *     console.log(`Video encoder: ${codec.name}`);
+     *   }
+     *
+     *   opaque = result.opaque;
+     * }
+     * ```
+     *
+     * @see {@link getCodecList} To get all codecs at once
+     */
+    static iterateCodecs(opaque?: bigint | null): {
+        codec: Codec;
+        opaque: bigint;
+    } | null;
+    /**
+     * Short name of the codec.
+     *
+     * Direct mapping to AVCodec->name
+     * Typically matches the name of the codec specification.
+     * For example: "h264", "aac", "vp9", "opus"
+     */
+    get name(): string | null;
+    /**
+     * Descriptive name for the codec.
+     *
+     * Direct mapping to AVCodec->long_name
+     * More human-readable than name.
+     * For example: "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10"
+     */
+    get longName(): string | null;
+    /**
+     * Media type handled by this codec.
+     *
+     * Direct mapping to AVCodec->type
+     * AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_SUBTITLE, etc.
+     */
+    get type(): AVMediaType;
+    /**
+     * Codec ID.
+     *
+     * Direct mapping to AVCodec->id
+     * Unique identifier for this codec type (AV_CODEC_ID_H264, AV_CODEC_ID_AAC, etc.)
+     */
+    get id(): AVCodecID;
+    /**
+     * Codec capabilities.
+     *
+     * Direct mapping to AVCodec->capabilities
+     * Bitfield of AV_CODEC_CAP_* flags describing codec features.
+     */
+    get capabilities(): AVCodecCap;
+    /**
+     * Maximum lowres value supported by the decoder.
+     *
+     * Lowres decoding allows decoding at reduced resolution for faster preview.
+     * 0 means lowres decoding is not supported.
+     * 1 means 1/2 resolution is supported.
+     * 2 means 1/4 resolution is supported.
+     * 3 means 1/8 resolution is supported.
+     * @readonly
+     */
+    get maxLowres(): number;
+    /**
+     * Array of supported codec profiles.
+     *
+     * Profiles define subsets of codec features.
+     * For example, H.264 has Baseline, Main, High profiles.
+     * null if codec doesn't support profiles or none are defined.
+     * @readonly
+     */
+    get profiles(): CodecProfile[] | null;
+    /**
+     * Group name of the codec implementation.
+     *
+     * This is a short symbolic name of the wrapper backing this codec.
+     * For example "lavc" for internal codecs, "libopenh264" for OpenH264 wrapper.
+     * null if codec is not wrapped.
+     * @readonly
+     */
+    get wrapper(): string | null;
+    /**
+     * Supported framerates (video only).
+     *
+     * Terminated by {0,0}. null if any framerate is supported.
+     * Some codecs like MPEG-1/2 only support specific framerates.
+     * @readonly
+     */
+    get supportedFramerates(): Rational[] | null;
+    /**
+     * Array of supported pixel formats (video only).
+     *
+     * Terminated by AV_PIX_FMT_NONE. null if unknown.
+     * Lists all pixel formats this codec can encode/decode.
+     * @readonly
+     */
+    get pixelFormats(): AVPixelFormat[] | null;
+    /**
+     * Supported sample rates (audio only).
+     *
+     * Terminated by 0. null if any sample rate is supported.
+     * Common rates: 8000, 16000, 22050, 44100, 48000, 96000, 192000 Hz.
+     * @readonly
+     */
+    get supportedSamplerates(): number[] | null;
+    /**
+     * Array of supported sample formats (audio only).
+     *
+     * Terminated by AV_SAMPLE_FMT_NONE. null if unknown.
+     * Lists all sample formats this codec can encode/decode.
+     * Common formats: S16, S32, FLT, DBL (planar and interleaved variants).
+     * @readonly
+     */
+    get sampleFormats(): AVSampleFormat[] | null;
+    /**
+     * Array of supported channel layouts (audio only).
+     *
+     * Lists all channel configurations this codec supports.
+     * Common layouts: mono, stereo, 5.1, 7.1.
+     * null if unknown or all layouts are supported.
+     * @readonly
+     */
+    get channelLayouts(): ChannelLayout[] | null;
+    /**
+     * Check if the codec is an encoder.
+     *
+     * Direct mapping to av_codec_is_encoder()
+     *
+     * @returns true if the codec is an encoder, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const codec = Codec.findEncoderByName('libx264');
+     * if (codec && codec.isEncoder()) {
+     *   console.log('Found H.264 encoder');
+     * }
+     * ```
+     */
+    isEncoder(): boolean;
+    /**
+     * Check if the codec is a decoder.
+     *
+     * Direct mapping to av_codec_is_decoder()
+     *
+     * @returns true if the codec is a decoder, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const codec = Codec.findDecoder(AV_CODEC_ID_H264);
+     * if (codec && codec.isDecoder()) {
+     *   console.log('Found H.264 decoder');
+     * }
+     * ```
+     */
+    isDecoder(): boolean;
+    /**
+     * Check if the codec is experimental.
+     *
+     * Experimental codecs require explicit allowance to use.
+     * You must set strict_std_compliance to FF_COMPLIANCE_EXPERIMENTAL
+     * or lower in the codec context to use experimental codecs.
+     *
+     * @returns true if the codec is experimental, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const codec = Codec.findEncoderByName('some_experimental_codec');
+     * if (codec && codec.isExperimental()) {
+     *   console.warn('This codec is experimental and may not be stable');
+     *   // codecContext.strict_std_compliance = FF_COMPLIANCE_EXPERIMENTAL;
+     * }
+     * ```
+     */
+    isExperimental(): boolean;
+    /**
+     * Get hardware configuration at specified index.
+     *
+     * Direct mapping to avcodec_get_hw_config()
+     *
+     * @param index - Configuration index (0-based)
+     * @returns Hardware configuration or null if not available
+     *
+     * @example
+     * ```typescript
+     * const codec = Codec.findDecoder(AV_CODEC_ID_H264);
+     * for (let i = 0; ; i++) {
+     *   const config = codec.getHwConfig(i);
+     *   if (!config) break;
+     *
+     *   if (config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX) {
+     *     console.log(`Supports device type: ${config.deviceType}`);
+     *   }
+     * }
+     * ```
+     */
+    getHwConfig(index: number): {
+        pixFmt: AVPixelFormat;
+        methods: number;
+        deviceType: AVHWDeviceType;
+    } | null;
+    /**
+     * Get the native codec object for use with C++ bindings
+     * @internal
+     */
+    getNative(): NativeCodec;
+}