node-av 1.3.0 → 2.0.0

package/README.md

@@ -34,46 +34,45 @@ await using input = await MediaInput.open('input.mp4');
 await using output = await MediaOutput.open('output.mp4');
 
 // Get video stream
-const videoStream = input.video();
+const videoStream = input.video()!;
 
-// Create decoder/encoder
-using decoder = await Decoder.create(videoStream!);
-using encoder = await Encoder.create(FF_ENCODER_LIBX264, decoder.getOutputStreamInfo(), {
-  bitrate: '2M',
-  gopSize: 60,
+// Create decoder
+using decoder = await Decoder.create(videoStream);
+
+// Create encoder
+using encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+  timeBase: videoStream.timeBase,
+  frameRate: videoStream.avgFrameRate,
 });
 
 // Add stream to output
 const outputIndex = output.addStream(encoder);
-await output.writeHeader();
 
 // Process packets
-for await (const packet of input.packets()) {
-  if (packet.streamIndex === videoStream!.index) {
-    using frame = await decoder.decode(packet);
-    if (frame) {
-      using encoded = await encoder.encode(frame);
-      if (encoded) {
-        await output.writePacket(encoded, outputIndex);
-      }
+for await (using packet of input.packets(videoStream.index)) {
+  using frame = await decoder.decode(packet);
+  if (frame) {
+    using encoded = await encoder.encode(frame);
+    if (encoded) {
+      await output.writePacket(encoded, outputIndex);
     }
   }
 }
 
-// Flush decoder/encoder
-for await (const frame of decoder.flushFrames()) {
+// Flush decoder
+for await (using frame of decoder.flushFrames()) {
   using encoded = await encoder.encode(frame);
   if (encoded) {
     await output.writePacket(encoded, outputIndex);
   }
 }
 
-for await (const packet of encoder.flushPackets()) {
+// Flush encoder
+for await (using packet of encoder.flushPackets()) {
   await output.writePacket(packet, outputIndex);
 }
 
-// End
-await output.writeTrailer();
+// Done
 ```
 
 ### Pipeline API
@@ -85,9 +84,9 @@ import { pipeline, MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api
 const input = await MediaInput.open('input.mp4');
 const output = await MediaOutput.open('output.mp4');
 const decoder = await Decoder.create(input.video());
-const encoder = await Encoder.create(FF_ENCODER_LIBX264, decoder.getOutputStreamInfo(), {
-  bitrate: '2M',
-  gopSize: 60
+const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+  timeBase: videoStream.timeBase,
+  frameRate: videoStream.avgFrameRate,
 });
 
 const control = pipeline(input, decoder, encoder, output);
@@ -102,23 +101,23 @@ The library supports all hardware acceleration methods available in FFmpeg. The
 
 ```typescript
 import { HardwareContext } from 'node-av/api';
-import { FF_ENCODER_H264_VIDEOTOOLBOX } from 'node-av/constants';
+import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
 // Automatically detect best available hardware
 const hw = HardwareContext.auto();
-if (hw) {
-  console.log(`Using hardware: ${hw.deviceTypeName}`);
-  
-  // Use with decoder
-  const decoder = await Decoder.create(stream, {
-    hardware: hw
-  });
-  
-  // Use with encoder (use hardware-specific codec)
-  const encoder = await Encoder.create(FF_ENCODER_H264_VIDEOTOOLBOX, decoder.getOutputStreamInfo(), {
-    hardware: hw
-  });
-}
+console.log(`Using hardware: ${hw.deviceTypeName}`);
+
+// Use with decoder
+const decoder = await Decoder.create(stream, {
+  hardware: hw
+});
+
+// Use with encoder (use hardware-specific codec)
+const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_LIBX264;
+const encoder = await Encoder.create(encoderCodec, {
+  timeBase: videoStream.timeBase,
+  frameRate: videoStream.avgFrameRate,
+});
 ```
 
 ### Specific Hardware
@@ -288,7 +287,7 @@ This project is licensed under the MIT License. See the LICENSE file for details
 
 ## Contributing
 
-Contributions are welcome! Please read [CONTRIBUTION.md](https://github.com/seydx/av/tree/main/CONTRIBUTION.md) for development setup, code standards, and contribution guidelines before submitting pull requests.
+Contributions are welcome! Please read [CONTRIBUTING.md](https://github.com/seydx/av/tree/main/CONTRIBUTING.md) for development setup, code standards, and contribution guidelines before submitting pull requests.
 
 ## Support
 

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

@@ -164,7 +164,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * Yields filtered packets ready for output.
      *
      * @param packets - Async iterable of packets
-     * @yields Filtered packets
+     * @yields {Packet} Filtered packets
      * @throws {Error} If filter is disposed
      *
      * @throws {FFmpegError} If filtering fails
@@ -225,7 +225,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * Convenient async iteration over remaining packets.
      * Combines flush and iteration.
      *
-     * @yields Remaining packets
+     * @yields {Packet} Remaining packets
      * @throws {Error} If filter is disposed
      *
      * @example

package/dist/api/bitstream-filter.js

@@ -231,7 +231,7 @@ export class BitStreamFilterAPI {
      * Yields filtered packets ready for output.
      *
      * @param packets - Async iterable of packets
-     * @yields Filtered packets
+     * @yields {Packet} Filtered packets
      * @throws {Error} If filter is disposed
      *
      * @throws {FFmpegError} If filtering fails
@@ -324,7 +324,7 @@ export class BitStreamFilterAPI {
      * Convenient async iteration over remaining packets.
      * Combines flush and iteration.
      *
-     * @yields Remaining packets
+     * @yields {Packet} Remaining packets
      * @throws {Error} If filter is disposed
      *
      * @example

package/dist/api/decoder.d.ts

@@ -1,6 +1,6 @@
-import { CodecContext, Frame } from '../lib/index.js';
+import { Codec, CodecContext, Frame } from '../lib/index.js';
 import type { Packet, Stream } from '../lib/index.js';
-import type { DecoderOptions, StreamInfo } from './types.js';
+import type { DecoderOptions } from './types.js';
 /**
  * High-level decoder for audio and video streams.
  *
@@ -45,13 +45,15 @@ import type { DecoderOptions, StreamInfo } from './types.js';
  */
 export declare class Decoder implements Disposable {
     private codecContext;
+    private codec;
     private frame;
-    private streamIndex;
     private stream;
-    private isOpen;
+    private initialized;
+    private isClosed;
     private hardware?;
     /**
      * @param codecContext - Configured codec context
+     * @param codec - Codec being used
      * @param stream - Media stream being decoded
      * @param hardware - Optional hardware context
      * Use {@link create} factory method
@@ -120,36 +122,21 @@ export declare class Decoder implements Disposable {
      */
     get isDecoderOpen(): boolean;
     /**
-     * Get output stream information.
+     * Check if decoder has been initialized.
      *
-     * Returns format information about decoded frames.
-     * For hardware decoding, returns the hardware pixel format.
-     * Essential for configuring downstream components like encoders or filters.
+     * Returns true if decoder is initialized (true by default for decoders).
+     * Decoders are pre-initialized from stream parameters.
      *
-     * @returns Stream format information
+     * @returns true if decoder has been initialized
      *
      * @example
      * ```typescript
-     * const info = decoder.getOutputStreamInfo();
-     * if (info.type === 'video') {
-     *   console.log(`Video: ${info.width}x${info.height} @ ${info.pixelFormat}`);
-     *   console.log(`Frame rate: ${info.frameRate.num}/${info.frameRate.den}`);
+     * if (decoder.isDecoderInitialized) {
+     *   console.log('Decoder is ready to process frames');
      * }
      * ```
-     *
-     * @example
-     * ```typescript
-     * const info = decoder.getOutputStreamInfo();
-     * if (info.type === 'audio') {
-     *   console.log(`Audio: ${info.sampleRate}Hz ${info.sampleFormat}`);
-     *   console.log(`Channels: ${info.channelLayout}`);
-     * }
-     * ```
-     *
-     * @see {@link StreamInfo} For format details
-     * @see {@link Encoder.create} For matching encoder configuration
      */
-    getOutputStreamInfo(): StreamInfo;
+    get isDecoderInitialized(): boolean;
     /**
      * Check if decoder uses hardware acceleration.
      *
@@ -165,6 +152,19 @@ export declare class Decoder implements Disposable {
      * @see {@link HardwareContext} For hardware setup
      */
     isHardware(): boolean;
+    /**
+     * Check if decoder is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (decoder.isReady()) {
+     *   const frame = await decoder.decode(packet);
+     * }
+     * ```
+     */
+    isReady(): boolean;
     /**
      * Decode a packet to a frame.
      *
@@ -193,7 +193,7 @@ export declare class Decoder implements Disposable {
      * @example
      * ```typescript
      * for await (const packet of input.packets()) {
-     *   if (packet.streamIndex === decoder.getStreamIndex()) {
+     *   if (packet.streamIndex === decoder.getStream().index) {
      *     const frame = await decoder.decode(packet);
      *     if (frame) {
      *       await processFrame(frame);
@@ -209,42 +209,94 @@ export declare class Decoder implements Disposable {
      */
     decode(packet: Packet): Promise<Frame | null>;
     /**
-     * Flush decoder and get buffered frame.
+     * Decode packet stream to frame stream.
      *
-     * Signals end-of-stream and retrieves remaining frames.
-     * Call repeatedly until null to get all buffered frames.
-     * Essential for ensuring all frames are decoded.
+     * High-level async generator for complete decoding pipeline.
+     * Automatically filters packets for this stream, manages memory,
+     * and flushes buffered frames at end.
+     * Primary interface for stream-based decoding.
      *
-     * Direct mapping to avcodec_send_packet(NULL).
+     * @param packets - Async iterable of packets
+     * @yields {Frame} Decoded frames
+     * @throws {Error} If decoder is closed
      *
-     * @returns Buffered frame or null if none remaining
+     * @throws {FFmpegError} If decoding fails
      *
-     * @throws {Error} If decoder is closed
+     * @example
+     * ```typescript
+     * await using input = await MediaInput.open('video.mp4');
+     * using decoder = await Decoder.create(input.video());
+     *
+     * for await (const frame of decoder.frames(input.packets())) {
+     *   console.log(`Frame: ${frame.width}x${frame.height}`);
+     *   frame.free();
+     * }
+     * ```
      *
      * @example
      * ```typescript
-     * // After all packets processed
+     * for await (const frame of decoder.frames(input.packets())) {
+     *   // Process frame
+     *   await filter.process(frame);
+     *
+     *   // Frame automatically freed
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { pipeline } from 'node-av/api';
+     *
+     * const control = pipeline(
+     *   input,
+     *   decoder,
+     *   encoder,
+     *   output
+     * );
+     * await control.completion;
+     * ```
+     *
+     * @see {@link decode} For single packet decoding
+     * @see {@link MediaInput.packets} For packet source
+     */
+    frames(packets: AsyncIterable<Packet>): AsyncGenerator<Frame>;
+    /**
+     * Flush decoder and signal end-of-stream.
+     *
+     * Sends null packet to decoder to signal end-of-stream.
+     * Does nothing if decoder is closed.
+     * Must use receive() or flushFrames() to get remaining buffered frames.
+     *
+     * Direct mapping to avcodec_send_packet(NULL).
+     *
+     * @throws {FFmpegError} If flush fails
+     *
+     * @example
+     * ```typescript
+     * // Signal end of stream
+     * await decoder.flush();
+     *
+     * // Then get remaining frames
      * let frame;
-     * while ((frame = await decoder.flush()) !== null) {
+     * while ((frame = await decoder.receive()) !== null) {
      *   console.log('Got buffered frame');
-     *   await processFrame(frame);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link flushFrames} For async iteration
-     * @see {@link frames} For complete decoding pipeline
+     * @see {@link flushFrames} For convenient async iteration
+     * @see {@link receive} For getting buffered frames
      */
-    flush(): Promise<Frame | null>;
+    flush(): Promise<void>;
     /**
      * Flush all buffered frames as async generator.
      *
      * Convenient async iteration over remaining frames.
-     * Automatically handles repeated flush calls.
+     * Automatically sends flush signal and retrieves buffered frames.
      * Useful for end-of-stream processing.
      *
-     * @yields Buffered frames
-     * @throws {Error} If decoder is closed
+     * @yields {Frame} Buffered frames
      *
      * @example
      * ```typescript
@@ -256,63 +308,47 @@ export declare class Decoder implements Disposable {
      * }
      * ```
      *
-     * @see {@link flush} For single frame flush
+     * @see {@link flush} For signaling end-of-stream
      * @see {@link frames} For complete pipeline
      */
     flushFrames(): AsyncGenerator<Frame>;
     /**
-     * Decode packet stream to frame stream.
+     * Receive frame from decoder.
      *
-     * High-level async generator for complete decoding pipeline.
-     * Automatically filters packets for this stream, manages memory,
-     * and flushes buffered frames at end.
-     * Primary interface for stream-based decoding.
+     * Gets decoded frames from the codec's internal buffer.
+     * Handles frame cloning and error checking.
+     * Hardware frames include hw_frames_ctx reference.
+     * Call repeatedly until null to drain all buffered frames.
      *
-     * @param packets - Async iterable of packets
-     * @yields Decoded frames
-     * @throws {Error} If decoder is closed
+     * Direct mapping to avcodec_receive_frame().
      *
-     * @throws {FFmpegError} If decoding fails
+     * @returns Cloned frame or null if no frames available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * await using input = await MediaInput.open('video.mp4');
-     * using decoder = await Decoder.create(input.video());
-     *
-     * for await (const frame of decoder.frames(input.packets())) {
-     *   console.log(`Frame: ${frame.width}x${frame.height}`);
+     * const frame = await decoder.receive();
+     * if (frame) {
+     *   console.log('Got decoded frame');
      *   frame.free();
      * }
      * ```
      *
      * @example
      * ```typescript
-     * for await (const frame of decoder.frames(input.packets())) {
-     *   // Process frame
-     *   await filter.filterFrame(frame);
-     *
-     *   // Frame automatically freed
+     * // Drain all buffered frames
+     * let frame;
+     * while ((frame = await decoder.receive()) !== null) {
+     *   console.log(`Frame PTS: ${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @example
-     * ```typescript
-     * import { pipeline } from 'node-av/api';
-     *
-     * const control = pipeline(
-     *   input,
-     *   decoder,
-     *   encoder,
-     *   output
-     * );
-     * await control.completion;
-     * ```
-     *
-     * @see {@link decode} For single packet decoding
-     * @see {@link MediaInput.packets} For packet source
+     * @see {@link decode} For sending packets and receiving frames
+     * @see {@link flush} For signaling end-of-stream
      */
-    frames(packets: AsyncIterable<Packet>): AsyncGenerator<Frame>;
+    receive(): Promise<Frame | null>;
     /**
      * Close decoder and free resources.
      *
@@ -333,24 +369,6 @@ export declare class Decoder implements Disposable {
      * @see {@link Symbol.dispose} For automatic cleanup
      */
     close(): void;
-    /**
-     * Get stream index.
-     *
-     * Returns the index of the stream being decoded.
-     * Used for packet filtering in multi-stream files.
-     *
-     * @returns Stream index
-     *
-     * @example
-     * ```typescript
-     * if (packet.streamIndex === decoder.getStreamIndex()) {
-     *   const frame = await decoder.decode(packet);
-     * }
-     * ```
-     *
-     * @see {@link getStream} For full stream object
-     */
-    getStreamIndex(): number;
     /**
      * Get stream object.
      *
@@ -359,45 +377,38 @@ export declare class Decoder implements Disposable {
      *
      * @returns Stream object
      *
-     * @example
-     * ```typescript
-     * const stream = decoder.getStream();
-     * console.log(`Duration: ${stream.duration}`);
-     * console.log(`Time base: ${stream.timeBase.num}/${stream.timeBase.den}`);
-     * ```
+     * @internal
      *
-     * @see {@link Stream} For stream properties
-     * @see {@link getStreamIndex} For index only
+     * @see {@link Stream} For stream details
      */
     getStream(): Stream;
     /**
-     * Get underlying codec context.
+     * Get decoder codec.
      *
-     * Returns the internal codec context for advanced operations.
-     * Returns null if decoder is closed.
+     * Returns the codec used by this decoder.
+     * Useful for checking codec capabilities and properties.
      *
-     * @returns Codec context or null
+     * @returns Codec instance
      *
      * @internal
+     *
+     * @see {@link Codec} For codec details
      */
-    getCodecContext(): CodecContext | null;
+    getCodec(): Codec;
     /**
-     * Receive frame from decoder.
-     *
-     * Internal method to get decoded frames from codec.
-     * Handles frame cloning and error checking.
-     * Hardware frames include hw_frames_ctx reference.
-     *
-     * Direct mapping to avcodec_receive_frame().
+     * Get underlying codec context.
      *
-     * @returns Cloned frame or null
+     * Returns the codec context for advanced operations.
+     * Useful for accessing low-level codec properties and settings.
+     * Returns null if decoder is closed.
      *
-     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     * @returns Codec context or null if closed
      *
      * @internal
      *
+     * @see {@link CodecContext} For context details
      */
-    private receiveFrameInternal;
+    getCodecContext(): CodecContext | null;
     /**
      * Dispose of decoder.
      *