node-av 0.0.1

package/dist/api/io-stream.d.ts

@@ -0,0 +1,109 @@
+/**
+ * IOStream - Custom I/O Factory for FFmpeg
+ *
+ * Provides factory methods for creating IOContext instances from various sources.
+ * Supports Buffers for in-memory operations and custom callbacks for full control.
+ *
+ * All methods are static - this class cannot be instantiated.
+ * Use the overloaded create() method to create IOContext from different input types.
+ *
+ * @module api/io-stream
+ */
+import { IOContext } from '../lib/index.js';
+import type { IOInputCallbacks, MediaInputOptions } from './types.js';
+/**
+ * Factory class for creating IOContext instances.
+ *
+ * Provides a unified interface for creating custom I/O contexts from:
+ * - Buffers for in-memory data
+ * - Custom callbacks for full I/O control
+ *
+ * @example
+ * ```typescript
+ * import { IOStream } from 'node-av/api';
+ * import { readFile } from 'fs/promises';
+ *
+ * // From Buffer
+ * const buffer = await readFile('video.mp4');
+ * const ioContext = IOStream.create(buffer);
+ *
+ * // From custom callbacks
+ * const ioContext = IOStream.create({
+ *   read: (size) => customSource.read(size),
+ *   seek: (offset, whence) => customSource.seek(offset, whence)
+ * });
+ * ```
+ */
+export declare class IOStream {
+    private constructor();
+    /**
+     * Create IOContext from a Buffer.
+     *
+     * Creates an I/O context for reading from in-memory data.
+     * Automatically handles seeking within the buffer.
+     *
+     * @param buffer - Buffer containing media data
+     * @param options - Optional configuration
+     *
+     * @returns IOContext instance ready for use
+     *
+     * @example
+     * ```typescript
+     * const buffer = await readFile('video.mp4');
+     * const ioContext = IOStream.create(buffer);
+     * ```
+     */
+    static create(buffer: Buffer, options?: MediaInputOptions): IOContext;
+    /**
+     * Create IOContext from custom callbacks.
+     *
+     * Creates an I/O context with custom read and seek operations.
+     * Callbacks must be synchronous and return immediately.
+     *
+     * @param callbacks - Custom I/O callbacks (read required, seek optional)
+     * @param options - Optional configuration
+     *
+     * @returns IOContext instance ready for use
+     *
+     * @throws {Error} If read callback is not provided
+     *
+     * @example
+     * ```typescript
+     * const ioContext = IOStream.create({
+     *   read: (size) => buffer.slice(pos, pos + size),
+     *   seek: (offset, whence) => calculatePosition(offset, whence)
+     * });
+     * ```
+     */
+    static create(callbacks: IOInputCallbacks, options?: MediaInputOptions): IOContext;
+    /**
+     * Create IOContext from a Buffer with position tracking.
+     *
+     * Sets up read and seek callbacks that operate on the buffer.
+     * Maintains internal position state for sequential reading.
+     *
+     * @param buffer - Buffer containing the data
+     * @param bufferSize - Internal buffer size for IOContext
+     *
+     * @returns Configured IOContext instance
+     *
+     * @internal
+     */
+    private static createFromBuffer;
+    /**
+     * Create IOContext from user-provided callbacks.
+     *
+     * Validates and wraps the provided callbacks for use with FFmpeg.
+     * Only supports read mode as high-level API doesn't expose write operations.
+     *
+     * @param callbacks - User-provided I/O callbacks
+     * @param bufferSize - Internal buffer size for IOContext
+     *
+     * @returns Configured IOContext instance
+     *
+     * @throws {Error} If read callback is not provided
+     *
+     * @internal
+     */
+    private static createFromCallbacks;
+}

package/dist/api/io-stream.js

