node-av 0.0.1

package/dist/lib/io-context.js

@@ -0,0 +1,550 @@
+import { bindings } from './binding.js';
+import { AVIO_FLAG_READ } from './constants.js';
+import { OptionMember } from './option.js';
+/**
+ * I/O context for custom input/output operations.
+ *
+ * Provides buffered I/O and protocol handling for reading/writing data
+ * from/to files, network streams, memory buffers, or custom sources.
+ * Can be used with FormatContext for custom I/O or standalone for direct I/O operations.
+ *
+ * Direct mapping to FFmpeg's AVIOContext.
+ *
+ * @example
+ * ```typescript
+ * import { IOContext, FFmpegError } from 'node-av';
+ * import { AVIO_FLAG_READ, AVSEEK_SET } from 'node-av/constants';
+ *
+ * // Open a file for reading
+ * const io = new IOContext();
+ * const ret = await io.open2('input.mp4', AVIO_FLAG_READ);
+ * FFmpegError.throwIfError(ret, 'open2');
+ *
+ * // Read data
+ * const buffer = await io.read(4096);
+ *
+ * // Seek to position
+ * const seekRet = await io.seek(1024n, AVSEEK_SET);
+ * FFmpegError.throwIfError(seekRet < 0 ? -1 : 0, 'seek');
+ *
+ * // Get file size
+ * const size = await io.size();
+ *
+ * // Clean up
+ * await io.closep();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom I/O with callbacks
+ * const io = new IOContext();
+ * io.allocContextWithCallbacks(
+ *   4096,           // buffer size
+ *   0,              // read mode
+ *   (size) => {     // custom read function
+ *     return myBuffer.slice(pos, pos + size);
+ *   },
+ *   null,           // no write
+ *   (offset, whence) => { // custom seek function
+ *     return BigInt(calculateNewPosition(offset, whence));
+ *   }
+ * );
+ *
+ * // Use with FormatContext
+ * const ctx = new FormatContext();
+ * ctx.allocOutputContext2(null, 'mp4', null);
+ * ctx.pb = io;
+ * const openRet = await ctx.openInput(null, null, null);
+ * FFmpegError.throwIfError(openRet, 'openInput');
+ * ```
+ *
+ * @see {@link FormatContext} For using custom I/O with containers
+ */
+export class IOContext extends OptionMember {
+    /**
+     * Create a new I/O context instance.
+     *
+     * The context is uninitialized - you must call allocContext() or open2() before use.
+     * No FFmpeg resources are allocated until initialization.
+     *
+     * Direct wrapper around AVIOContext allocation.
+     *
+     * @example
+     * ```typescript
+     * import { IOContext, FFmpegError, AVIO_FLAG_READ } from 'node-av';
+     *
+     * const io = new IOContext();
+     * const ret = await io.open2('file.mp4', AVIO_FLAG_READ);
+     * FFmpegError.throwIfError(ret, 'open2');
+     * // I/O context is now ready for use
+     * ```
+     */
+    constructor() {
+        super(new bindings.IOContext());
+    }
+    /**
+     * Create an IOContext wrapper from a native IOContext.
+     *
+     * Used internally when getting IOContext from other objects.
+     * @internal
+     *
+     * @param native - Native IOContext to wrap
+     * @returns Wrapped IOContext instance
+     */
+    static fromNative(native) {
+        const io = Object.create(IOContext.prototype);
+        io.native = native;
+        return io;
+    }
+    /**
+     * Check if end of file reached.
+     *
+     * Direct mapping to avio_feof()
+     *
+     * @readonly
+     */
+    get eof() {
+        return this.native.eof;
+    }
+    /**
+     * Error code if any.
+     *
+     * Direct mapping to AVIOContext->error
+     *
+     * @readonly
+     */
+    get error() {
+        return this.native.error;
+    }
+    /**
+     * Whether seeking is possible.
+     *
+     * Direct mapping to AVIOContext->seekable
+     *
+     * Bitmask of AVIO_SEEKABLE_* flags.
+     * @readonly
+     */
+    get seekable() {
+        return this.native.seekable;
+    }
+    /**
+     * Maximum packet size.
+     *
+     * Direct mapping to AVIOContext->max_packet_size
+     *
+     * If non-zero, indicates the maximum packet size.
+     */
+    get maxPacketSize() {
+        return this.native.maxPacketSize;
+    }
+    set maxPacketSize(value) {
+        this.native.maxPacketSize = value;
+    }
+    /**
+     * Whether direct mode is enabled.
+     *
+     * Direct mapping to AVIOContext->direct
+     *
+     * avio_read and avio_write should if possible be satisfied directly
+     * instead of going through a buffer, and avio_seek will always call
+     * the underlying seek function directly.
+     */
+    get direct() {
+        return this.native.direct;
+    }
+    set direct(value) {
+        this.native.direct = value;
+    }
+    /**
+     * Get current position in the file.
+     *
+     * Direct mapping to AVIOContext->pos
+     *
+     * @readonly
+     */
+    get pos() {
+        return this.native.pos;
+    }
+    /**
+     * Get buffer size.
+     *
+     * Direct mapping to AVIOContext->buffer_size
+     *
+     * @readonly
+     */
+    get bufferSize() {
+        return this.native.bufferSize;
+    }
+    /**
+     * Check if opened for writing.
+     *
+     * Direct mapping to AVIOContext->write_flag
+     *
+     * @readonly
+     */
+    get writeFlag() {
+        return this.native.writeFlag;
+    }
+    /**
+     * Create and initialize a buffered I/O context.
+     *
+     * Allocates an I/O context with an internal buffer for efficient I/O operations.
+     * For file I/O, use open2() instead which handles allocation automatically.
+     *
+     * Direct mapping to avio_alloc_context()
+     *
+     * @param bufferSize - Size of the internal buffer in bytes
+     * @param writeFlag - 1 for writing, 0 for reading
+     *
+     * @example
+     * ```typescript
+     * import { IOContext } from 'node-av';
+     *
+     * const io = new IOContext();
+     * io.allocContext(4096, 0); // 4KB buffer for reading
+     *
+     * // For writing
+     * const writeIO = new IOContext();
+     * writeIO.allocContext(8192, 1); // 8KB buffer for writing
+     * ```
+     *
+     * @see {@link allocContextWithCallbacks} For custom I/O callbacks
+     * @see {@link open2} For file I/O
+     */
+    allocContext(bufferSize, writeFlag) {
+        return this.native.allocContext(bufferSize, writeFlag);
+    }
+    /**
+     * Allocate an AVIOContext with custom callbacks.
+     *
+     * Creates a custom I/O context with JavaScript callbacks for read, write, and seek operations.
+     *
+     * IMPORTANT: Callbacks must be synchronous! They are called from FFmpeg's thread and must
+     * return immediately. If you need async operations, buffer the data in JavaScript first.
+     *
+     * Direct mapping to avio_alloc_context() with custom callbacks
+     *
+     * @param bufferSize - Size of the buffer in bytes
+     * @param writeFlag - 0 for read, 1 for write
+     * @param readCallback - Synchronous callback for reading data. Returns Buffer, null for EOF, or negative error code
+     * @param writeCallback - Synchronous callback for writing data. Returns bytes written or negative error code
+     * @param seekCallback - Synchronous callback for seeking. Returns new position or negative error code
+     *
+     * @example
+     * ```typescript
+     * import { IOContext, AVSEEK_SET, AVSEEK_CUR, AVSEEK_END } from 'node-av';
+     *
+     * const io = new IOContext();
+     * let position = 0;
+     * const buffer = Buffer.from('example data');
+     *
+     * io.allocContextWithCallbacks(
+     *   4096,
+     *   0,
+     *   (size) => {
+     *     // Read up to 'size' bytes - MUST BE SYNCHRONOUS
+     *     return buffer.slice(position, position + size);
+     *   },
+     *   null,
+     *   (offset, whence) => {
+     *     // Seek to position - MUST BE SYNCHRONOUS
+     *     if (whence === AVSEEK_SET) position = Number(offset);
+     *     else if (whence === AVSEEK_CUR) position += Number(offset);
+     *     else if (whence === AVSEEK_END) position = buffer.length + Number(offset);
+     *     return BigInt(position);
+     *   }
+     * );
+     * ```
+     *
+     * @see {@link allocContext} For simple buffer allocation
+     */
+    allocContextWithCallbacks(bufferSize, writeFlag, readCallback, writeCallback, seekCallback) {
+        return this.native.allocContextWithCallbacks(bufferSize, writeFlag, readCallback ?? undefined, writeCallback ?? undefined, seekCallback ?? undefined);
+    }
+    /**
+     * Free the AVIOContext.
+     *
+     * Direct mapping to avio_context_free()
+     *
+     * @example
+     * ```typescript
+     * import { IOContext } from 'node-av';
+     *
+     * io.freeContext();
+     * // io is now invalid and should not be used
+     * ```
+     */
+    freeContext() {
+        return this.native.freeContext();
+    }
+    /**
+     * Open a resource for reading or writing.
+     *
+     * Opens a URL using the appropriate protocol handler (file, http, etc.).
+     * Automatically allocates and initializes the I/O context.
+     *
+     * Direct mapping to avio_open2()
+     *
+     * @param url - URL to open (file://, http://, https://, etc.)
+     * @param flags - I/O flags (AVIO_FLAG_READ, AVIO_FLAG_WRITE, etc.)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(ENOENT): File not found
+     *   - AVERROR(EACCES): Permission denied
+     *   - AVERROR(EIO): I/O error
+     *   - AVERROR(ENOMEM): Memory allocation failure
+     *   - <0: Other protocol-specific errors
+     *
+     * @example
+     * ```typescript
+     * import { IOContext, FFmpegError } from 'node-av';
+     * import { AVIO_FLAG_READ, AVIO_FLAG_WRITE } from 'node-av/constants';
+     *
+     * // Open file for reading
+     * const io = new IOContext();
+     * const ret = await io.open2('input.mp4', AVIO_FLAG_READ);
+     * FFmpegError.throwIfError(ret, 'open2');
+     *
+     * // Open file for writing
+     * const writeIO = new IOContext();
+     * const writeRet = await writeIO.open2('output.mp4', AVIO_FLAG_WRITE);
+     * FFmpegError.throwIfError(writeRet, 'open2');
+     *
+     * // Open network stream
+     * const streamIO = new IOContext();
+     * const streamRet = await streamIO.open2('http://example.com/stream.m3u8', AVIO_FLAG_READ);
+     * FFmpegError.throwIfError(streamRet, 'open2');
+     * ```
+     *
+     * @see {@link closep} To close and free resources
+     */
+    async open2(url, flags = AVIO_FLAG_READ) {
+        return this.native.open2(url, flags);
+    }
+    /**
+     * Close the resource and free the AVIOContext.
+     *
+     * Direct mapping to avio_closep()
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - 0: Success
+     *   - AVERROR(EIO): I/O error during close
+     *   - <0: Other errors
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = await io.closep();
+     * FFmpegError.throwIfError(ret, 'closep');
+     * // I/O context is now closed and freed
+     * ```
+     */
+    async closep() {
+        return this.native.closep();
+    }
+    /**
+     * Read size bytes from AVIOContext.
+     *
+     * Direct mapping to avio_read()
+     *
+     * @param size - Number of bytes to read
+     *
+     * @returns Buffer with data or error code if negative:
+     *   - Buffer: Successfully read data
+     *   - AVERROR_EOF: End of file reached
+     *   - AVERROR(EIO): I/O error
+     *   - <0: Other errors
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError, AVERROR_EOF } from 'node-av';
+     *
+     * const data = await io.read(1024);
+     * if (typeof data === 'number' && data < 0) {
+     *   if (data === AVERROR_EOF) {
+     *     console.log('End of file');
+     *   } else {
+     *     FFmpegError.throwIfError(data, 'read');
+     *   }
+     * } else {
+     *   // Process buffer
+     *   console.log(`Read ${data.length} bytes`);
+     * }
+     * ```
+     */
+    async read(size) {
+        return this.native.read(size);
+    }
+    /**
+     * Write buffer to AVIOContext.
+     *
+     * Direct mapping to avio_write()
+     *
+     * @param buffer - Buffer to write
+     *
+     * @example
+     * ```typescript
+     * import { IOContext } from 'node-av';
+     *
+     * const data = Buffer.from('Hello, World!');
+     * await io.write(data);
+     * // Data written successfully
+     * ```
+     *
+     * @throws {Error} If write fails
+     */
+    async write(buffer) {
+        return this.native.write(buffer);
+    }
+    /**
+     * Seek to a given offset.
+     *
+     * Direct mapping to avio_seek()
+     *
+     * @param offset - Offset to seek to
+     * @param whence - AVSEEK_SET (0), AVSEEK_CUR (1), AVSEEK_END (2), or AVSEEK_SIZE (0x10000)
+     *
+     * @returns New position or negative AVERROR:
+     *   - >=0: New position in bytes
+     *   - AVERROR(EINVAL): Invalid whence value
+     *   - AVERROR(ESPIPE): Seek not supported
+     *   - <0: Other errors
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError, AVSEEK_SET, AVSEEK_END, AVSEEK_SIZE } from 'node-av';
+     *
+     * // Seek to beginning
+     * const pos = await io.seek(0n, AVSEEK_SET);
+     * FFmpegError.throwIfError(pos < 0n ? Number(pos) : 0, 'seek');
+     *
+     * // Seek to end
+     * const endPos = await io.seek(0n, AVSEEK_END);
+     * FFmpegError.throwIfError(endPos < 0n ? Number(endPos) : 0, 'seek');
+     *
+     * // Get file size without changing position
+     * const size = await io.seek(0n, AVSEEK_SIZE);
+     * console.log(`File size: ${size} bytes`);
+     * ```
+     */
+    async seek(offset, whence) {
+        return this.native.seek(offset, whence);
+    }
+    /**
+     * Get the file size.
+     *
+     * Direct mapping to avio_size()
+     *
+     * @returns File size or negative AVERROR:
+     *   - >=0: File size in bytes
+     *   - AVERROR(ENOSYS): Operation not supported
+     *   - <0: Other errors
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const size = await io.size();
+     * if (size < 0n) {
+     *   // Handle unsupported or error
+     *   console.error('Cannot determine file size');
+     * } else {
+     *   console.log(`File size: ${size} bytes`);
+     * }
+     * ```
+     */
+    async size() {
+        return this.native.size();
+    }
+    /**
+     * Force flushing of buffered data.
+     *
+     * Direct mapping to avio_flush()
+     *
+     * @example
+     * ```typescript
+     * import { IOContext } from 'node-av';
+     *
+     * await io.flush();
+     * // All buffered data has been written
+     * ```
+     */
+    async flush() {
+        return this.native.flush();
+    }
+    /**
+     * Skip given number of bytes forward.
+     *
+     * Direct mapping to avio_skip()
+     *
+     * @param offset - Number of bytes to skip
+     *
+     * @returns New position or negative AVERROR:
+     *   - >=0: New position in bytes
+     *   - AVERROR_EOF: End of file reached
+     *   - <0: Other errors
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Skip 1024 bytes
+     * const newPos = await io.skip(1024n);
+     * FFmpegError.throwIfError(newPos < 0n ? Number(newPos) : 0, 'skip');
+     * console.log(`New position: ${newPos}`);
+     * ```
+     */
+    async skip(offset) {
+        return this.native.skip(offset);
+    }
+    /**
+     * Get the current position.
+     *
+     * Direct mapping to avio_tell()
+     *
+     * @returns Current position in bytes
+     *
+     * @example
+     * ```typescript
+     * import { IOContext } from 'node-av';
+     *
+     * const position = io.tell();
+     * console.log(`Current position: ${position} bytes`);
+     * ```
+     */
+    tell() {
+        return this.native.tell();
+    }
+    /**
+     * Get the native FFmpeg AVIOContext pointer.
+     *
+     * @internal For use by other wrapper classes
+     * @returns The underlying native I/O context object
+     */
+    getNative() {
+        return this.native;
+    }
+    /**
+     * Dispose of the I/O context.
+     *
+     * Implements the AsyncDisposable interface for automatic cleanup.
+     * Equivalent to calling closep().
+     *
+     * @example
+     * ```typescript
+     * import { IOContext, AVIO_FLAG_READ } from 'node-av';
+     *
+     * {
+     *   await using io = new IOContext();
+     *   await io.open2('file.mp4', AVIO_FLAG_READ);
+     *   // ... use I/O context
+     * } // Automatically closed when leaving scope
+     * ```
+     */
+    async [Symbol.asyncDispose]() {
+        await this.native[Symbol.asyncDispose]();
+    }
+}
+//# sourceMappingURL=io-context.js.map

package/dist/lib/io-context.js.map

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