node-av 1.1.0 → 1.2.0

package/dist/lib/bitstream-filter.d.ts

@@ -1,11 +1,12 @@
 import type { AVCodecID } from '../constants/constants.js';
 import type { NativeBitStreamFilter, NativeWrapper } from './native-types.js';
 /**
- * Bitstream filter definition.
+ * Bitstream filter descriptor.
  *
- * Represents a bitstream filter for manipulating encoded data without decoding.
- * Allows modification of codec-specific headers, packet metadata, and bitstream syntax.
- * This is an immutable descriptor - actual filtering happens via BitStreamFilterContext.
+ * Provides access to bitstream filter properties and codec compatibility information.
+ * Bitstream filters are used to modify or analyze compressed bitstreams without
+ * full decoding/encoding. Common uses include H.264/HEVC parameter set extraction,
+ * VP9 superframe splitting, and adding/removing codec-specific headers.
  *
  * Direct mapping to FFmpeg's AVBitStreamFilter.
  *
@@ -13,111 +14,124 @@ import type { NativeBitStreamFilter, NativeWrapper } from './native-types.js';
  * ```typescript
  * import { BitStreamFilter } from 'node-av';
  *
- * // Find a specific bitstream filter
- * const h264Mp4ToAnnexB = BitStreamFilter.getByName('h264_mp4toannexb');
- * if (!h264Mp4ToAnnexB) throw new Error('h264_mp4toannexb filter not found');
- *
- * console.log(`Filter: ${h264Mp4ToAnnexB.name}`);
- * console.log(`Supported codecs: ${h264Mp4ToAnnexB.codecIds}`);
+ * // Get a specific bitstream filter
+ * const h264Filter = BitStreamFilter.getByName('h264_mp4toannexb');
+ * if (h264Filter) {
+ *   console.log(`Filter: ${h264Filter.name}`);
+ *   console.log(`Supported codecs: ${h264Filter.codecIds}`);
+ * }
  *
  * // List all available bitstream filters
  * const filters = BitStreamFilter.iterate();
  * for (const filter of filters) {
- *   console.log(`Found filter: ${filter.name}`);
+ *   console.log(`- ${filter.name}`);
  * }
  * ```
+ *
+ * @see [AVBitStreamFilter](https://ffmpeg.org/doxygen/trunk/structAVBitStreamFilter.html) - FFmpeg Doxygen
  */
 export declare class BitStreamFilter implements NativeWrapper<NativeBitStreamFilter> {
     private native;
     /**
-     * Create a BitStreamFilter wrapper.
-     *
-     * Usually not called directly - use static methods instead.
-     * No FFmpeg resources are allocated.
-     *
-     * @param native - Native BitStreamFilter object from bindings
+     * @param native The native bitstream filter instance
      * @internal
      */
     constructor(native: NativeBitStreamFilter);
     /**
-     * Find a bitstream filter by name.
+     * Get a bitstream filter by name.
      *
-     * Searches for a registered bitstream filter with the given name.
-     * Returns null if no filter with that name exists.
+     * Retrieves a specific bitstream filter descriptor by its name.
+     * Common filter names include 'h264_mp4toannexb', 'hevc_mp4toannexb',
+     * 'extract_extradata', 'vp9_superframe', etc.
      *
-     * Calls av_bsf_get_by_name() internally.
+     * Direct mapping to av_bsf_get_by_name().
      *
-     * @param name - Name of the bitstream filter (e.g., 'h264_mp4toannexb')
-     * @returns BitStreamFilter if found, null otherwise
+     * @param name - Name of the bitstream filter
+     * @returns BitStreamFilter instance if found, null otherwise
      *
      * @example
      * ```typescript
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * if (filter) {
-     *   console.log(`Found filter: ${filter.name}`);
+     * // Get H.264 stream format converter
+     * const h264Filter = BitStreamFilter.getByName('h264_mp4toannexb');
+     * if (!h264Filter) {
+     *   throw new Error('H.264 bitstream filter not available');
      * }
+     *
+     * // Get HEVC metadata extractor
+     * const hevcFilter = BitStreamFilter.getByName('hevc_metadata');
      * ```
+     *
+     * @see {@link iterate} To list all available filters
+     * @see {@link BitStreamFilterContext.alloc} To use the filter
      */
     static getByName(name: string): BitStreamFilter | null;
     /**
-     * Get all available bitstream filters.
+     * Iterate over all available bitstream filters.
      *
-     * Returns an array of all registered bitstream filters.
-     * Useful for discovery and debugging.
+     * Returns an array of all registered bitstream filters in FFmpeg.
+     * Useful for discovering available filters or building filter lists.
      *
-     * Calls av_bsf_iterate() internally.
+     * Direct mapping to av_bsf_iterate().
      *
      * @returns Array of all available bitstream filters
      *
      * @example
      * ```typescript
+     * import { BitStreamFilter } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * // List all available filters
      * const filters = BitStreamFilter.iterate();
-     * for (const filter of filters) {
-     *   console.log(`${filter.name}: ${filter.codecIds?.join(', ') || 'all codecs'}`);
+     * console.log(`Found ${filters.length} bitstream filters`);
+     *
+     * // Find filters that support H.264
+     * const h264Filters = filters.filter(f =>
+     *   f.codecIds?.includes(AV_CODEC_ID_H264)
+     * );
+     * console.log('H.264 compatible filters:');
+     * for (const filter of h264Filters) {
+     *   console.log(`- ${filter.name}`);
      * }
      * ```
+     *
+     * @see {@link getByName} To get a specific filter
      */
     static iterate(): BitStreamFilter[];
     /**
-     * Filter name.
+     * Name of the bitstream filter.
      *
-     * Short name used to identify the filter.
-     * This is the name used with getByName().
+     * Human-readable name identifying the filter (e.g., 'h264_mp4toannexb').
      *
-     * Maps to AVBitStreamFilter->name.
-     *
-     * @example
-     * ```typescript
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * console.log(filter.name); // 'h264_mp4toannexb'
-     * ```
+     * Direct mapping to AVBitStreamFilter->name.
      */
     get name(): string | null;
     /**
-     * Supported codec IDs.
+     * List of supported codec IDs.
      *
-     * List of codec IDs this filter can process.
-     * If null, the filter works with any codec.
+     * Array of codec IDs that this filter can process.
+     * If null, the filter supports all codecs.
      *
-     * Maps to AVBitStreamFilter->codec_ids.
+     * Direct mapping to AVBitStreamFilter->codec_ids.
      *
      * @example
      * ```typescript
-     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
-     *
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * if (filter.codecIds?.includes(AV_CODEC_ID_H264)) {
-     *   console.log('Filter supports H.264');
+     * import { AV_CODEC_ID_H264, AV_CODEC_ID_HEVC } from 'node-av/constants';
+     *
+     * const filter = BitStreamFilter.getByName('extract_extradata');
+     * if (filter?.codecIds) {
+     *   const supportsH264 = filter.codecIds.includes(AV_CODEC_ID_H264);
+     *   const supportsHEVC = filter.codecIds.includes(AV_CODEC_ID_HEVC);
+     *   console.log(`H.264 support: ${supportsH264}`);
+     *   console.log(`HEVC support: ${supportsHEVC}`);
      * }
      * ```
      */
     get codecIds(): AVCodecID[] | null;
     /**
-     * Get the underlying native object.
+     * Get the underlying native BitStreamFilter object.
      *
-     * For advanced use cases that need direct access to the native bindings.
+     * @returns The native BitStreamFilter binding object
      *
-     * @returns Native BitStreamFilter object
      * @internal
      */
     getNative(): NativeBitStreamFilter;

package/dist/lib/bitstream-filter.js

@@ -1,10 +1,11 @@
 import { bindings } from './binding.js';
 /**
- * Bitstream filter definition.
+ * Bitstream filter descriptor.
  *
- * Represents a bitstream filter for manipulating encoded data without decoding.
- * Allows modification of codec-specific headers, packet metadata, and bitstream syntax.
- * This is an immutable descriptor - actual filtering happens via BitStreamFilterContext.
+ * Provides access to bitstream filter properties and codec compatibility information.
+ * Bitstream filters are used to modify or analyze compressed bitstreams without
+ * full decoding/encoding. Common uses include H.264/HEVC parameter set extraction,
+ * VP9 superframe splitting, and adding/removing codec-specific headers.
  *
  * Direct mapping to FFmpeg's AVBitStreamFilter.
  *
@@ -12,111 +13,125 @@ import { bindings } from './binding.js';
  * ```typescript
  * import { BitStreamFilter } from 'node-av';
  *
- * // Find a specific bitstream filter
- * const h264Mp4ToAnnexB = BitStreamFilter.getByName('h264_mp4toannexb');
- * if (!h264Mp4ToAnnexB) throw new Error('h264_mp4toannexb filter not found');
- *
- * console.log(`Filter: ${h264Mp4ToAnnexB.name}`);
- * console.log(`Supported codecs: ${h264Mp4ToAnnexB.codecIds}`);
+ * // Get a specific bitstream filter
+ * const h264Filter = BitStreamFilter.getByName('h264_mp4toannexb');
+ * if (h264Filter) {
+ *   console.log(`Filter: ${h264Filter.name}`);
+ *   console.log(`Supported codecs: ${h264Filter.codecIds}`);
+ * }
  *
  * // List all available bitstream filters
  * const filters = BitStreamFilter.iterate();
  * for (const filter of filters) {
- *   console.log(`Found filter: ${filter.name}`);
+ *   console.log(`- ${filter.name}`);
  * }
  * ```
+ *
+ * @see [AVBitStreamFilter](https://ffmpeg.org/doxygen/trunk/structAVBitStreamFilter.html) - FFmpeg Doxygen
  */
 export class BitStreamFilter {
     native;
     /**
-     * Create a BitStreamFilter wrapper.
-     *
-     * Usually not called directly - use static methods instead.
-     * No FFmpeg resources are allocated.
-     *
-     * @param native - Native BitStreamFilter object from bindings
+     * @param native The native bitstream filter instance
      * @internal
      */
     constructor(native) {
         this.native = native;
     }
     /**
-     * Find a bitstream filter by name.
+     * Get a bitstream filter by name.
      *
-     * Searches for a registered bitstream filter with the given name.
-     * Returns null if no filter with that name exists.
+     * Retrieves a specific bitstream filter descriptor by its name.
+     * Common filter names include 'h264_mp4toannexb', 'hevc_mp4toannexb',
+     * 'extract_extradata', 'vp9_superframe', etc.
      *
-     * Calls av_bsf_get_by_name() internally.
+     * Direct mapping to av_bsf_get_by_name().
      *
-     * @param name - Name of the bitstream filter (e.g., 'h264_mp4toannexb')
-     * @returns BitStreamFilter if found, null otherwise
+     * @param name - Name of the bitstream filter
+     * @returns BitStreamFilter instance if found, null otherwise
      *
      * @example
      * ```typescript
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * if (filter) {
-     *   console.log(`Found filter: ${filter.name}`);
+     * // Get H.264 stream format converter
+     * const h264Filter = BitStreamFilter.getByName('h264_mp4toannexb');
+     * if (!h264Filter) {
+     *   throw new Error('H.264 bitstream filter not available');
      * }
+     *
+     * // Get HEVC metadata extractor
+     * const hevcFilter = BitStreamFilter.getByName('hevc_metadata');
      * ```
+     *
+     * @see {@link iterate} To list all available filters
+     * @see {@link BitStreamFilterContext.alloc} To use the filter
      */
     static getByName(name) {
         const native = bindings.BitStreamFilter.getByName(name);
         return native ? new BitStreamFilter(native) : null;
     }
     /**
-     * Get all available bitstream filters.
+     * Iterate over all available bitstream filters.
      *
-     * Returns an array of all registered bitstream filters.
-     * Useful for discovery and debugging.
+     * Returns an array of all registered bitstream filters in FFmpeg.
+     * Useful for discovering available filters or building filter lists.
      *
-     * Calls av_bsf_iterate() internally.
+     * Direct mapping to av_bsf_iterate().
      *
      * @returns Array of all available bitstream filters
      *
      * @example
      * ```typescript
+     * import { BitStreamFilter } from 'node-av';
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * // List all available filters
      * const filters = BitStreamFilter.iterate();
-     * for (const filter of filters) {
-     *   console.log(`${filter.name}: ${filter.codecIds?.join(', ') || 'all codecs'}`);
+     * console.log(`Found ${filters.length} bitstream filters`);
+     *
+     * // Find filters that support H.264
+     * const h264Filters = filters.filter(f =>
+     *   f.codecIds?.includes(AV_CODEC_ID_H264)
+     * );
+     * console.log('H.264 compatible filters:');
+     * for (const filter of h264Filters) {
+     *   console.log(`- ${filter.name}`);
      * }
      * ```
+     *
+     * @see {@link getByName} To get a specific filter
      */
     static iterate() {
         const natives = bindings.BitStreamFilter.iterate();
         return natives.map((native) => new BitStreamFilter(native));
     }
     /**
-     * Filter name.
+     * Name of the bitstream filter.
      *
-     * Short name used to identify the filter.
-     * This is the name used with getByName().
+     * Human-readable name identifying the filter (e.g., 'h264_mp4toannexb').
      *
-     * Maps to AVBitStreamFilter->name.
-     *
-     * @example
-     * ```typescript
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * console.log(filter.name); // 'h264_mp4toannexb'
-     * ```
+     * Direct mapping to AVBitStreamFilter->name.
      */
     get name() {
         return this.native.name;
     }
     /**
-     * Supported codec IDs.
+     * List of supported codec IDs.
      *
-     * List of codec IDs this filter can process.
-     * If null, the filter works with any codec.
+     * Array of codec IDs that this filter can process.
+     * If null, the filter supports all codecs.
      *
-     * Maps to AVBitStreamFilter->codec_ids.
+     * Direct mapping to AVBitStreamFilter->codec_ids.
      *
      * @example
      * ```typescript
-     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
-     *
-     * const filter = BitStreamFilter.getByName('h264_mp4toannexb');
-     * if (filter.codecIds?.includes(AV_CODEC_ID_H264)) {
-     *   console.log('Filter supports H.264');
+     * import { AV_CODEC_ID_H264, AV_CODEC_ID_HEVC } from 'node-av/constants';
+     *
+     * const filter = BitStreamFilter.getByName('extract_extradata');
+     * if (filter?.codecIds) {
+     *   const supportsH264 = filter.codecIds.includes(AV_CODEC_ID_H264);
+     *   const supportsHEVC = filter.codecIds.includes(AV_CODEC_ID_HEVC);
+     *   console.log(`H.264 support: ${supportsH264}`);
+     *   console.log(`HEVC support: ${supportsHEVC}`);
      * }
      * ```
      */
@@ -124,11 +139,10 @@ export class BitStreamFilter {
         return this.native.codecIds;
     }
     /**
-     * Get the underlying native object.
+     * Get the underlying native BitStreamFilter object.
      *
-     * For advanced use cases that need direct access to the native bindings.
+     * @returns The native BitStreamFilter binding object
      *
-     * @returns Native BitStreamFilter object
      * @internal
      */
     getNative() {

package/dist/lib/bitstream-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"bitstream-filter.js","sourceRoot":"","sources":["../../src/lib/bitstream-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,eAAe;IAClB,MAAM,CAAwB;IAEtC;;;;;;;;OAQG;IACH,YAAY,MAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,SAAS,CAAC,IAAY;QAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,OAAO;QACZ,MAAM,OAAO,GAAG,QAAQ,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAA6B,EAAE,EAAE,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAA8B,CAAC;IACpD,CAAC;IAED;;;;;;;OAOG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"bitstream-filter.js","sourceRoot":"","sources":["../../src/lib/bitstream-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,eAAe;IAClB,MAAM,CAAwB;IAEtC;;;OAGG;IACH,YAAY,MAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,SAAS,CAAC,IAAY;QAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,OAAO;QACZ,MAAM,OAAO,GAAG,QAAQ,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAA6B,EAAE,EAAE,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;OAMG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAA8B,CAAC;IACpD,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}