Merge main into release for tag v1.26.0

dev/convert.html

@@ -100,9 +100,10 @@
 			},
 			*/
 			video: () => ({
-				width: 720,
-				frameRate: 30,
-				bitrate: Mediabunny.QUALITY_VERY_LOW,
+				allowRotationMetadata: false,
+				//width: 720,
+				//frameRate: 30,
+				//bitrate: Mediabunny.QUALITY_VERY_LOW,
 				//discard: true,
 				/*
 				process: (sample) => {
@@ -180,7 +181,7 @@
 			},
 			trim: {
 				start: 0,
-				end: 20
+				end: 4
 			},
 		});
 		console.log(conversion);

dev/live.html

@@ -25,29 +25,41 @@
             target: new Mediabunny.BufferTarget(),
             format: new Mediabunny.Mp4OutputFormat(),
         });
+		let videoSource = null;
+		let audioSource = null;
         if (videoTrack) {
-            const source = new Mediabunny.MediaStreamVideoTrackSource(videoTrack, {
+            videoSource = new Mediabunny.MediaStreamVideoTrackSource(videoTrack, {
                 codec: 'avc',
                 bitrate: Mediabunny.QUALITY_MEDIUM
             });
 
-            source.errorPromise.catch((d) => console.log("Hello?????", d));
+            videoSource.errorPromise.catch((d) => console.log("Hello?????", d));
 
-            output.addVideoTrack(source);
+            output.addVideoTrack(videoSource);
         }
         if (audioTrack) {
-            const source = new Mediabunny.MediaStreamAudioTrackSource(audioTrack, {
+            audioSource = new Mediabunny.MediaStreamAudioTrackSource(audioTrack, {
                 codec: 'mp3',
                 bitrate: Mediabunny.QUALITY_MEDIUM
             });
 
-            source.errorPromise.catch((d) => console.log("Hello!!???", d));
+            audioSource.errorPromise.catch((d) => console.log("Hello!!???", d));
 
-            output.addAudioTrack(source);
+            output.addAudioTrack(audioSource);
         }
 
         await output.start();
 
+		setTimeout(() => {
+			videoSource?.pause();
+			audioSource?.pause();
+
+			setTimeout(() => {
+				videoSource?.resume();
+				audioSource?.resume();
+			}, 1000);
+		}, 1000);
+
         await new Promise(resolve => setTimeout(resolve, 5000));
 
         await output.finalize();

docs/guide/converting-media-files.md

@@ -120,6 +120,7 @@ type ConversionVideoOptions = {
 	height?: number;
 	fit?: 'fill' | 'contain' | 'cover';
 	rotate?: 0 | 90 | 180 | 270;
+	allowRotationMetadata?: boolean;
 	crop?: { left: number; top: number; width: number; height: number };
 	frameRate?: number;
 	codec?: VideoCodec;
@@ -175,6 +176,8 @@ In the rare case that the input video changes size over time, the `fit` field ca
 
 `rotation` rotates the video by the specified number of degrees clockwise. This rotation is applied on top of any rotation metadata in the original input file and happens before cropping and resizing.
 
+By default, Mediabunny will try to make use of rotation metadata in the output file to perform the rotation whenever possible. However, if you don't want this to happen, or you want to use Mediabunny to strip all rotation metadata from a file, you can set `allowRotationMetadata` to `false`.
+
 ### Cropping video
 
 `crop` can be used to extract a rectangular region from the original video. The rectangle is specified using `left`, `top`, `width` and `height` and is clamped to the dimensions of the video. Cropping is applied after rotation but before resizing.

docs/guide/media-sources.md

@@ -187,6 +187,16 @@ videoTrackSource.errorPromise.catch((error) => ...);
 
 This source requires no additional method calls; data will automatically be captured and piped to the output file as soon as `start()` is called on the `Output`. Make sure to `stop()` on `videoTrack` after finalizing the `Output` if you don't need the user's media anymore.
 
+If you want to temporarily stop capturing video frames from this source, you can use the `pause()` and `resume()` methods:
+```ts
+videoTrackSource.pause();
+
+// Later:
+videoTrackSource.resume();
+```
+
+While paused, video frames emitted by the stream will be ignored. When resumed, video frames are let through again, offset in timestamp such that the result plays back continuously with no gap in playback. Note that pausing does *not* stop the underlying media stream.
+
 ::: info
 If this source is the only MediaStreamTrack source in the `Output`, then the first video sample added by it starts at timestamp 0. If there are multiple, then the earliest media sample across all tracks starts at timestamp 0, and all tracks will be perfectly synchronized with each other.
 :::
@@ -344,6 +354,16 @@ audioTrackSource.errorPromise.catch((error) => ...);
 
 This source requires no additional method calls; data will automatically be captured and piped to the output file as soon as `start()` is called on the `Output`. Make sure to `stop()` on `audioTrack` after finalizing the `Output` if you don't need the user's media anymore.
 
+If you want to temporarily stop capturing audio data from this source, you can use the `pause()` and `resume()` methods:
+```ts
+audioTrackSource.pause();
+
+// Later:
+audioTrackSource.resume();
+```
+
+While paused, audio data emitted by the stream will be ignored. When resumed, audio data are let through again, offset in timestamp such that the result plays back continuously with no gap in playback. Note that pausing does *not* stop the underlying media stream.
+
 ::: info
 If this source is the only MediaStreamTrack source in the `Output`, then the first audio sample added by it starts at timestamp 0. If there are multiple, then the earliest media sample across all tracks starts at timestamp 0, and all tracks will be perfectly synchronized with each other.
 :::

docs/index.md

@@ -124,6 +124,7 @@ const sponsors = {
 		{ image: 'https://avatars.githubusercontent.com/u/97225946', name: '808vita', url: 'https://github.com/808vita' },
 		{ image: 'https://avatars.githubusercontent.com/u/3709646', name: 'Rodrigo Belfiore', url: 'https://github.com/roprgm' },
 		{ image: 'https://avatars.githubusercontent.com/u/31102694', name: 'Aiden Liu', url: 'https://github.com/aidenlx' },
+		{ image: 'https://avatars.githubusercontent.com/u/41021374', name: 'arthco', url: 'https://github.com/arthtyagi' },
 	],
 };
 </script>

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "mediabunny",
-  "version": "1.25.8",
+  "version": "1.26.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mediabunny",
-      "version": "1.25.8",
+      "version": "1.26.0",
       "license": "MPL-2.0",
       "workspaces": [
         "packages/*"
@@ -7739,9 +7739,9 @@
       }
     },
     "node_modules/mediabunny": {
-      "version": "1.25.7",
-      "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.25.7.tgz",
-      "integrity": "sha512-DL0E1h29HTDaD9bYRXLSSHiAoLbDBksrdYS+4OHWA+aNhQeN+CAGEG7EU6wlhPZ8MOpwXIeC7uv06lo4ziohQQ==",
+      "version": "1.25.8",
+      "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.25.8.tgz",
+      "integrity": "sha512-2WCa9WtEbHOvg5rAWXQjVE+O/r01fpj65ymZdA2XhIeaWmdDQ40p32F0WY6tdBi+aeY+4ldwhAOpo0eyVrYTGg==",
       "license": "MPL-2.0",
       "peer": true,
       "workspaces": [
@@ -12065,7 +12065,7 @@
     },
     "packages/mp3-encoder": {
       "name": "@mediabunny/mp3-encoder",
-      "version": "1.25.8",
+      "version": "1.26.0",
       "license": "MPL-2.0",
       "devDependencies": {
         "@types/emscripten": "^1.40.1"

package.json

@@ -1,7 +1,7 @@
 {
   "name": "mediabunny",
   "author": "Vanilagy",
-  "version": "1.25.8",
+  "version": "1.26.0",
   "description": "Pure TypeScript media toolkit for reading, writing, and converting media files, directly in the browser.",
   "type": "module",
   "workspaces": [

packages/mp3-encoder/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediabunny/mp3-encoder",
   "author": "Vanilagy",
-  "version": "1.25.8",
+  "version": "1.26.0",
   "description": "MP3 encoder extension for Mediabunny, based on LAME.",
   "main": "./dist/bundles/mediabunny-mp3-encoder.mjs",
   "module": "./dist/bundles/mediabunny-mp3-encoder.mjs",

src/conversion.ts

@@ -143,6 +143,12 @@ export type ConversionVideoOptions = {
 	 * This rotation is _in addition to_ the natural rotation of the input video as specified in input file's metadata.
 	 */
 	rotate?: Rotation;
+	/**
+	 * Defaults to `true`. When enabaled, Mediabunny will use the rotation metadata in the output file to perform video
+	 * rotation whenever possible. Set this field to `false` if you want to ensure the output file does not make use of
+	 * rotation metadata and that any rotation is baked into the video frames directly.
+	 */
+	allowRotationMetadata?: boolean;
 	/**
 	 * Specifies the rectangular region of the input video to crop to. The crop region will automatically be clamped to
 	 * the dimensions of the input video track. Cropping is performed after rotation but before resizing.
@@ -304,6 +310,9 @@ const validateVideoOptions = (videoOptions: ConversionVideoOptions | undefined)
 	if (videoOptions?.rotate !== undefined && ![0, 90, 180, 270].includes(videoOptions.rotate)) {
 		throw new TypeError('options.video.rotate, when provided, must be 0, 90, 180 or 270.');
 	}
+	if (videoOptions?.allowRotationMetadata !== undefined && typeof videoOptions.allowRotationMetadata !== 'boolean') {
+		throw new TypeError('options.video.allowRotationMetadata, when provided, must be a boolean.');
+	}
 	if (videoOptions?.crop !== undefined) {
 		validateCropRectangle(videoOptions.crop, 'options.video.');
 	}
@@ -838,7 +847,8 @@ export class Conversion {
 		let videoSource: VideoSource;
 
 		const totalRotation = normalizeRotation(track.rotation + (trackOptions.rotate ?? 0));
-		const outputSupportsRotation = this.output.format.supportsVideoRotationMetadata;
+		const canUseRotationMetadata = this.output.format.supportsVideoRotationMetadata
+			&& (trackOptions.allowRotationMetadata ?? true);
 
 		const [rotatedWidth, rotatedHeight] = totalRotation % 180 === 0
 			? [track.codedWidth, track.codedHeight]
@@ -883,7 +893,7 @@ export class Conversion {
 			// TODO This is suboptimal: Forcing a rerender when both rotation and process are set is not
 			// performance-optimal, but right now there's no other way because we can't change the track rotation
 			// metadata after the output has already started. Should be possible with API changes in v2, though!
-			|| (totalRotation !== 0 && (!outputSupportsRotation || trackOptions.process !== undefined))
+			|| (totalRotation !== 0 && (!canUseRotationMetadata || trackOptions.process !== undefined))
 			|| !!crop;
 
 		const alpha = trackOptions.alpha ?? 'discard';

src/media-source.ts

@@ -1055,6 +1055,12 @@ export class MediaStreamVideoTrackSource extends VideoSource {
 	private _promiseWithResolvers = promiseWithResolvers();
 	/** @internal */
 	private _errorPromiseAccessed = false;
+	/** @internal */
+	private _paused = false;
+	/** @internal */
+	private _lastSampleTimestamp: number | null = null;
+	/** @internal */
+	private _pauseOffset = 0;
 
 	/** A promise that rejects upon any error within this source. This promise never resolves. */
 	get errorPromise() {
@@ -1062,6 +1068,11 @@ export class MediaStreamVideoTrackSource extends VideoSource {
 		return this._promiseWithResolvers.promise;
 	}
 
+	/** Whether this source is currently paused as a result of calling `.pause()`. */
+	get paused() {
+		return this._paused;
+	}
+
 	/**
 	 * Creates a new {@link MediaStreamVideoTrackSource} from a
 	 * [`MediaStreamVideoTrack`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack), which will pull
@@ -1103,8 +1114,29 @@ export class MediaStreamVideoTrackSource extends VideoSource {
 				return;
 			}
 
+			const currentTimestamp = videoFrame.timestamp / 1e6;
+
+			if (this._paused) {
+				const frameSeen = firstVideoFrameTimestamp !== null;
+				if (frameSeen) {
+					if (this._lastSampleTimestamp !== null) {
+						// In addition to dropping this frame, let's also keep track of the time we have lost due to the
+						// pause. Doing it like this instead of simply keeping track of the paused time is better since
+						// it retains the frame rate of the underlying source.
+						const timeDelta = currentTimestamp - this._lastSampleTimestamp;
+						// We modify this field instead of _timestampOffset since we still might have data in flight
+						// in the encoder, with which we don't want to mess.
+						this._pauseOffset -= timeDelta;
+					}
+					this._lastSampleTimestamp = currentTimestamp;
+				}
+
+				videoFrame.close();
+				return;
+			}
+
 			if (firstVideoFrameTimestamp === null) {
-				firstVideoFrameTimestamp = videoFrame.timestamp / 1e6;
+				firstVideoFrameTimestamp = currentTimestamp;
 
 				const muxer = this._connectedTrack!.output._muxer;
 				if (muxer.firstMediaStreamTimestamp === null) {
@@ -1116,13 +1148,19 @@ export class MediaStreamVideoTrackSource extends VideoSource {
 				}
 			}
 
+			this._lastSampleTimestamp = currentTimestamp;
+
 			if (this._encoder.getQueueSize() >= 4) {
 				// Drop frames if the encoder is overloaded
 				videoFrame.close();
 				return;
 			}
 
-			void this._encoder.add(new VideoSample(videoFrame), true)
+			const sample = new VideoSample(videoFrame, {
+				timestamp: currentTimestamp + this._pauseOffset,
+			});
+
+			void this._encoder.add(sample, true)
 				.catch((error) => {
 					errored = true;
 
@@ -1182,6 +1220,19 @@ export class MediaStreamVideoTrackSource extends VideoSource {
 		}
 	}
 
+	/**
+	 * Pauses the capture of video frames - any video frames emitted by the underlying media stream will be ignored
+	 * while paused. This does *not* close the underlying `MediaStreamVideoTrack`, it just ignores its output.
+	 */
+	pause() {
+		this._paused = true;
+	}
+
+	/** Resumes the capture of video frames after being paused. */
+	resume() {
+		this._paused = false;
+	}
+
 	/** @internal */
 	override async _flushAndClose(forceClose: boolean) {
 		if (this._abortController) {
@@ -1857,6 +1908,12 @@ export class MediaStreamAudioTrackSource extends AudioSource {
 	private _promiseWithResolvers = promiseWithResolvers();
 	/** @internal */
 	private _errorPromiseAccessed = false;
+	/** @internal */
+	private _paused = false;
+	/** @internal */
+	private _lastSampleTimestamp: number | null = null;
+	/** @internal */
+	private _pauseOffset = 0;
 
 	/** A promise that rejects upon any error within this source. This promise never resolves. */
 	get errorPromise() {
@@ -1864,6 +1921,11 @@ export class MediaStreamAudioTrackSource extends AudioSource {
 		return this._promiseWithResolvers.promise;
 	}
 
+	/** Whether this source is currently paused as a result of calling `.pause()`. */
+	get paused() {
+		return this._paused;
+	}
+
 	/**
 	 * Creates a new {@link MediaStreamAudioTrackSource} from a `MediaStreamAudioTrack`, which will pull audio samples
 	 * from the stream in real time and encode them according to {@link AudioEncodingConfig}.
@@ -1890,38 +1952,74 @@ export class MediaStreamAudioTrackSource extends AudioSource {
 
 		this._abortController = new AbortController();
 
+		let firstAudioDataTimestamp: number | null = null;
+		let errored = false;
+
+		const onAudioSample = (audioSample: AudioSample) => {
+			if (errored) {
+				audioSample.close();
+				return;
+			}
+
+			const currentTimestamp = audioSample.timestamp;
+
+			if (this._paused) {
+				const dataSeen = firstAudioDataTimestamp !== null;
+				if (dataSeen) {
+					if (this._lastSampleTimestamp !== null) {
+						// In addition to dropping this sample, let's also keep track of the time we have lost due to
+						// the pause. Doing it like this instead of simply keeping track of the paused time is better
+						// since it retains the sample rate of the underlying source.
+						const timeDelta = currentTimestamp - this._lastSampleTimestamp;
+						// We modify this field instead of _timestampOffset since we still might have data in flight
+						// in the encoder, with which we don't want to mess.
+						this._pauseOffset -= timeDelta;
+					}
+					this._lastSampleTimestamp = currentTimestamp;
+				}
+
+				audioSample.close();
+				return;
+			}
+
+			if (firstAudioDataTimestamp === null) {
+				firstAudioDataTimestamp = audioSample.timestamp;
+
+				const muxer = this._connectedTrack!.output._muxer;
+				if (muxer.firstMediaStreamTimestamp === null) {
+					muxer.firstMediaStreamTimestamp = performance.now() / 1000;
+					this._timestampOffset = -firstAudioDataTimestamp;
+				} else {
+					this._timestampOffset = (performance.now() / 1000 - muxer.firstMediaStreamTimestamp)
+						- firstAudioDataTimestamp;
+				}
+			}
+
+			this._lastSampleTimestamp = currentTimestamp;
+
+			if (this._encoder.getQueueSize() >= 4) {
+				// Drop data if the encoder is overloaded
+				audioSample.close();
+				return;
+			}
+
+			audioSample.setTimestamp(currentTimestamp + this._pauseOffset);
+
+			void this._encoder.add(audioSample, true)
+				.catch((error) => {
+					errored = true;
+
+					this._abortController?.abort();
+					this._promiseWithResolvers.reject(error);
+					void this._audioContext?.suspend();
+				});
+		};
+
 		if (typeof MediaStreamTrackProcessor !== 'undefined') {
 			// Great, MediaStreamTrackProcessor is supported, this is the preferred way of doing things
-			let firstAudioDataTimestamp: number | null = null;
-
 			const processor = new MediaStreamTrackProcessor({ track: this._track });
 			const consumer = new WritableStream<AudioData>({
-				write: (audioData) => {
-					if (firstAudioDataTimestamp === null) {
-						firstAudioDataTimestamp = audioData.timestamp / 1e6;
-
-						const muxer = this._connectedTrack!.output._muxer;
-						if (muxer.firstMediaStreamTimestamp === null) {
-							muxer.firstMediaStreamTimestamp = performance.now() / 1000;
-							this._timestampOffset = -firstAudioDataTimestamp;
-						} else {
-							this._timestampOffset = (performance.now() / 1000 - muxer.firstMediaStreamTimestamp)
-								- firstAudioDataTimestamp;
-						}
-					}
-
-					if (this._encoder.getQueueSize() >= 4) {
-						// Drop data if the encoder is overloaded
-						audioData.close();
-						return;
-					}
-
-					void this._encoder.add(new AudioSample(audioData), true)
-						.catch((error) => {
-							this._abortController?.abort();
-							this._promiseWithResolvers.reject(error);
-						});
-				},
+				write: audioData => onAudioSample(new AudioSample(audioData)),
 			});
 
 			processor.readable.pipeTo(consumer, {
@@ -1949,7 +2047,6 @@ export class MediaStreamAudioTrackSource extends AudioSource {
 			sourceNode.connect(this._scriptProcessorNode);
 			this._scriptProcessorNode.connect(this._audioContext.destination);
 
-			let audioReceived = false;
 			let totalDuration = 0;
 
 			this._scriptProcessorNode.onaudioprocess = (event) => {
@@ -1957,33 +2054,25 @@ export class MediaStreamAudioTrackSource extends AudioSource {
 				totalDuration += event.inputBuffer.duration;
 
 				for (const audioSample of iterator) {
-					if (!audioReceived) {
-						audioReceived = true;
-
-						const muxer = this._connectedTrack!.output._muxer;
-						if (muxer.firstMediaStreamTimestamp === null) {
-							muxer.firstMediaStreamTimestamp = performance.now() / 1000;
-						} else {
-							this._timestampOffset = performance.now() / 1000 - muxer.firstMediaStreamTimestamp;
-						}
-					}
-
-					if (this._encoder.getQueueSize() >= 4) {
-						// Drop data if the encoder is overloaded
-						audioSample.close();
-						continue;
-					}
-
-					void this._encoder.add(audioSample, true)
-						.catch((error) => {
-							void this._audioContext!.suspend();
-							this._promiseWithResolvers.reject(error);
-						});
+					onAudioSample(audioSample);
 				}
 			};
 		}
 	}
 
+	/**
+	 * Pauses the capture of audio data - any audio data emitted by the underlying media stream will be ignored
+	 * while paused. This does *not* close the underlying `MediaStreamAudioTrack`, it just ignores its output.
+	 */
+	pause() {
+		this._paused = true;
+	}
+
+	/** Resumes the capture of audio data after being paused. */
+	resume() {
+		this._paused = false;
+	}
+
 	/** @internal */
 	override async _flushAndClose(forceClose: boolean) {
 		if (this._abortController) {