@@ -0,0 +1,124 @@
+/**
+ * IOStream - Custom I/O Factory for FFmpeg
+ *
+ * Provides factory methods for creating IOContext instances from various sources.
+ * Supports Buffers for in-memory operations and custom callbacks for full control.
+ *
+ * All methods are static - this class cannot be instantiated.
+ * Use the overloaded create() method to create IOContext from different input types.
+ *
+ * @module api/io-stream
+ */
+import { AVSEEK_CUR, AVSEEK_END, AVSEEK_SET, AVSEEK_SIZE, IOContext } from '../lib/index.js';
+/**
+ * Factory class for creating IOContext instances.
+ *
+ * Provides a unified interface for creating custom I/O contexts from:
+ * - Buffers for in-memory data
+ * - Custom callbacks for full I/O control
+ *
+ * @example
+ * ```typescript
+ * import { IOStream } from 'node-av/api';
+ * import { readFile } from 'fs/promises';
+ *
+ * // From Buffer
+ * const buffer = await readFile('video.mp4');
+ * const ioContext = IOStream.create(buffer);
+ *
+ * // From custom callbacks
+ * const ioContext = IOStream.create({
+ *   read: (size) => customSource.read(size),
+ *   seek: (offset, whence) => customSource.seek(offset, whence)
+ * });
+ * ```
+ */
+export class IOStream {
+    // Private constructor to prevent instantiation
+    constructor() {
+        throw new Error('IOStream is a static class and cannot be instantiated');
+    }
+    static create(input, options = {}) {
+        const { bufferSize = 8192 } = options;
+        // Handle Buffer
+        if (Buffer.isBuffer(input)) {
+            return this.createFromBuffer(input, bufferSize);
+        }
+        // Handle custom callbacks
+        if (typeof input === 'object' && 'read' in input) {
+            return this.createFromCallbacks(input, bufferSize);
+        }
+        throw new TypeError('Invalid input type. Expected Buffer or IOInputCallbacks');
+    }
+    /**
+     * Create IOContext from a Buffer with position tracking.
+     *
+     * Sets up read and seek callbacks that operate on the buffer.
+     * Maintains internal position state for sequential reading.
+     *
+     * @param buffer - Buffer containing the data
+     * @param bufferSize - Internal buffer size for IOContext
+     *
+     * @returns Configured IOContext instance
+     *
+     * @internal
+     */
+    static createFromBuffer(buffer, bufferSize) {
+        let position = 0;
+        const ioContext = new IOContext();
+        ioContext.allocContextWithCallbacks(bufferSize, 0, (size) => {
+            if (position >= buffer.length) {
+                return null; // EOF
+            }
+            const chunk = buffer.subarray(position, Math.min(position + size, buffer.length));
+            position += chunk.length;
+            return chunk;
+        }, undefined, (offset, whence) => {
+            switch (whence) {
+                case AVSEEK_SIZE:
+                    return BigInt(buffer.length);
+                case AVSEEK_SET:
+                    position = Number(offset);
+                    break;
+                case AVSEEK_CUR:
+                    position += Number(offset);
+                    break;
+                case AVSEEK_END:
+                    position = buffer.length + Number(offset);
+                    break;
+            }
+            // Clamp position
+            position = Math.max(0, Math.min(position, buffer.length));
+            return BigInt(position);
+        });
+        return ioContext;
+    }
+    /**
+     * Create IOContext from user-provided callbacks.
+     *
+     * Validates and wraps the provided callbacks for use with FFmpeg.
+     * Only supports read mode as high-level API doesn't expose write operations.
+     *
+     * @param callbacks - User-provided I/O callbacks
+     * @param bufferSize - Internal buffer size for IOContext
+     *
+     * @returns Configured IOContext instance
+     *
+     * @throws {Error} If read callback is not provided
+     *
+     * @internal
+     */
+    static createFromCallbacks(callbacks, bufferSize) {
+        // We only support read mode in the high-level API
+        // Write mode would be needed for custom output, which we don't currently support
+        if (!callbacks.read) {
+            throw new Error('Read callback is required');
+        }
+        const ioContext = new IOContext();
+        ioContext.allocContextWithCallbacks(bufferSize, 0, // Always read mode
+        callbacks.read, undefined, // No write callback in high-level API
+        callbacks.seek);
+        return ioContext;
+    }
+}
+//# sourceMappingURL=io-stream.js.map

package/dist/api/io-stream.js.map

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

package/dist/api/media-input.d.ts

