mediabunny 1.0.2 → 1.0.4

package/dist/modules/media-source.d.ts

@@ -0,0 +1,230 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { AudioCodec, Quality, SubtitleCodec, VideoCodec } from './codec';
+import { EncodedPacket } from './packet';
+import { AudioSample, VideoSample } from './sample';
+/**
+ * Base class for media sources. Media sources are used to add media samples to an output file.
+ * @public
+ */
+export declare abstract class MediaSource {
+    /**
+     * Closes this source. This prevents future samples from being added and signals to the output file that no further
+     * samples will come in for this track. Calling `.close()` is optional but recommended after adding the
+     * last sample - for improved performance and reduced memory usage.
+     */
+    close(): void;
+}
+/**
+ * Base class for video sources - sources for video tracks.
+ * @public
+ */
+export declare abstract class VideoSource extends MediaSource {
+    constructor(codec: VideoCodec);
+}
+/**
+ * The most basic video source; can be used to directly pipe encoded packets into the output file.
+ * @public
+ */
+export declare class EncodedVideoPacketSource extends VideoSource {
+    constructor(codec: VideoCodec);
+    /**
+     * Adds an encoded packet to the output video track.
+     *
+     * @param meta - Additional metadata from the encoder. You should pass this for the first call, including a valid
+     * decoder config.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(packet: EncodedPacket, meta?: EncodedVideoChunkMetadata): Promise<void>;
+}
+/**
+ * Configuration object that controls video encoding. Can be used to set codec, quality, and more.
+ * @public
+ */
+export type VideoEncodingConfig = {
+    /** The video codec that should be used for encoding the video samples (frames). */
+    codec: VideoCodec;
+    /**
+     * The target bitrate for the encoded video, in bits per second. Alternatively, a subjective Quality can
+     * be provided.
+     */
+    bitrate: number | Quality;
+    /** The latency mode used by the encoder; controls the performance-quality tradeoff. */
+    latencyMode?: VideoEncoderConfig['latencyMode'];
+    /**
+     * The interval, in seconds, of how often frames are encoded as a key frame. The default is 5 seconds. Frequent key
+     * frames improve seeking behavior but increase file size. When using multiple video tracks, you should give them
+     * all the same key frame interval.
+     */
+    keyFrameInterval?: number;
+    /**
+     * The full codec string as specified in the WebCodecs Codec Registry. This string must match the codec
+     * specified in `codec`. When not set, a fitting codec string will be constructed automatically by the library.
+     */
+    fullCodecString?: string;
+    /** Called for each successfully encoded packet. Both the packet and the encoding metadata are passed. */
+    onEncodedPacket?: (packet: EncodedPacket, meta: EncodedVideoChunkMetadata | undefined) => unknown;
+    /** Called when the internal encoder config, as used by the WebCodecs API, is created. */
+    onEncoderConfig?: (config: VideoEncoderConfig) => unknown;
+};
+/**
+ * This source can be used to add raw, unencoded video samples (frames) to an output video track. These frames will
+ * automatically be encoded and then piped into the output.
+ * @public
+ */
+export declare class VideoSampleSource extends VideoSource {
+    constructor(encodingConfig: VideoEncodingConfig);
+    /**
+     * Encodes a video sample (frame) and then adds it to the output.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(videoSample: VideoSample, encodeOptions?: VideoEncoderEncodeOptions): Promise<void>;
+}
+/**
+ * This source can be used to add video frames to the output track from a fixed canvas element. Since canvases are often
+ * used for rendering, this source provides a convenient wrapper around VideoSampleSource.
+ * @public
+ */
+export declare class CanvasSource extends VideoSource {
+    constructor(canvas: HTMLCanvasElement | OffscreenCanvas, encodingConfig: VideoEncodingConfig);
+    /**
+     * Captures the current canvas state as a video sample (frame), encodes it and adds it to the output.
+     *
+     * @param timestamp - The timestamp of the sample, in seconds.
+     * @param duration - The duration of the sample, in seconds.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(timestamp: number, duration?: number, encodeOptions?: VideoEncoderEncodeOptions): Promise<void>;
+}
+/**
+ * Video source that encodes the frames of a MediaStreamVideoTrack and pipes them into the output. This is useful for
+ * capturing live or real-time data such as webcams or screen captures. Frames will automatically start being captured
+ * once the connected Output is started, and will keep being captured until the Output is finalized or this source
+ * is closed.
+ * @public
+ */
+export declare class MediaStreamVideoTrackSource extends VideoSource {
+    constructor(track: MediaStreamVideoTrack, encodingConfig: VideoEncodingConfig);
+}
+/**
+ * Base class for audio sources - sources for audio tracks.
+ * @public
+ */
+export declare abstract class AudioSource extends MediaSource {
+    constructor(codec: AudioCodec);
+}
+/**
+ * The most basic audio source; can be used to directly pipe encoded packets into the output file.
+ * @public
+ */
+export declare class EncodedAudioPacketSource extends AudioSource {
+    constructor(codec: AudioCodec);
+    /**
+     * Adds an encoded packet to the output audio track.
+     *
+     * @param meta - Additional metadata from the encoder. You should pass this for the first call, including a valid
+     * decoder config.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(packet: EncodedPacket, meta?: EncodedAudioChunkMetadata): Promise<void>;
+}
+/**
+ * Configuration object that controls audio encoding. Can be used to set codec, quality, and more.
+ * @public
+ */
+export type AudioEncodingConfig = {
+    /** The audio codec that should be used for encoding the audio samples. */
+    codec: AudioCodec;
+    /**
+     * The target bitrate for the encoded audio, in bits per second. Alternatively, a subjective Quality can
+     * be provided. Required for compressed audio codecs, unused for PCM codecs.
+     */
+    bitrate?: number | Quality;
+    /**
+     * The full codec string as specified in the WebCodecs Codec Registry. This string must match the codec
+     * specified in `codec`. When not set, a fitting codec string will be constructed automatically by the library.
+     */
+    fullCodecString?: string;
+    /** Called for each successfully encoded packet. Both the packet and the encoding metadata are passed. */
+    onEncodedPacket?: (packet: EncodedPacket, meta: EncodedAudioChunkMetadata | undefined) => unknown;
+    /** Called when the internal encoder config, as used by the WebCodecs API, is created. */
+    onEncoderConfig?: (config: AudioEncoderConfig) => unknown;
+};
+/**
+ * This source can be used to add raw, unencoded audio samples to an output audio track. These samples will
+ * automatically be encoded and then piped into the output.
+ * @public
+ */
+export declare class AudioSampleSource extends AudioSource {
+    constructor(encodingConfig: AudioEncodingConfig);
+    /**
+     * Encodes an audio sample and then adds it to the output.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(audioSample: AudioSample): Promise<void>;
+}
+/**
+ * This source can be used to add audio data from an AudioBuffer to the output track. This is useful when working with
+ * the Web Audio API.
+ * @public
+ */
+export declare class AudioBufferSource extends AudioSource {
+    constructor(encodingConfig: AudioEncodingConfig);
+    /**
+     * Converts an AudioBuffer to audio samples, encodes them and adds them to the output. The first AudioBuffer will
+     * be played at timestamp 0, and any subsequent AudioBuffer will have a timestamp equal to the total duration of
+     * all previous AudioBuffers.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(audioBuffer: AudioBuffer): Promise<void[]>;
+}
+/**
+ * Audio source that encodes the data of a MediaStreamAudioTrack and pipes it into the output. This is useful for
+ * capturing live or real-time audio such as microphones or audio from other media elements. Audio will automatically
+ * start being captured once the connected Output is started, and will keep being captured until the Output is
+ * finalized or this source is closed.
+ * @public
+ */
+export declare class MediaStreamAudioTrackSource extends AudioSource {
+    constructor(track: MediaStreamAudioTrack, encodingConfig: AudioEncodingConfig);
+}
+/**
+ * Base class for subtitle sources - sources for subtitle tracks.
+ * @public
+ */
+export declare abstract class SubtitleSource extends MediaSource {
+    constructor(codec: SubtitleCodec);
+}
+/**
+ * This source can be used to add subtitles from a subtitle text file.
+ * @public
+ */
+export declare class TextSubtitleSource extends SubtitleSource {
+    constructor(codec: SubtitleCodec);
+    /**
+     * Parses the subtitle text according to the specified codec and adds it to the output track. You don't have to
+     * add the entire subtitle file at once here; you can provide it in chunks.
+     *
+     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
+     * to respect writer and encoder backpressure.
+     */
+    add(text: string): Promise<void>;
+}
+//# sourceMappingURL=media-source.d.ts.map

package/dist/modules/media-source.d.ts.map

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