mediabunny 1.1.1 → 1.3.0

package/dist/bundles/mediabunny.cjs

@@ -159,6 +159,9 @@ var Mediabunny = (() => {
       return bit;
     }
     readBits(n) {
+      if (n === 1) {
+        return this.readBit();
+      }
       let result = 0;
       for (let i = 0; i < n; i++) {
         result <<= 1;
@@ -189,7 +192,7 @@ var Mediabunny = (() => {
   };
   var readExpGolomb = (bitstream) => {
     let leadingZeroBits = 0;
-    while (bitstream.readBit() === 0 && leadingZeroBits < 32) {
+    while (bitstream.readBits(1) === 0 && leadingZeroBits < 32) {
       leadingZeroBits++;
     }
     if (leadingZeroBits >= 32) {
@@ -1773,6 +1776,31 @@ var Mediabunny = (() => {
     }
     return nalUnits;
   };
+  var findNalUnitsInLengthPrefixed = (packetData, lengthSize) => {
+    const nalUnits = [];
+    let offset = 0;
+    const dataView = new DataView(packetData.buffer, packetData.byteOffset, packetData.byteLength);
+    while (offset + lengthSize <= packetData.length) {
+      let nalUnitLength;
+      if (lengthSize === 1) {
+        nalUnitLength = dataView.getUint8(offset);
+      } else if (lengthSize === 2) {
+        nalUnitLength = dataView.getUint16(offset, false);
+      } else if (lengthSize === 3) {
+        nalUnitLength = (dataView.getUint16(offset, false) << 8) + dataView.getUint8(offset + 2);
+      } else if (lengthSize === 4) {
+        nalUnitLength = dataView.getUint32(offset, false);
+      } else {
+        assertNever(lengthSize);
+        assert(false);
+      }
+      offset += lengthSize;
+      const nalUnit = packetData.subarray(offset, offset + nalUnitLength);
+      nalUnits.push(nalUnit);
+      offset += nalUnitLength;
+    }
+    return nalUnits;
+  };
   var removeEmulationPreventionBytes = (data) => {
     const result = [];
     const len = data.length;
@@ -2348,22 +2376,6 @@ var Mediabunny = (() => {
     return new Uint8Array(bytes2);
   };
   var extractVp9CodecInfoFromPacket = (packet) => {
-    const lastByte = packet[packet.length - 1];
-    if (lastByte && (lastByte & 224) === 192) {
-      const bytesPerFrameSize = ((lastByte & 24) >> 3) + 1;
-      const numFrames = (lastByte & 7) + 1;
-      const indexSize = 2 + numFrames * bytesPerFrameSize;
-      if (packet[packet.length - indexSize] !== lastByte) {
-        return null;
-      }
-      let frameSize = 0;
-      const offset = packet.length - indexSize + 1;
-      for (let i = 0; i < bytesPerFrameSize; i++) {
-        if (!packet[offset + i]) return null;
-        frameSize |= packet[offset + i] << 8 * i;
-      }
-      packet = packet.subarray(0, frameSize);
-    }
     const bitstream = new Bitstream(packet);
     const frameMarker = bitstream.readBits(2);
     if (frameMarker !== 2) {
@@ -2437,13 +2449,12 @@ var Mediabunny = (() => {
       matrixCoefficients
     };
   };
-  var extractAv1CodecInfoFromPacket = (packet) => {
+  function* iterateAv1PacketObus(packet) {
     const bitstream = new Bitstream(packet);
     const readLeb128 = () => {
       let value = 0;
       for (let i = 0; i < 8; i++) {
         const byte = bitstream.readAlignedByte();
-        if (byte === void 0) return 0;
         value |= (byte & 127) << i * 7;
         if (!(byte & 128)) {
           break;
@@ -2458,121 +2469,133 @@ var Mediabunny = (() => {
       return value;
     };
     while (bitstream.getBitsLeft() >= 8) {
-      const obuHeader = bitstream.readBits(8);
-      const obuType = obuHeader >> 3 & 15;
-      const obuExtension = obuHeader >> 2 & 1;
-      const obuHasSizeField = obuHeader >> 1 & 1;
+      bitstream.skipBits(1);
+      const obuType = bitstream.readBits(4);
+      const obuExtension = bitstream.readBits(1);
+      const obuHasSizeField = bitstream.readBits(1);
+      bitstream.skipBits(1);
       if (obuExtension) {
         bitstream.skipBits(8);
       }
       let obuSize;
       if (obuHasSizeField) {
         const obuSizeValue = readLeb128();
-        if (obuSizeValue === null) return null;
+        if (obuSizeValue === null) return;
         obuSize = obuSizeValue;
       } else {
         obuSize = Math.floor(bitstream.getBitsLeft() / 8);
       }
-      if (obuType === 1) {
-        const seqProfile = bitstream.readBits(3);
-        const stillPicture = bitstream.readBits(1);
-        const reducedStillPictureHeader = bitstream.readBits(1);
-        let seqLevel = 0;
-        let seqTier = 0;
-        let bufferDelayLengthMinus1 = 0;
-        if (reducedStillPictureHeader) {
-          seqLevel = bitstream.readBits(5);
-        } else {
-          const timingInfoPresentFlag = bitstream.readBits(1);
-          if (timingInfoPresentFlag) {
-            bitstream.skipBits(32);
-            bitstream.skipBits(32);
-            const equalPictureInterval = bitstream.readBits(1);
-            if (equalPictureInterval) {
-              return null;
-            }
+      assert(bitstream.pos % 8 === 0);
+      yield {
+        type: obuType,
+        data: packet.subarray(bitstream.pos / 8, bitstream.pos / 8 + obuSize)
+      };
+      bitstream.skipBits(obuSize * 8);
+    }
+  }
+  var extractAv1CodecInfoFromPacket = (packet) => {
+    for (const { type, data } of iterateAv1PacketObus(packet)) {
+      if (type !== 1) {
+        continue;
+      }
+      const bitstream = new Bitstream(data);
+      const seqProfile = bitstream.readBits(3);
+      const stillPicture = bitstream.readBits(1);
+      const reducedStillPictureHeader = bitstream.readBits(1);
+      let seqLevel = 0;
+      let seqTier = 0;
+      let bufferDelayLengthMinus1 = 0;
+      if (reducedStillPictureHeader) {
+        seqLevel = bitstream.readBits(5);
+      } else {
+        const timingInfoPresentFlag = bitstream.readBits(1);
+        if (timingInfoPresentFlag) {
+          bitstream.skipBits(32);
+          bitstream.skipBits(32);
+          const equalPictureInterval = bitstream.readBits(1);
+          if (equalPictureInterval) {
+            return null;
           }
-          const decoderModelInfoPresentFlag = bitstream.readBits(1);
-          if (decoderModelInfoPresentFlag) {
-            bufferDelayLengthMinus1 = bitstream.readBits(5);
-            bitstream.skipBits(32);
-            bitstream.skipBits(5);
-            bitstream.skipBits(5);
+        }
+        const decoderModelInfoPresentFlag = bitstream.readBits(1);
+        if (decoderModelInfoPresentFlag) {
+          bufferDelayLengthMinus1 = bitstream.readBits(5);
+          bitstream.skipBits(32);
+          bitstream.skipBits(5);
+          bitstream.skipBits(5);
+        }
+        const operatingPointsCntMinus1 = bitstream.readBits(5);
+        for (let i = 0; i <= operatingPointsCntMinus1; i++) {
+          bitstream.skipBits(12);
+          const seqLevelIdx = bitstream.readBits(5);
+          if (i === 0) {
+            seqLevel = seqLevelIdx;
           }
-          const operatingPointsCntMinus1 = bitstream.readBits(5);
-          for (let i = 0; i <= operatingPointsCntMinus1; i++) {
-            bitstream.skipBits(12);
-            const seqLevelIdx = bitstream.readBits(5);
+          if (seqLevelIdx > 7) {
+            const seqTierTemp = bitstream.readBits(1);
             if (i === 0) {
-              seqLevel = seqLevelIdx;
-            }
-            if (seqLevelIdx > 7) {
-              const seqTierTemp = bitstream.readBits(1);
-              if (i === 0) {
-                seqTier = seqTierTemp;
-              }
+              seqTier = seqTierTemp;
             }
-            if (decoderModelInfoPresentFlag) {
-              const decoderModelPresentForThisOp = bitstream.readBits(1);
-              if (decoderModelPresentForThisOp) {
-                const n = bufferDelayLengthMinus1 + 1;
-                bitstream.skipBits(n);
-                bitstream.skipBits(n);
-                bitstream.skipBits(1);
-              }
-            }
-            const initialDisplayDelayPresentFlag = bitstream.readBits(1);
-            if (initialDisplayDelayPresentFlag) {
-              bitstream.skipBits(4);
+          }
+          if (decoderModelInfoPresentFlag) {
+            const decoderModelPresentForThisOp = bitstream.readBits(1);
+            if (decoderModelPresentForThisOp) {
+              const n = bufferDelayLengthMinus1 + 1;
+              bitstream.skipBits(n);
+              bitstream.skipBits(n);
+              bitstream.skipBits(1);
             }
           }
+          const initialDisplayDelayPresentFlag = bitstream.readBits(1);
+          if (initialDisplayDelayPresentFlag) {
+            bitstream.skipBits(4);
+          }
         }
-        const highBitdepth = bitstream.readBits(1);
-        let bitDepth = 8;
-        if (seqProfile === 2 && highBitdepth) {
-          const twelveBit = bitstream.readBits(1);
-          bitDepth = twelveBit ? 12 : 10;
-        } else if (seqProfile <= 2) {
-          bitDepth = highBitdepth ? 10 : 8;
-        }
-        let monochrome = 0;
-        if (seqProfile !== 1) {
-          monochrome = bitstream.readBits(1);
-        }
-        let chromaSubsamplingX = 1;
-        let chromaSubsamplingY = 1;
-        let chromaSamplePosition = 0;
-        if (!monochrome) {
-          if (seqProfile === 0) {
-            chromaSubsamplingX = 1;
-            chromaSubsamplingY = 1;
-          } else if (seqProfile === 1) {
-            chromaSubsamplingX = 0;
-            chromaSubsamplingY = 0;
-          } else {
-            if (bitDepth === 12) {
-              chromaSubsamplingX = bitstream.readBits(1);
-              if (chromaSubsamplingX) {
-                chromaSubsamplingY = bitstream.readBits(1);
-              }
+      }
+      const highBitdepth = bitstream.readBits(1);
+      let bitDepth = 8;
+      if (seqProfile === 2 && highBitdepth) {
+        const twelveBit = bitstream.readBits(1);
+        bitDepth = twelveBit ? 12 : 10;
+      } else if (seqProfile <= 2) {
+        bitDepth = highBitdepth ? 10 : 8;
+      }
+      let monochrome = 0;
+      if (seqProfile !== 1) {
+        monochrome = bitstream.readBits(1);
+      }
+      let chromaSubsamplingX = 1;
+      let chromaSubsamplingY = 1;
+      let chromaSamplePosition = 0;
+      if (!monochrome) {
+        if (seqProfile === 0) {
+          chromaSubsamplingX = 1;
+          chromaSubsamplingY = 1;
+        } else if (seqProfile === 1) {
+          chromaSubsamplingX = 0;
+          chromaSubsamplingY = 0;
+        } else {
+          if (bitDepth === 12) {
+            chromaSubsamplingX = bitstream.readBits(1);
+            if (chromaSubsamplingX) {
+              chromaSubsamplingY = bitstream.readBits(1);
             }
           }
-          if (chromaSubsamplingX && chromaSubsamplingY) {
-            chromaSamplePosition = bitstream.readBits(2);
-          }
         }
-        return {
-          profile: seqProfile,
-          level: seqLevel,
-          tier: seqTier,
-          bitDepth,
-          monochrome,
-          chromaSubsamplingX,
-          chromaSubsamplingY,
-          chromaSamplePosition
-        };
+        if (chromaSubsamplingX && chromaSubsamplingY) {
+          chromaSamplePosition = bitstream.readBits(2);
+        }
       }
-      bitstream.skipBits(obuSize * 8);
+      return {
+        profile: seqProfile,
+        level: seqLevel,
+        tier: seqTier,
+        bitDepth,
+        monochrome,
+        chromaSubsamplingX,
+        chromaSubsamplingY,
+        chromaSamplePosition
+      };
     }
     return null;
   };
@@ -2703,6 +2726,105 @@ var Mediabunny = (() => {
     }
     return { modeBlockflags };
   };
+  var determineVideoPacketType = async (videoTrack, packet) => {
+    assert(videoTrack.codec);
+    switch (videoTrack.codec) {
+      case "avc":
+        {
+          const decoderConfig = await videoTrack.getDecoderConfig();
+          assert(decoderConfig);
+          let nalUnits;
+          if (decoderConfig.description) {
+            const bytes2 = toUint8Array(decoderConfig.description);
+            const lengthSizeMinusOne = bytes2[4] & 3;
+            const lengthSize = lengthSizeMinusOne + 1;
+            nalUnits = findNalUnitsInLengthPrefixed(packet.data, lengthSize);
+          } else {
+            nalUnits = findNalUnitsInAnnexB(packet.data);
+          }
+          const isKeyframe = nalUnits.some((x) => extractNalUnitTypeForAvc(x) === 5);
+          return isKeyframe ? "key" : "delta";
+        }
+        ;
+      case "hevc":
+        {
+          const decoderConfig = await videoTrack.getDecoderConfig();
+          assert(decoderConfig);
+          let nalUnits;
+          if (decoderConfig.description) {
+            const bytes2 = toUint8Array(decoderConfig.description);
+            const lengthSizeMinusOne = bytes2[21] & 3;
+            const lengthSize = lengthSizeMinusOne + 1;
+            nalUnits = findNalUnitsInLengthPrefixed(packet.data, lengthSize);
+          } else {
+            nalUnits = findNalUnitsInAnnexB(packet.data);
+          }
+          const isKeyframe = nalUnits.some((x) => {
+            const type = extractNalUnitTypeForHevc(x);
+            return 16 <= type && type <= 23;
+          });
+          return isKeyframe ? "key" : "delta";
+        }
+        ;
+      case "vp8":
+        {
+          const frameType = packet.data[0] & 1;
+          return frameType === 0 ? "key" : "delta";
+        }
+        ;
+      case "vp9":
+        {
+          const bitstream = new Bitstream(packet.data);
+          if (bitstream.readBits(2) !== 2) {
+            return null;
+          }
+          ;
+          const profileLowBit = bitstream.readBits(1);
+          const profileHighBit = bitstream.readBits(1);
+          const profile = (profileHighBit << 1) + profileLowBit;
+          if (profile === 3) {
+            bitstream.skipBits(1);
+          }
+          const showExistingFrame = bitstream.readBits(1);
+          if (showExistingFrame) {
+            return null;
+          }
+          const frameType = bitstream.readBits(1);
+          return frameType === 0 ? "key" : "delta";
+        }
+        ;
+      case "av1":
+        {
+          let reducedStillPictureHeader = false;
+          for (const { type, data } of iterateAv1PacketObus(packet.data)) {
+            if (type === 1) {
+              const bitstream = new Bitstream(data);
+              bitstream.skipBits(4);
+              reducedStillPictureHeader = !!bitstream.readBits(1);
+            } else if (type === 3 || type === 6 || type === 7) {
+              if (reducedStillPictureHeader) {
+                return "key";
+              }
+              const bitstream = new Bitstream(data);
+              const showExistingFrame = bitstream.readBits(1);
+              if (showExistingFrame) {
+                return null;
+              }
+              const frameType = bitstream.readBits(2);
+              return frameType === 0 ? "key" : "delta";
+            }
+          }
+          return null;
+        }
+        ;
+      default:
+        {
+          assertNever(videoTrack.codec);
+          assert(false);
+        }
+        ;
+    }
+  };
 
   // src/isobmff/isobmff-boxes.ts
   var IsobmffBoxWriter = class {
@@ -5970,7 +6092,7 @@ ${cue.notes ?? ""}`;
       if (chunk.type !== "key") return;
       if (!trackData.info.decoderConfig.colorSpace || !trackData.info.decoderConfig.colorSpace.matrix) return;
       const bitstream = new Bitstream(chunk.data);
-      if (bitstream.readBits(2) !== 2) return;
+      bitstream.skipBits(2);
       const profileLowBit = bitstream.readBits(1);
       const profileHighBit = bitstream.readBits(1);
       const profile = (profileHighBit << 1) + profileLowBit;
@@ -7933,12 +8055,34 @@ ${cue.notes ?? ""}`;
     if (options.metadataOnly !== void 0 && typeof options.metadataOnly !== "boolean") {
       throw new TypeError("options.metadataOnly, when defined, must be a boolean.");
     }
+    if (options.verifyKeyPackets !== void 0 && typeof options.verifyKeyPackets !== "boolean") {
+      throw new TypeError("options.verifyKeyPackets, when defined, must be a boolean.");
+    }
+    if (options.verifyKeyPackets && options.metadataOnly) {
+      throw new TypeError("options.verifyKeyPackets and options.metadataOnly cannot be enabled together.");
+    }
   };
   var validateTimestamp = (timestamp) => {
     if (typeof timestamp !== "number" || Number.isNaN(timestamp)) {
       throw new TypeError("timestamp must be a number.");
     }
   };
+  var maybeFixPacketType = (track, promise, options) => {
+    if (options.verifyKeyPackets) {
+      return promise.then(async (packet) => {
+        if (!packet || packet.type === "delta") {
+          return packet;
+        }
+        const determinedType = await track.determinePacketType(packet);
+        if (determinedType) {
+          packet.type = determinedType;
+        }
+        return packet;
+      });
+    } else {
+      return promise;
+    }
+  };
   var EncodedPacketSink = class {
     constructor(track) {
       if (!(track instanceof InputTrack)) {
@@ -7952,7 +8096,7 @@ ${cue.notes ?? ""}`;
      */
     getFirstPacket(options = {}) {
       validatePacketRetrievalOptions(options);
-      return this._track._backing.getFirstPacket(options);
+      return maybeFixPacketType(this._track, this._track._backing.getFirstPacket(options), options);
     }
     /**
      * Retrieves the packet corresponding to the given timestamp, in seconds. More specifically, returns the last packet
@@ -7965,7 +8109,7 @@ ${cue.notes ?? ""}`;
     getPacket(timestamp, options = {}) {
       validateTimestamp(timestamp);
       validatePacketRetrievalOptions(options);
-      return this._track._backing.getPacket(timestamp, options);
+      return maybeFixPacketType(this._track, this._track._backing.getPacket(timestamp, options), options);
     }
     /**
      * Retrieves the packet following the given packet (in decode order), or null if the given packet is the
@@ -7976,7 +8120,7 @@ ${cue.notes ?? ""}`;
         throw new TypeError("packet must be an EncodedPacket.");
       }
       validatePacketRetrievalOptions(options);
-      return this._track._backing.getNextPacket(packet, options);
+      return maybeFixPacketType(this._track, this._track._backing.getNextPacket(packet, options), options);
     }
     /**
      * Retrieves the key packet corresponding to the given timestamp, in seconds. More specifically, returns the last
@@ -7985,23 +8129,49 @@ ${cue.notes ?? ""}`;
      * last key packet using `getKeyPacket(Infinity)`. The method returns null if the timestamp is before the first
      * key packet in the track.
      *
+     * To ensure that the returned packet is guaranteed to be a real key frame, enable `options.verifyKeyPackets`.
+     *
      * @param timestamp - The timestamp used for retrieval, in seconds.
      */
-    getKeyPacket(timestamp, options = {}) {
+    async getKeyPacket(timestamp, options = {}) {
       validateTimestamp(timestamp);
       validatePacketRetrievalOptions(options);
-      return this._track._backing.getKeyPacket(timestamp, options);
+      if (!options.verifyKeyPackets) {
+        return this._track._backing.getKeyPacket(timestamp, options);
+      }
+      const packet = await this._track._backing.getKeyPacket(timestamp, options);
+      if (!packet || packet.type === "delta") {
+        return packet;
+      }
+      const determinedType = await this._track.determinePacketType(packet);
+      if (determinedType === "delta") {
+        return this.getKeyPacket(packet.timestamp - 1 / this._track.timeResolution, options);
+      }
+      return packet;
     }
     /**
      * Retrieves the key packet following the given packet (in decode order), or null if the given packet is the last
      * key packet.
+     *
+     * To ensure that the returned packet is guaranteed to be a real key frame, enable `options.verifyKeyPackets`.
      */
-    getNextKeyPacket(packet, options = {}) {
+    async getNextKeyPacket(packet, options = {}) {
       if (!(packet instanceof EncodedPacket)) {
         throw new TypeError("packet must be an EncodedPacket.");
       }
       validatePacketRetrievalOptions(options);
-      return this._track._backing.getNextKeyPacket(packet, options);
+      if (!options.verifyKeyPackets) {
+        return this._track._backing.getNextKeyPacket(packet, options);
+      }
+      const nextPacket = await this._track._backing.getNextKeyPacket(packet, options);
+      if (!nextPacket || nextPacket.type === "delta") {
+        return nextPacket;
+      }
+      const determinedType = await this._track.determinePacketType(nextPacket);
+      if (determinedType === "delta") {
+        return this.getNextKeyPacket(nextPacket, options);
+      }
+      return nextPacket;
     }
     /**
      * Creates an async iterator that yields the packets in this track in decode order. To enable fast iteration, this
@@ -8147,7 +8317,7 @@ ${cue.notes ?? ""}`;
           }
         });
         const packetSink = this._createPacketSink();
-        const keyPacket = await packetSink.getKeyPacket(startTimestamp) ?? await packetSink.getFirstPacket();
+        const keyPacket = await packetSink.getKeyPacket(startTimestamp, { verifyKeyPackets: true }) ?? await packetSink.getFirstPacket();
         if (!keyPacket) {
           return;
         }
@@ -8155,7 +8325,7 @@ ${cue.notes ?? ""}`;
         let endPacket = void 0;
         if (endTimestamp < Infinity) {
           const packet = await packetSink.getPacket(endTimestamp);
-          const keyPacket2 = !packet ? null : packet.type === "key" && packet.timestamp === endTimestamp ? packet : await packetSink.getNextKeyPacket(packet);
+          const keyPacket2 = !packet ? null : packet.type === "key" && packet.timestamp === endTimestamp ? packet : await packetSink.getNextKeyPacket(packet, { verifyKeyPackets: true });
           if (keyPacket2) {
             endPacket = keyPacket2;
           }
@@ -8307,7 +8477,7 @@ ${cue.notes ?? ""}`;
             break;
           }
           const targetPacket = await packetSink.getPacket(timestamp);
-          const keyPacket = targetPacket && await packetSink.getKeyPacket(timestamp);
+          const keyPacket = targetPacket && await packetSink.getKeyPacket(timestamp, { verifyKeyPackets: true });
           if (!keyPacket) {
             if (maxSequenceNumber !== -1) {
               await decodePackets();
@@ -9158,7 +9328,10 @@ ${cue.notes ?? ""}`;
       const colorSpace = await this._backing.getColorSpace();
       return colorSpace.primaries === "bt2020" || colorSpace.primaries === "smpte432" || colorSpace.transfer === "pg" || colorSpace.transfer === "hlg" || colorSpace.matrix === "bt2020-ncl";
     }
-    /** Returns the decoder configuration for decoding the track's packets using a VideoDecoder. */
+    /**
+     * Returns the decoder configuration for decoding the track's packets using a VideoDecoder. Returns null if the
+     * track's codec is unknown.
+     */
     getDecoderConfig() {
       return this._backing.getDecoderConfig();
     }
@@ -9187,6 +9360,18 @@ ${cue.notes ?? ""}`;
         return false;
       }
     }
+    async determinePacketType(packet) {
+      if (!(packet instanceof EncodedPacket)) {
+        throw new TypeError("packet must be an EncodedPacket.");
+      }
+      if (packet.isMetadataOnly) {
+        throw new TypeError("packet must not be metadata-only to determine its type.");
+      }
+      if (this.codec === null) {
+        return null;
+      }
+      return determineVideoPacketType(this, packet);
+    }
   };
   var InputAudioTrack = class extends InputTrack {
     /** @internal */
@@ -9208,7 +9393,10 @@ ${cue.notes ?? ""}`;
     get sampleRate() {
       return this._backing.getSampleRate();
     }
-    /** Returns the decoder configuration for decoding the track's packets using an AudioDecoder. */
+    /**
+     * Returns the decoder configuration for decoding the track's packets using an AudioDecoder. Returns null if the
+     * track's codec is unknown.
+     */
     getDecoderConfig() {
       return this._backing.getDecoderConfig();
     }
@@ -9241,6 +9429,15 @@ ${cue.notes ?? ""}`;
         return false;
       }
     }
+    async determinePacketType(packet) {
+      if (!(packet instanceof EncodedPacket)) {
+        throw new TypeError("packet must be an EncodedPacket.");
+      }
+      if (this.codec === null) {
+        return null;
+      }
+      return "key";
+    }
   };
 
   // src/reader.ts
@@ -9411,6 +9608,18 @@ ${cue.notes ?? ""}`;
       this.pos += 4;
       return view2.getUint32(offset, this.littleEndian);
     }
+    readU64() {
+      let low;
+      let high;
+      if (this.littleEndian) {
+        low = this.readU32();
+        high = this.readU32();
+      } else {
+        high = this.readU32();
+        low = this.readU32();
+      }
+      return high * 4294967296 + low;
+    }
     readAscii(length) {
       const { view: view2, offset } = this.reader.getViewAndOffset(this.pos, this.pos + length);
       this.pos += length;
@@ -9438,25 +9647,38 @@ ${cue.notes ?? ""}`;
       return this.metadataPromise ??= (async () => {
         const actualFileSize = await this.metadataReader.reader.source.getSize();
         const riffType = this.metadataReader.readAscii(4);
-        this.metadataReader.littleEndian = riffType === "RIFF";
-        const totalFileSize = Math.min(this.metadataReader.readU32() + 8, actualFileSize);
+        this.metadataReader.littleEndian = riffType !== "RIFX";
+        const isRf64 = riffType === "RF64";
+        const outerChunkSize = this.metadataReader.readU32();
+        let totalFileSize = isRf64 ? actualFileSize : Math.min(outerChunkSize + 8, actualFileSize);
         const format = this.metadataReader.readAscii(4);
         if (format !== "WAVE") {
           throw new Error("Invalid WAVE file - wrong format");
         }
         this.metadataReader.pos = 12;
+        let chunksRead = 0;
+        let dataChunkSize = null;
         while (this.metadataReader.pos < totalFileSize) {
           await this.metadataReader.reader.loadRange(this.metadataReader.pos, this.metadataReader.pos + 8);
           const chunkId = this.metadataReader.readAscii(4);
           const chunkSize = this.metadataReader.readU32();
           const startPos = this.metadataReader.pos;
+          if (isRf64 && chunksRead === 0 && chunkId !== "ds64") {
+            throw new Error('Invalid RF64 file: First chunk must be "ds64".');
+          }
           if (chunkId === "fmt ") {
             await this.parseFmtChunk(chunkSize);
           } else if (chunkId === "data") {
+            dataChunkSize ??= chunkSize;
             this.dataStart = this.metadataReader.pos;
-            this.dataSize = Math.min(chunkSize, totalFileSize - this.dataStart);
+            this.dataSize = Math.min(dataChunkSize, totalFileSize - this.dataStart);
+          } else if (chunkId === "ds64") {
+            const riffChunkSize = this.metadataReader.readU64();
+            dataChunkSize = this.metadataReader.readU64();
+            totalFileSize = Math.min(riffChunkSize + 8, actualFileSize);
           }
           this.metadataReader.pos = startPos + chunkSize + (chunkSize & 1);
+          chunksRead++;
         }
         if (!this.audioInfo) {
           throw new Error('Invalid WAVE file - missing "fmt " chunk');
@@ -9651,13 +9873,18 @@ ${cue.notes ?? ""}`;
       this.helper = new Uint8Array(8);
       this.helperView = new DataView(this.helper.buffer);
     }
+    writeU16(value) {
+      this.helperView.setUint16(0, value, true);
+      this.writer.write(this.helper.subarray(0, 2));
+    }
     writeU32(value) {
       this.helperView.setUint32(0, value, true);
       this.writer.write(this.helper.subarray(0, 4));
     }
-    writeU16(value) {
-      this.helperView.setUint16(0, value, true);
-      this.writer.write(this.helper.subarray(0, 2));
+    writeU64(value) {
+      this.helperView.setUint32(0, value, true);
+      this.helperView.setUint32(4, Math.floor(value / 2 ** 32), true);
+      this.writer.write(this.helper);
     }
     writeAscii(text) {
       this.writer.write(new TextEncoder().encode(text));
@@ -9670,9 +9897,12 @@ ${cue.notes ?? ""}`;
       super(output);
       this.headerWritten = false;
       this.dataSize = 0;
+      this.sampleRate = null;
+      this.sampleCount = 0;
       this.format = format;
       this.writer = output._writer;
       this.riffWriter = new RiffWriter(output._writer);
+      this.isRf64 = !!format._options.large;
     }
     async start() {
     }
@@ -9690,11 +9920,18 @@ ${cue.notes ?? ""}`;
           assert(meta);
           assert(meta.decoderConfig);
           this.writeHeader(track, meta.decoderConfig);
+          this.sampleRate = meta.decoderConfig.sampleRate;
           this.headerWritten = true;
         }
         this.validateAndNormalizeTimestamp(track, packet.timestamp, packet.type === "key");
+        if (!this.isRf64 && this.writer.getPos() + packet.data.byteLength >= 2 ** 32) {
+          throw new Error(
+            "Adding more audio data would exceed the maximum RIFF size of 4 GiB. To write larger files, use RF64 by setting `large: true` in the WavOutputFormatOptions."
+          );
+        }
         this.writer.write(packet.data);
         this.dataSize += packet.data.byteLength;
+        this.sampleCount += Math.round(packet.duration * this.sampleRate);
         await this.writer.flush();
       } finally {
         release();
@@ -9722,9 +9959,21 @@ ${cue.notes ?? ""}`;
       const channels = config.numberOfChannels;
       const sampleRate = config.sampleRate;
       const blockSize = pcmInfo.sampleSize * channels;
-      this.riffWriter.writeAscii("RIFF");
-      this.riffWriter.writeU32(0);
+      this.riffWriter.writeAscii(this.isRf64 ? "RF64" : "RIFF");
+      if (this.isRf64) {
+        this.riffWriter.writeU32(4294967295);
+      } else {
+        this.riffWriter.writeU32(0);
+      }
       this.riffWriter.writeAscii("WAVE");
+      if (this.isRf64) {
+        this.riffWriter.writeAscii("ds64");
+        this.riffWriter.writeU32(28);
+        this.riffWriter.writeU64(0);
+        this.riffWriter.writeU64(0);
+        this.riffWriter.writeU64(0);
+        this.riffWriter.writeU32(0);
+      }
       this.riffWriter.writeAscii("fmt ");
       this.riffWriter.writeU32(16);
       this.riffWriter.writeU16(format);
@@ -9734,7 +9983,11 @@ ${cue.notes ?? ""}`;
       this.riffWriter.writeU16(blockSize);
       this.riffWriter.writeU16(8 * pcmInfo.sampleSize);
       this.riffWriter.writeAscii("data");
-      this.riffWriter.writeU32(0);
+      if (this.isRf64) {
+        this.riffWriter.writeU32(4294967295);
+      } else {
+        this.riffWriter.writeU32(0);
+      }
       if (this.format._options.onHeader) {
         const { data, start } = this.writer.stopTrackingWrites();
         this.format._options.onHeader(data, start);
@@ -9743,10 +9996,19 @@ ${cue.notes ?? ""}`;
     async finalize() {
       const release = await this.mutex.acquire();
       const endPos = this.writer.getPos();
-      this.writer.seek(4);
-      this.riffWriter.writeU32(this.dataSize + 36);
-      this.writer.seek(40);
-      this.riffWriter.writeU32(this.dataSize);
+      if (this.isRf64) {
+        this.writer.seek(20);
+        this.riffWriter.writeU64(endPos - 8);
+        this.writer.seek(28);
+        this.riffWriter.writeU64(this.dataSize);
+        this.writer.seek(36);
+        this.riffWriter.writeU64(this.sampleCount);
+      } else {
+        this.writer.seek(4);
+        this.riffWriter.writeU32(endPos - 8);
+        this.writer.seek(40);
+        this.riffWriter.writeU32(this.dataSize);
+      }
       this.writer.seek(endPos);
       release();
     }
@@ -10005,6 +10267,9 @@ ${cue.notes ?? ""}`;
       if (!options || typeof options !== "object") {
         throw new TypeError("options must be an object.");
       }
+      if (options.large !== void 0 && typeof options.large !== "boolean") {
+        throw new TypeError("options.large, when provided, must be a boolean.");
+      }
       if (options.onHeader !== void 0 && typeof options.onHeader !== "function") {
         throw new TypeError("options.onHeader, when provided, must be a function.");
       }
@@ -15973,7 +16238,7 @@ ${cue.notes ?? ""}`;
       }
       const riffReader = new RiffReader(input._mainReader);
       const riffType = riffReader.readAscii(4);
-      if (riffType !== "RIFF" && riffType !== "RIFX") {
+      if (riffType !== "RIFF" && riffType !== "RIFX" && riffType !== "RF64") {
         return false;
       }
       riffReader.pos = 8;
@@ -16380,7 +16645,7 @@ ${cue.notes ?? ""}`;
           const decoderConfig = await track.getDecoderConfig();
           const meta = { decoderConfig: decoderConfig ?? void 0 };
           const endPacket = Number.isFinite(this._endTimestamp) ? await sink.getPacket(this._endTimestamp, { metadataOnly: true }) ?? void 0 : void 0;
-          for await (const packet of sink.packets(void 0, endPacket)) {
+          for await (const packet of sink.packets(void 0, endPacket, { verifyKeyPackets: true })) {
             if (this._synchronizer.shouldWait(track.id, packet.timestamp)) {
               await this._synchronizer.wait(packet.timestamp);
             }