Merge main into release for tag v1.39.0

docs/guide/media-sinks.md

@@ -97,9 +97,13 @@ await sink.getKeyPacket(5); // => EncodedPacket | null
 
 When retrieving a packet using a timestamp, the last packet (in [presentation order](#decode-vs-presentation-order)) with a timestamp less than or equal to the search timestamp will be returned. The methods return `null` if there exists no such packet.
 
-There is a special method for retrieving the first packet (in [decode order](#decode-vs-presentation-order)):
+There are special methods for retrieving the first packet (in [decode order](#decode-vs-presentation-order)):
 ```ts
 await sink.getFirstPacket(); // => EncodedPacket | null
+
+// The first packet is typically a key frame, but this is not required.
+// This method returns the first key frame:
+await sink.getFirstKeyPacket(); // => EncodedPacket | null
 ```
 The last packet (in [presentation order](#decode-vs-presentation-order)) can be retrieved like so:
 ```ts

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "mediabunny",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mediabunny",
-      "version": "1.38.1",
+      "version": "1.39.0",
       "license": "MPL-2.0",
       "workspaces": [
         "packages/*"
@@ -7751,9 +7751,9 @@
       }
     },
     "node_modules/mediabunny": {
-      "version": "1.38.0",
+      "version": "1.38.1",
-      "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.38.0.tgz",
+      "resolved": "https://registry.npmjs.org/mediabunny/-/mediabunny-1.38.1.tgz",
-      "integrity": "sha512-FiZtTWLY4rmEw4jBx8r5Tk+sE+PcBb03UYUZNv9DujEy9wdmX7JaQOvHNUZLVTxPWT0h+LYmWFnWKRkl4KmzyA==",
+      "integrity": "sha512-iqZjL21WG32qpdlONAyBBnmhLo4EvF+v4wnfe1rXEKT/7ogiYOZnQGL8TZi7QIFV71DSg7a64egFWUgf3oeSYA==",
       "license": "MPL-2.0",
       "peer": true,
       "workspaces": [
@@ -12077,7 +12077,7 @@
     },
     "packages/aac-encoder": {
       "name": "@mediabunny/aac-encoder",
-      "version": "1.38.1",
+      "version": "1.39.0",
       "license": "MPL-2.0",
       "devDependencies": {
         "@types/emscripten": "^1.40.1"
@@ -12092,7 +12092,7 @@
     },
     "packages/ac3": {
       "name": "@mediabunny/ac3",
-      "version": "1.38.1",
+      "version": "1.39.0",
       "license": "MPL-2.0",
       "devDependencies": {
         "@types/emscripten": "^1.40.1"
@@ -12107,7 +12107,7 @@
     },
     "packages/flac-encoder": {
       "name": "@mediabunny/flac-encoder",
-      "version": "1.38.1",
+      "version": "1.39.0",
       "license": "MPL-2.0",
       "devDependencies": {
         "@types/emscripten": "^1.40.1"
@@ -12122,7 +12122,7 @@
     },
     "packages/mp3-encoder": {
       "name": "@mediabunny/mp3-encoder",
-      "version": "1.38.1",
+      "version": "1.39.0",
       "license": "MPL-2.0",
       "devDependencies": {
         "@types/emscripten": "^1.40.1"

package.json

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

packages/aac-encoder/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediabunny/aac-encoder",
   "author": "Vanilagy",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "AAC encoder extension for Mediabunny, based on FFmpeg.",
   "main": "./dist/bundles/mediabunny-aac-encoder.mjs",
   "module": "./dist/bundles/mediabunny-aac-encoder.mjs",

packages/ac3/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediabunny/ac3",
   "author": "Vanilagy",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "AC-3 and E-AC-3 (Dolby Digital) decoder and encoder extension for Mediabunny, based on FFmpeg.",
   "main": "./dist/bundles/mediabunny-ac3.mjs",
   "module": "./dist/bundles/mediabunny-ac3.mjs",

packages/flac-encoder/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediabunny/flac-encoder",
   "author": "Vanilagy",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "FLAC encoder extension for Mediabunny, based on libFLAC.",
   "main": "./dist/bundles/mediabunny-flac-encoder.mjs",
   "module": "./dist/bundles/mediabunny-flac-encoder.mjs",

packages/mp3-encoder/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mediabunny/mp3-encoder",
   "author": "Vanilagy",
-  "version": "1.38.1",
+  "version": "1.39.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/media-sink.ts

@@ -144,6 +144,23 @@ export class EncodedPacketSink {
 		return maybeFixPacketType(this._track, this._track._backing.getFirstPacket(options), options);
 	}
 
+	/** Retrieves the track's first key packet (in decode order), or null if it has no key packets. */
+	async getFirstKeyPacket(options: PacketRetrievalOptions = {}) {
+		validatePacketRetrievalOptions(options);
+
+		const firstPacket = await this.getFirstPacket(options);
+		if (!firstPacket) {
+			return null;
+		}
+
+		if (firstPacket.type === 'key') {
+			// Great
+			return firstPacket;
+		}
+
+		return this.getNextKeyPacket(firstPacket, options);
+	}
+
 	/**
 	 * Retrieves the packet corresponding to the given timestamp, in seconds. More specifically, returns the last packet
 	 * (in presentation order) with a start timestamp less than or equal to the given timestamp. This method can be
@@ -476,7 +493,7 @@ export abstract class BaseMediaSampleSink<
 
 			const packetSink = this._createPacketSink();
 			const keyPacket = await packetSink.getKeyPacket(startTimestamp, { verifyKeyPackets: true })
-				?? await packetSink.getFirstPacket();
+				?? await packetSink.getFirstKeyPacket({ verifyKeyPackets: true });
 
 			let currentPacket: EncodedPacket | null = keyPacket;