Add packet type derivation logic, new verifyKeyPackets options, new determinePacketType method

docs/guide/media-sinks.md

@@ -144,6 +144,32 @@ for await (const packet of sink.packets(start, end)) {
 
 The `packets` method is more performant than manual iteration as it will intelligently preload future packets before they are needed.
 
+#### Verifying key packets
+
+By default, packet types are determined using the metadata provided by the containing file. Some files can erroneously label some delta packets as key packets, leading to potential decoder errors. To be guaranteed that a key packet is actually a key packet, you can enable the `verifyKeyPackets` option:
+```ts
+// If the packet returned by this method has type: 'key', it's guaranteed
+// to be a key packet.
+await sink.getPacket(5, { verifyKeyPackets: true });
+
+// Returned packets are guaranteed to be key packets
+await sink.getKeyPacket(10, { verifyKeyPackets: true });
+await sink.getNextKeyPacket(packet, { verifyKeyPackets: true });
+
+// Also works for the iterator:
+for await (const packet of sink.packets(
+	undefined,
+	undefined,
+	{ verifyKeyPackets: true },
+)) {
+	// ...
+}
+```
+
+::: info
+`verifyKeyPackets` only works when `metadataOnly` is not also enabled.
+:::
+
 #### Metadata-only packet retrieval
 
 Sometimes, you're only interested in a packet's metadata (timestamp, duration, type, ...) and not in its encoded media data. All methods on `EncodedPacketSink` accept a final `options` parameter which you can use to retrieve [metadata-only packets](./packets-and-samples#metadata-only-packets):

docs/guide/packets-and-samples.md

@@ -133,6 +133,16 @@ encodedPacket.type; // => PacketType ('key' | 'delta')
 
 For example, in a video track, it is common to have a key frame about every few seconds. When seeking, if the user seeks to a position shortly after a key frame, the decoded data can be shown quickly; if they seek far away from a key frame, the decoder must first crunch through many delta frames before it can show anything.
 
+#### Determining a packet's actual type
+
+The `type` field is derived from metadata in the containing file, which can sometimes (in rare cases) be incorrect. To determine a packet's actual type with certainty, you can do this:
+```ts
+// `packet` must come from the InputTrack `track`
+const type = await track.determinePacketType(packet); // => PacketType | null
+```
+
+This determines the packet's type by looking into its bitstream. `null` is returned when the type couldn't be determined.
+
 ---
 
 You can query the packet's timing information: