node-av 0.0.1

package/dist/lib/codec.js

@@ -0,0 +1,492 @@
+import { bindings } from './binding.js';
+import { Rational } from './rational.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 class Codec {
+    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) {
+        this.native = native;
+    }
+    /**
+     * Create a Codec instance from a native codec object.
+     * @internal Used by the bindings layer
+     */
+    static fromNative(native) {
+        if (!native)
+            return null;
+        return new Codec(native);
+    }
+    /**
+     * 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) {
+        const native = bindings.Codec.findDecoder(id);
+        return native ? new Codec(native) : 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) {
+        const native = bindings.Codec.findDecoderByName(name);
+        return native ? new Codec(native) : 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) {
+        const native = bindings.Codec.findEncoder(id);
+        return native ? new Codec(native) : 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) {
+        const native = bindings.Codec.findEncoderByName(name);
+        return native ? new Codec(native) : 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() {
+        const natives = bindings.Codec.getCodecList();
+        return natives.map((n) => new Codec(n));
+    }
+    /**
+     * 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 = null) {
+        const result = bindings.Codec.iterateCodecs(opaque);
+        if (!result)
+            return null;
+        return {
+            codec: new Codec(result.codec),
+            opaque: result.opaque,
+        };
+    }
+    /**
+     * 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() {
+        return this.native.name;
+    }
+    /**
+     * 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() {
+        return this.native.longName;
+    }
+    /**
+     * Media type handled by this codec.
+     *
+     * Direct mapping to AVCodec->type
+     * AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_SUBTITLE, etc.
+     */
+    get type() {
+        return this.native.type;
+    }
+    /**
+     * Codec ID.
+     *
+     * Direct mapping to AVCodec->id
+     * Unique identifier for this codec type (AV_CODEC_ID_H264, AV_CODEC_ID_AAC, etc.)
+     */
+    get id() {
+        return this.native.id;
+    }
+    /**
+     * Codec capabilities.
+     *
+     * Direct mapping to AVCodec->capabilities
+     * Bitfield of AV_CODEC_CAP_* flags describing codec features.
+     */
+    get capabilities() {
+        return this.native.capabilities;
+    }
+    /**
+     * 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() {
+        return this.native.maxLowres;
+    }
+    /**
+     * 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() {
+        return this.native.profiles;
+    }
+    /**
+     * 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() {
+        return this.native.wrapper;
+    }
+    /**
+     * 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() {
+        const rates = this.native.supportedFramerates;
+        if (!rates)
+            return null;
+        return rates.map((r) => new Rational(r.num, r.den));
+    }
+    /**
+     * 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() {
+        return this.native.pixelFormats;
+    }
+    /**
+     * 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() {
+        return this.native.supportedSamplerates;
+    }
+    /**
+     * 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() {
+        return this.native.sampleFormats;
+    }
+    /**
+     * 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() {
+        return this.native.channelLayouts;
+    }
+    /**
+     * 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() {
+        return this.native.isEncoder();
+    }
+    /**
+     * 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() {
+        return this.native.isDecoder();
+    }
+    /**
+     * 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() {
+        return this.native.isExperimental();
+    }
+    /**
+     * 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) {
+        return this.native.getHwConfig(index);
+    }
+    /**
+     * Get the native codec object for use with C++ bindings
+     * @internal
+     */
+    getNative() {
+        return this.native;
+    }
+}
+//# sourceMappingURL=codec.js.map

package/dist/lib/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/lib/codec.ts"],"names":[],"mappings":"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"}