node-av 1.0.3 → 1.2.0

package/dist/lib/stream.d.ts

@@ -1,16 +1,16 @@
 import { CodecParameters } from './codec-parameters.js';
 import { Dictionary } from './dictionary.js';
 import { Rational } from './rational.js';
-import type { AVDiscard, AVDisposition, AVStreamEventFlag } from './constants.js';
+import type { AVDiscard, AVDisposition, AVStreamEventFlag } from '../constants/constants.js';
 import type { NativeStream, NativeWrapper } from './native-types.js';
 import type { Packet } from './packet.js';
 /**
- * Stream information within a media container.
+ * Media stream within a format context.
  *
- * Represents a single stream (video, audio, subtitle, etc.) within a media file.
- * Streams are created and managed by FormatContext and contain all the metadata
- * and parameters needed to decode or encode the stream. Each stream has its own
- * timebase, codec parameters, and metadata.
+ * Represents a single stream (video, audio, subtitle, etc.) within a media container.
+ * Contains stream-specific information including codec parameters, timing information,
+ * metadata, and disposition flags. Each stream in a file has a unique index and may
+ * contain packets of compressed data.
  *
  * Direct mapping to FFmpeg's AVStream.
  *
@@ -19,304 +19,194 @@ import type { Packet } from './packet.js';
  * import { FormatContext, FFmpegError } from 'node-av';
  * import { AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO } from 'node-av/constants';
  *
- * // Streams are obtained from FormatContext
+ * // Access streams from format context
  * const formatContext = new FormatContext();
- * const ret = await formatContext.openInput('video.mp4', null, null);
- * FFmpegError.throwIfError(ret, 'openInput');
+ * await formatContext.openInput('video.mp4');
  *
- * const infoRet = await formatContext.findStreamInfo(null);
- * FFmpegError.throwIfError(infoRet, 'findStreamInfo');
- *
- * // Access streams
- * const streams = formatContext.streams;
- * for (const stream of streams) {
- *   console.log(`Stream ${stream.index}: ${stream.codecpar.codecType}`);
- *   console.log(`Time base: ${stream.timeBase.num}/${stream.timeBase.den}`);
- *
- *   // Direct access to codec parameters
+ * // Iterate through streams
+ * for (let i = 0; i < formatContext.nbStreams; i++) {
+ *   const stream = formatContext.streams[i];
  *   const codecpar = stream.codecpar;
+ *
  *   if (codecpar.codecType === AVMEDIA_TYPE_VIDEO) {
- *     console.log(`Video: ${codecpar.width}x${codecpar.height}`);
+ *     console.log(`Video stream ${stream.index}:`);
+ *     console.log(`  Codec: ${codecpar.codecId}`);
+ *     console.log(`  Resolution: ${codecpar.width}x${codecpar.height}`);
+ *     console.log(`  Frame rate: ${stream.avgFrameRate.num}/${stream.avgFrameRate.den}`);
  *   } else if (codecpar.codecType === AVMEDIA_TYPE_AUDIO) {
- *     console.log(`Audio: ${codecpar.sampleRate}Hz ${codecpar.channels} channels`);
+ *     console.log(`Audio stream ${stream.index}:`);
+ *     console.log(`  Sample rate: ${codecpar.sampleRate} Hz`);
+ *     console.log(`  Channels: ${codecpar.channels}`);
  *   }
  * }
  * ```
  *
- * @see {@link FormatContext} For creating and managing streams
- * @see {@link CodecParameters} For codec-specific stream parameters
+ * @see [AVStream](https://ffmpeg.org/doxygen/trunk/structAVStream.html) - FFmpeg Doxygen
+ * @see {@link FormatContext} For container operations
+ * @see {@link CodecParameters} For codec configuration
  */
 export declare class Stream implements NativeWrapper<NativeStream> {
     private native;
     private _codecpar?;
     /**
-     * Constructor is internal - use FormatContext to create streams.
-     *
-     * Streams are created and managed by FormatContext.
-     * For demuxing, streams are created automatically when opening input.
-     * For muxing, use formatContext.newStream() to create streams.
-     *
+     * @param native - The native stream instance
      * @internal
-     *
-     * @param native - Native AVStream to wrap
-     *
-     * @example
-     * ```typescript
-     * // Don't create streams directly
-     * // const stream = new Stream(); // Wrong
-     *
-     * // For demuxing: streams are created automatically
-     * const streams = formatContext.streams; // Correct
-     *
-     * // For muxing: use newStream
-     * const stream = formatContext.newStream(null); // Correct
-     * ```
      */
     constructor(native: NativeStream);
     /**
-     * Stream index in the format context.
-     *
-     * Zero-based index of this stream in the format context's stream array.
-     * This is the index used to identify the stream in packets.
-     *
-     * Direct mapping to AVStream->index
-     *
-     * @readonly
+     * Stream index.
      *
-     * @example
-     * ```typescript
-     * // Find video stream index
-     * const videoStreamIndex = streams.findIndex(
-     *   s => s.codecpar.codecType === AVMEDIA_TYPE_VIDEO
-     * );
+     * Zero-based index of this stream in the format context.
+     * Used to identify packets belonging to this stream.
      *
-     * // Check packet's stream
-     * if (packet.streamIndex === videoStreamIndex) {
-     *   // This packet belongs to the video stream
-     * }
-     * ```
+     * Direct mapping to AVStream->index.
      */
     get index(): number;
     /**
-     * Format-specific stream ID.
+     * Stream ID.
      *
-     * Stream ID as defined by the container format.
-     * Different from index - this is format-specific.
+     * Format-specific stream identifier.
+     * May be used by some formats for internal stream identification.
      *
-     * Direct mapping to AVStream->id
-     *
-     * - decoding: Set by libavformat
-     * - encoding: Set by the user, replaced by libavformat if left unset
+     * Direct mapping to AVStream->id.
      */
     get id(): number;
     set id(value: number);
     /**
-     * Codec parameters associated with this stream.
-     *
-     * Contains all the parameters needed to set up a codec for this stream,
-     * including codec ID, dimensions for video, sample rate for audio, etc.
-     *
-     * Direct mapping to AVStream->codecpar
+     * Codec parameters.
      *
-     * - demuxing: Filled by libavformat on stream creation or in findStreamInfo()
-     * - muxing: Must be filled by the caller before writeHeader()
+     * Contains essential codec configuration for this stream.
+     * Used to initialize decoders and describe stream properties.
      *
-     * @example
-     * ```typescript
-     * // For video stream
-     * stream.codecpar.codecType = AVMEDIA_TYPE_VIDEO;
-     * stream.codecpar.codecId = AV_CODEC_ID_H264;
-     * stream.codecpar.width = 1920;
-     * stream.codecpar.height = 1080;
-     *
-     * // For audio stream
-     * stream.codecpar.codecType = AVMEDIA_TYPE_AUDIO;
-     * stream.codecpar.codecId = AV_CODEC_ID_AAC;
-     * stream.codecpar.sampleRate = 48000;
-     * stream.codecpar.channels = 2;
-     * ```
-     *
-     * @see {@link CodecParameters} For detailed parameter documentation
+     * Direct mapping to AVStream->codecpar.
      */
     get codecpar(): CodecParameters;
     set codecpar(value: CodecParameters);
     /**
-     * Time base for this stream.
-     *
-     * The fundamental unit of time (in seconds) in terms of which frame
-     * timestamps are represented. For example, a time base of 1/25 means
-     * each time unit is 1/25 of a second (40ms).
-     *
-     * Direct mapping to AVStream->time_base
-     *
-     * - decoding: Set by libavformat
-     * - encoding: May be set before writeHeader() as a hint to the muxer.
-     *             The muxer will overwrite with the actual timebase used.
-     *
-     * @example
-     * ```typescript
-     * import { Rational } from 'node-av';
-     *
-     * // Common time bases
-     * stream.timeBase = new Rational(1, 90000); // 90kHz (MPEG-TS)
-     * stream.timeBase = new Rational(1, 1000); // milliseconds
-     * stream.timeBase = new Rational(1, 25); // 25 fps video
+     * Stream time base.
      *
-     * // Convert PTS to seconds
-     * const pts = 45000n;
-     * const seconds = Number(pts) * stream.timeBase.toDouble();
-     * ```
+     * Unit of time for timestamps in this stream.
+     * All timestamps (PTS/DTS) are in units of this time base.
      *
-     * @see {@link Rational} For time base representation
+     * Direct mapping to AVStream->time_base.
      */
     get timeBase(): Rational;
     set timeBase(value: Rational);
     /**
-     * Decoding: pts of the first frame of the stream in presentation order, in stream time base.
+     * Start time.
      *
-     * Direct mapping to AVStream->start_time
+     * First timestamp of the stream in stream time base units.
+     * AV_NOPTS_VALUE if unknown.
      *
-     * Only set this if you are absolutely 100% sure that the value you set
-     * it to really is the pts of the first frame.
-     * This may be undefined (AV_NOPTS_VALUE).
-     *
-     * @note The ASF header does NOT contain a correct start_time the ASF
-     * demuxer must NOT set this.
+     * Direct mapping to AVStream->start_time.
      */
     get startTime(): bigint;
     set startTime(value: bigint);
     /**
-     * Decoding: duration of the stream, in stream time base.
-     *
-     * Direct mapping to AVStream->duration
+     * Stream duration.
      *
-     * If a source file does not specify a duration, but does specify
-     * a bitrate, this value will be estimated from bitrate and file size.
+     * Total duration in stream time base units.
+     * AV_NOPTS_VALUE if unknown.
      *
-     * Encoding: May be set by the caller before avformat_write_header() to
-     * provide a hint to the muxer about the estimated duration.
+     * Direct mapping to AVStream->duration.
      */
     get duration(): bigint;
     set duration(value: bigint);
     /**
-     * Number of frames in this stream if known or 0.
+     * Number of frames.
      *
-     * Direct mapping to AVStream->nb_frames
+     * Total number of frames in this stream.
+     * 0 if unknown.
+     *
+     * Direct mapping to AVStream->nb_frames.
      */
     get nbFrames(): bigint;
     set nbFrames(value: bigint);
     /**
-     * Stream disposition - a combination of AV_DISPOSITION_* flags.
-     *
-     * Direct mapping to AVStream->disposition
+     * Stream disposition flags.
      *
-     * - demuxing: set by libavformat when creating the stream or in
-     *             avformat_find_stream_info().
-     * - muxing: may be set by the caller before avformat_write_header().
+     * Combination of AV_DISPOSITION_* flags indicating stream properties
+     * (e.g., default, forced subtitles, visual impaired, etc.).
      *
-     * Common flags:
-     * - AV_DISPOSITION_DEFAULT: default track
-     * - AV_DISPOSITION_ATTACHED_PIC: stream is an attached picture (album art)
-     * - AV_DISPOSITION_CAPTIONS: stream contains captions
-     * - AV_DISPOSITION_DESCRIPTIONS: stream contains descriptions
-     * - AV_DISPOSITION_METADATA: stream contains metadata
+     * Direct mapping to AVStream->disposition.
      */
     get disposition(): AVDisposition;
     set disposition(value: AVDisposition);
     /**
-     * Selects which packets can be discarded at will and do not need to be demuxed.
+     * Discard setting.
      *
-     * Direct mapping to AVStream->discard
+     * Indicates which packets can be discarded during demuxing.
+     * Used to skip non-essential packets for performance.
      *
-     * - AVDISCARD_NONE: discard nothing
-     * - AVDISCARD_DEFAULT: discard useless packets like 0 size packets in avi
-     * - AVDISCARD_NONREF: discard all non reference
-     * - AVDISCARD_BIDIR: discard all bidirectional frames
-     * - AVDISCARD_NONINTRA: discard all non intra frames
-     * - AVDISCARD_NONKEY: discard all frames except keyframes
-     * - AVDISCARD_ALL: discard all
+     * Direct mapping to AVStream->discard.
      */
     get discard(): AVDiscard;
     set discard(value: AVDiscard);
     /**
-     * Sample aspect ratio (0 if unknown).
+     * Sample aspect ratio.
      *
-     * Direct mapping to AVStream->sample_aspect_ratio
+     * Pixel aspect ratio for video streams.
+     * 0/1 if unknown or not applicable.
      *
-     * This is the width of a pixel divided by the height of the pixel.
-     * - encoding: Set by user.
-     * - decoding: Set by libavformat.
+     * Direct mapping to AVStream->sample_aspect_ratio.
      */
     get sampleAspectRatio(): Rational;
     set sampleAspectRatio(value: Rational);
     /**
-     * Average framerate.
+     * Average frame rate.
      *
-     * Direct mapping to AVStream->avg_frame_rate
+     * Average framerate of the stream.
+     * 0/1 if unknown or variable frame rate.
      *
-     * - demuxing: May be set by libavformat when creating the stream or in
-     *             avformat_find_stream_info().
-     * - muxing: May be set by the caller before avformat_write_header().
+     * Direct mapping to AVStream->avg_frame_rate.
      */
     get avgFrameRate(): Rational;
     set avgFrameRate(value: Rational);
     /**
-     * Real base framerate of the stream.
+     * Real frame rate.
      *
-     * Direct mapping to AVStream->r_frame_rate
+     * Real base frame rate of the stream.
+     * This is the lowest common multiple of all frame rates in the stream.
      *
-     * This is the lowest framerate with which all timestamps can be
-     * represented accurately (it is the least common multiple of all
-     * framerates in the stream). Note, this value is just a guess!
-     * For example, if the time base is 1/90000 and all frames have either
-     * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
+     * Direct mapping to AVStream->r_frame_rate.
      */
     get rFrameRate(): Rational;
     set rFrameRate(value: Rational);
     /**
-     * Metadata dictionary for this stream.
+     * Stream metadata.
      *
-     * Direct mapping to AVStream->metadata
+     * Dictionary containing stream-specific metadata
+     * (e.g., language, title, encoder settings).
      *
-     * Contains key-value pairs of metadata.
+     * Direct mapping to AVStream->metadata.
      */
     get metadata(): Dictionary | null;
     set metadata(value: Dictionary | null);
     /**
-     * For streams with AV_DISPOSITION_ATTACHED_PIC disposition, this packet
-     * will contain the attached picture (e.g., album art).
+     * Attached picture.
      *
-     * Direct mapping to AVStream->attached_pic
+     * For streams with AV_DISPOSITION_ATTACHED_PIC set,
+     * contains the attached picture (e.g., album art).
      *
-     * - decoding: set by libavformat, must not be modified by the caller.
-     * - encoding: unused
-     * @readonly
+     * Direct mapping to AVStream->attached_pic.
      */
     get attachedPic(): Packet | null;
     /**
-     * Flags indicating events happening on the stream, a combination of
-     * AVSTREAM_EVENT_FLAG_*.
+     * Event flags.
      *
-     * Direct mapping to AVStream->event_flags
+     * Flags indicating events that happened to the stream.
+     * Used for signaling format changes.
      *
-     * - demuxing: may be set by the demuxer in avformat_open_input(),
-     *   avformat_find_stream_info() and av_read_frame(). Flags must be cleared
-     *   by the user once the event has been handled.
-     * - muxing: may be set by the user after avformat_write_header() to
-     *   indicate a user-triggered event. The muxer will clear the flags for
-     *   events it has handled in av_[interleaved]_write_frame().
-     *
-     * Flags:
-     * - AVSTREAM_EVENT_FLAG_METADATA_UPDATED: metadata was updated
-     * - AVSTREAM_EVENT_FLAG_NEW_PACKETS: new packets were read for this stream
+     * Direct mapping to AVStream->event_flags.
      */
     get eventFlags(): AVStreamEventFlag;
     set eventFlags(value: AVStreamEventFlag);
     /**
-     * Get the native FFmpeg AVStream pointer.
+     * Get the underlying native Stream object.
+     *
+     * @returns The native Stream binding object
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native stream object
+     * @internal
      */
     getNative(): NativeStream;
 }