@@ -0,0 +1,295 @@
+/**
+ * MediaInput - Unified Input Handler for FFmpeg
+ *
+ * Provides a high-level interface for opening and reading media from various sources.
+ * Supports files, URLs, and Buffers with automatic format detection.
+ *
+ * Central entry point for all media input operations.
+ * Manages FormatContext lifecycle and provides stream information.
+ *
+ * @module api/media-input
+ */
+import { FormatContext, Packet } from '../lib/index.js';
+import type { AVMediaType, AVSeekFlag, Stream } from '../lib/index.js';
+import type { MediaInputOptions, RawData } from './types.js';
+/**
+ * MediaInput - High-level media input handler.
+ *
+ * Opens and provides access to media streams from various sources.
+ * Automatically detects format and finds stream information.
+ *
+ * Manages the FormatContext and provides convenient methods for
+ * accessing streams, metadata, and packets.
+ *
+ * @example
+ * ```typescript
+ * import { MediaInput } from 'node-av/api';
+ *
+ * // Open from file
+ * const media = await MediaInput.open('video.mp4');
+ * console.log(`Found ${media.streams.length} streams`);
+ * console.log(`Duration: ${media.duration} seconds`);
+ *
+ * // Open from buffer
+ * const buffer = await fs.readFile('video.mp4');
+ * const media = await MediaInput.open(buffer);
+ *
+ * // Iterate packets
+ * for await (const packet of media.packets()) {
+ *   console.log(`Packet from stream ${packet.streamIndex}`);
+ * }
+ * ```
+ */
+export declare class MediaInput implements AsyncDisposable {
+    private formatContext;
+    private _streams;
+    private ioContext?;
+    /**
+     * Create a new MediaInput instance.
+     *
+     * Private constructor - use MediaInput.open() to create instances.
+     *
+     * Parses stream information immediately after construction.
+     *
+     * @param formatContext - Opened FormatContext
+     */
+    private constructor();
+    /**
+     * Probe the format of media without fully opening it.
+     *
+     * Detects the container format and basic information without
+     * parsing all stream information. Useful for quick format validation.
+     *
+     * @param input - File path or Buffer to probe
+     *
+     * @returns Format information or null if unrecognized
+     *
+     * @example
+     * ```typescript
+     * // Probe a file
+     * const info = await MediaInput.probeFormat('video.mp4');
+     * if (info) {
+     *   console.log(`Format: ${info.format}`);
+     *   console.log(`Confidence: ${info.confidence}%`);
+     * }
+     *
+     * // Probe a buffer
+     * const buffer = await fs.readFile('video.mp4');
+     * const info = await MediaInput.probeFormat(buffer);
+     * ```
+     */
+    static probeFormat(input: string | Buffer): Promise<{
+        format: string;
+        longName?: string;
+        extensions?: string;
+        mimeType?: string;
+        confidence: number;
+    } | null>;
+    /**
+     * Open a media input from various sources.
+     *
+     * Creates a FormatContext and opens the input for reading.
+     * Automatically detects format and finds stream information.
+     *
+     * Uses av_format_open_input() and av_find_stream_info() internally.
+     *
+     * @param input - File path, URL, or Buffer
+     * @param options - Optional configuration for timestamp handling
+     *
+     * @returns Promise resolving to MediaInput instance
+     *
+     * @throws {Error} If input cannot be opened or stream info not found
+     *
+     * @example
+     * ```typescript
+     * // From file
+     * const media = await MediaInput.open('video.mp4');
+     *
+     * // From URL
+     * const media = await MediaInput.open('https://example.com/video.mp4');
+     *
+     * // From Buffer
+     * const buffer = await fs.readFile('video.mp4');
+     * const media = await MediaInput.open(buffer);
+     * ```
+     */
+    static open(input: string | Buffer, options?: MediaInputOptions): Promise<MediaInput>;
+    /**
+     * Open raw video or audio data.
+     *
+     * @param rawData - Raw video or audio configuration
+     *
+     * @returns Promise resolving to MediaInput instance
+     *
+     * @example
+     * ```typescript
+     * // Raw video
+     * const input = await MediaInput.open({
+     *   type: 'video',
+     *   data: 'input.yuv',
+     *   width: 1280,
+     *   height: 720,
+     *   pixelFormat: 'yuv420p',
+     *   frameRate: 30
+     * });
+     *
+     * // Raw audio
+     * const input = await MediaInput.open({
+     *   type: 'audio',
+     *   data: 'input.pcm',
+     *   sampleRate: 48000,
+     *   channels: 2,
+     *   sampleFormat: 's16le'
+     * });
+     * ```
+     */
+    static open(rawData: RawData, options?: MediaInputOptions): Promise<MediaInput>;
+    /**
+     * Get all streams in the container.
+     *
+     * @returns Array of stream information
+     */
+    get streams(): Stream[];
+    /**
+     * Get media duration in seconds.
+     *
+     * Returns 0 if duration is not available.
+     *
+     * @returns Duration in seconds
+     */
+    get duration(): number;
+    /**
+     * Get container metadata.
+     *
+     * @returns Metadata key-value pairs
+     */
+    get metadata(): Record<string, string>;
+    /**
+     * Get container format name.
+     *
+     * @returns Format name (e.g., 'mov,mp4,m4a,3gp,3g2,mj2')
+     */
+    get formatName(): string;
+    /**
+     * Get container format long name.
+     *
+     * @returns Format long name (e.g., 'QuickTime / MOV')
+     */
+    get formatLongName(): string;
+    /**
+     * Get the first video stream.
+     *
+     * @param index - Video stream index (0 for first, 1 for second, etc.)
+     *
+     * @returns Stream info or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const videoStream = media.video();
+     * if (videoStream) {
+     *   console.log(`Video: ${videoStream.width}x${videoStream.height}`);
+     * }
+     * ```
+     */
+    video(index?: number): Stream | undefined;
+    /**
+     * Get the first audio stream.
+     *
+     * @param index - Audio stream index (0 for first, 1 for second, etc.)
+     *
+     * @returns Stream info or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const audioStream = media.audio();
+     * if (audioStream) {
+     *   console.log(`Audio: ${audioStream.sampleRate}Hz, ${audioStream.channels}ch`);
+     * }
+     * ```
+     */
+    audio(index?: number): Stream | undefined;
+    /**
+     * Find the best stream of a given type.
+     *
+     * Uses FFmpeg's stream selection logic to find the most suitable stream.
+     *
+     * Uses av_find_best_stream() internally for optimal stream selection.
+     *
+     * @param type - Media type to search for
+     *
+     * @returns Stream info or undefined if not found
+     */
+    findBestStream(type: AVMediaType): Stream | undefined;
+    /**
+     * Iterate over all packets in the container.
+     *
+     * Allocates a single packet and reuses it for efficiency.
+     * Automatically unreferences the packet between iterations.
+     *
+     * Uses av_read_frame() internally.
+     *
+     * @yields Packet from the container
+     *
+     * @example
+     * ```typescript
+     * for await (const packet of media.packets()) {
+     *   if (packet.streamIndex === videoStream.index) {
+     *     // Process video packet
+     *     await decoder.decode(packet);
+     *   }
+     * }
+     * ```
+     */
+    packets(index?: number): AsyncGenerator<Packet>;
+    /**
+     * Seek to a specific timestamp.
+     *
+     * Uses av_seek_frame() internally.
+     *
+     * Converts seconds to microseconds for FFmpeg's AV_TIME_BASE.
+     *
+     * @param timestamp - Target timestamp in seconds
+     * @param streamIndex - Stream to seek in (-1 for default)
+     * @param flags - Seek flags (0 for default)
+     *
+     * @returns 0 on success, negative error code on failure
+     */
+    seek(timestamp: number, streamIndex?: number, flags?: AVSeekFlag): Promise<number>;
+    /**
+     * Close the input and free resources.
+     *
+     * Uses avformat_close_input() internally.
+     *
+     * Properly cleans up IOContext references before closing to prevent
+     * use-after-free errors.
+     */
+    close(): Promise<void>;
+    /**
+     * Get the low-level FormatContext.
+     *
+     * Internal method for advanced use cases.
+     *
+     * Provides direct access to the underlying AVFormatContext.
+     *
+     * @returns FFmpeg FormatContext
+     *
+     * @internal
+     */
+    getFormatContext(): FormatContext;
+    /**
+     * Async cleanup when using 'await using' statement.
+     *
+     * Implements the AsyncDisposable interface for automatic cleanup.
+     *
+     * Calls close() to free all resources.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   await using media = await MediaInput.open('video.mp4');
+     *   // Use media...
+     * } // Automatically closed
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}