shifro 1.1.5 → 1.2.1

package/README.md

@@ -16,7 +16,7 @@ Run `npm install -g shifro` to install the command-line tool globally.
 shifro --key eb676abbcb345e96bbcf616630f1a3da:100b6c20940f779a4589152b57d2dacb ./input.mp4 ./output.mp4
 ```
 
->You can also use `npx shifro ...` to run the CLI tool without installing it globally
+> You can also use `npx shifro ...` to run the CLI tool without installing it globally
 
 This CLI can be used as an alternative to the [mp4decrypt](https://www.bento4.com/documentation/mp4decrypt/) or [shaka-packager](https://shaka-project.github.io/shaka-packager/html/documentation.html#raw-key-encryption-options).
 
@@ -38,7 +38,7 @@ async function decrypt() {
         ['4d97930a3d7b55fa81d0028653f5e499', '429ec76475e7a952d224d8ef867f12b6'],
         ['d21373c0b8ab5ba9954742bcdfb5f48b', '150a6c7d7dee6a91b74dccfce5b31928'],
       ]),
-      // Optinally, you can use this callback to handle encryption information (like key ID and PSSH boxes)
+      // Optionally, you can use this callback to handle encryption information (like key ID and PSSH boxes)
       handleEncryptionInfo: ({ keyId, psshBoxes }) => {
         console.group(`Key ID: ${keyId}`);
         for (const psshBox of psshBoxes) {
@@ -57,6 +57,38 @@ async function decrypt() {
 }
 ```
 
+#### Decrypting file with an external AES backend
+
+```ts
+import {
+  Decryption,
+  FilePathSource,
+  FilePathTarget,
+  Input,
+  Output,
+  decryptBytes,
+  type EncryptedBytes,
+} from 'shifro';
+
+// Decrypt bytes with your DRM library
+async function decryptProtectedData({ scheme, data, iv }: EncryptedBytes) {
+  // Your decryption logic here
+}
+
+async function runDecryption() {
+  const decryption = await Decryption.init({
+    input: new Input({
+      source: new FilePathSource('./input.mp4'),
+      // `decryptBytes` - helper function that allows to handle only the encrypted bytes. Clear sample bytes are not included.
+      decryptSample: decryptBytes(decryptProtectedData),
+    }),
+    output: new Output({ target: new FilePathTarget('./output.mp4') }),
+  });
+
+  await decryption.execute();
+}
+```
+
 #### Decrypting file using browser's Web Streams API
 
 ```ts

package/dist/cli.mjs

@@ -1,27 +1,344 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { ALL_FORMATS, Conversion, FilePathSource, FilePathTarget, Input, Mp4OutputFormat, Output } from "mediabunny";
+import { ALL_FORMATS, Conversion, EncodedPacket, FilePathSource, FilePathTarget, Input, Mp4OutputFormat, Output } from "mediabunny";
 //#region package.json
 var name = "shifro";
-var version = "1.1.5";
+var version = "1.2.1";
 var author = "Vitaly Gashkov <vitalygashkov@vk.com>";
 //#endregion
+//#region src/mediabunny-isobmff.ts
+const binarySearchLessOrEqual = (items, needle, getValue) => {
+	let low = 0;
+	let high = items.length - 1;
+	let result = -1;
+	while (low <= high) {
+		const middle = low + Math.floor((high - low) / 2);
+		if (getValue(items[middle]) <= needle) {
+			result = middle;
+			low = middle + 1;
+		} else high = middle - 1;
+	}
+	return result;
+};
+const binarySearchExact = (items, needle, getValue) => {
+	let low = 0;
+	let high = items.length - 1;
+	while (low <= high) {
+		const middle = low + Math.floor((high - low) / 2);
+		const value = getValue(items[middle]);
+		if (value === needle) return middle;
+		if (value < needle) low = middle + 1;
+		else high = middle - 1;
+	}
+	return -1;
+};
+const readBytes = (slice, length) => {
+	const bytes = slice.bytes.slice(slice.bufferPos, slice.bufferPos + length);
+	slice.bufferPos += length;
+	return bytes;
+};
+const readU16Be = (slice) => {
+	const value = slice.view.getUint16(slice.bufferPos, false);
+	slice.bufferPos += 2;
+	return value;
+};
+const readU32Be = (slice) => {
+	const value = slice.view.getUint32(slice.bufferPos, false);
+	slice.bufferPos += 4;
+	return value;
+};
+const readSampleBytes = async (internalTrack, byteOffset, byteLength) => {
+	let slice = internalTrack.demuxer.reader.requestSlice(byteOffset, byteLength);
+	if (slice instanceof Promise) slice = await slice;
+	if (!slice) throw new Error("Failed to read encrypted sample bytes.");
+	return readBytes(slice, byteLength);
+};
+const resolveEncryptionAuxInfo = async (internalTrack, auxInfo) => {
+	if (auxInfo.resolved) return auxInfo.resolved;
+	const encryptionInfo = internalTrack.encryptionInfo;
+	if (!encryptionInfo || encryptionInfo.defaultPerSampleIvSize === null) throw new Error("Missing track encryption info.");
+	if (auxInfo.offset === null || auxInfo.sampleCount === 0) throw new Error("Incomplete saiz/saio info; cannot resolve encryption data.");
+	if (auxInfo.defaultSampleInfoSize === 0 && !auxInfo.sampleSizes) throw new Error("Invalid auxiliary encryption info: auxInfo.sampleSizes is required when auxInfo.defaultSampleInfoSize is 0.");
+	let totalSize = 0;
+	if (auxInfo.defaultSampleInfoSize > 0) totalSize = auxInfo.defaultSampleInfoSize * auxInfo.sampleCount;
+	else if (auxInfo.sampleSizes) for (const size of auxInfo.sampleSizes) totalSize += size;
+	let slice = internalTrack.demuxer.reader.requestSlice(auxInfo.offset, totalSize);
+	if (slice instanceof Promise) slice = await slice;
+	if (!slice) throw new Error("Failed to read auxiliary encryption info.");
+	const entries = [];
+	const ivSize = encryptionInfo.defaultPerSampleIvSize;
+	for (let i = 0; i < auxInfo.sampleCount; i++) {
+		const entrySize = auxInfo.defaultSampleInfoSize > 0 ? auxInfo.defaultSampleInfoSize : auxInfo.sampleSizes?.[i] ?? 0;
+		const iv = new Uint8Array(16);
+		if (ivSize > 0) iv.set(readBytes(slice, ivSize), 0);
+		else if (encryptionInfo.defaultConstantIv) iv.set(encryptionInfo.defaultConstantIv, 0);
+		let subsamples = null;
+		if (entrySize > ivSize) {
+			const subsampleCount = readU16Be(slice);
+			subsamples = [];
+			for (let j = 0; j < subsampleCount; j++) subsamples.push({
+				clearLen: readU16Be(slice),
+				protectedLen: readU32Be(slice)
+			});
+		}
+		entries.push({
+			iv,
+			subsamples
+		});
+	}
+	auxInfo.resolved = entries;
+	return entries;
+};
+const getSampleInfo = (sampleTable, sampleIndex) => {
+	const timingEntryIndex = binarySearchLessOrEqual(sampleTable.sampleTimingEntries, sampleIndex, (entry) => entry.startIndex);
+	const timingEntry = sampleTable.sampleTimingEntries[timingEntryIndex];
+	if (!timingEntry || timingEntry.startIndex + timingEntry.count <= sampleIndex) return null;
+	let presentationTimestamp = timingEntry.startDecodeTimestamp + (sampleIndex - timingEntry.startIndex) * timingEntry.delta;
+	const offsetEntryIndex = binarySearchLessOrEqual(sampleTable.sampleCompositionTimeOffsets, sampleIndex, (entry) => entry.startIndex);
+	const offsetEntry = sampleTable.sampleCompositionTimeOffsets[offsetEntryIndex];
+	if (offsetEntry && sampleIndex - offsetEntry.startIndex < offsetEntry.count) presentationTimestamp += offsetEntry.offset;
+	const sampleSize = sampleTable.sampleSizes[Math.min(sampleIndex, sampleTable.sampleSizes.length - 1)];
+	if (sampleSize === void 0) return null;
+	const chunkEntryIndex = binarySearchLessOrEqual(sampleTable.sampleToChunk, sampleIndex, (entry) => entry.startSampleIndex);
+	const chunkEntry = sampleTable.sampleToChunk[chunkEntryIndex];
+	if (!chunkEntry) return null;
+	const chunkIndex = chunkEntry.startChunkIndex + Math.floor((sampleIndex - chunkEntry.startSampleIndex) / chunkEntry.samplesPerChunk);
+	const chunkOffset = sampleTable.chunkOffsets[chunkIndex];
+	if (chunkOffset === void 0) return null;
+	const startSampleIndexOfChunk = chunkEntry.startSampleIndex + (chunkIndex - chunkEntry.startChunkIndex) * chunkEntry.samplesPerChunk;
+	let chunkSize = 0;
+	let sampleOffset = chunkOffset;
+	if (sampleTable.sampleSizes.length === 1) {
+		sampleOffset += sampleSize * (sampleIndex - startSampleIndexOfChunk);
+		chunkSize += sampleSize * chunkEntry.samplesPerChunk;
+	} else for (let i = startSampleIndexOfChunk; i < startSampleIndexOfChunk + chunkEntry.samplesPerChunk; i++) {
+		const currentSampleSize = sampleTable.sampleSizes[i];
+		if (currentSampleSize === void 0) return null;
+		if (i < sampleIndex) sampleOffset += currentSampleSize;
+		chunkSize += currentSampleSize;
+	}
+	let duration = timingEntry.delta;
+	if (sampleTable.presentationTimestamps && sampleTable.presentationTimestampIndexMap) {
+		const presentationIndex = sampleTable.presentationTimestampIndexMap[sampleIndex];
+		if (presentationIndex !== void 0 && presentationIndex < sampleTable.presentationTimestamps.length - 1) {
+			const nextEntry = sampleTable.presentationTimestamps[presentationIndex + 1];
+			if (nextEntry) duration = nextEntry.presentationTimestamp - presentationTimestamp;
+		}
+	}
+	const isKeyFrame = sampleTable.keySampleIndices ? binarySearchExact(sampleTable.keySampleIndices, sampleIndex, (value) => value) !== -1 : true;
+	return {
+		presentationTimestamp,
+		duration,
+		sampleOffset,
+		sampleSize,
+		chunkOffset,
+		chunkSize,
+		isKeyFrame
+	};
+};
+const psshBoxesAreEqual = (left, right) => {
+	if (left.systemId !== right.systemId) return false;
+	if (left.data.byteLength !== right.data.byteLength) return false;
+	for (let i = 0; i < left.data.byteLength; i++) if (left.data[i] !== right.data[i]) return false;
+	return true;
+};
+const cloneSubsamples = (subsamples) => {
+	if (!subsamples) return null;
+	return subsamples.map((subsample) => ({
+		clearLen: subsample.clearLen,
+		protectedLen: subsample.protectedLen
+	}));
+};
+const getPattern = (encryptionInfo) => {
+	const cryptByteBlock = encryptionInfo.defaultCryptByteBlock ?? 0;
+	const skipByteBlock = encryptionInfo.defaultSkipByteBlock ?? 0;
+	if (cryptByteBlock === 0 && skipByteBlock === 0) return null;
+	return {
+		cryptByteBlock,
+		skipByteBlock
+	};
+};
+const isUint8Array = (value) => value instanceof Uint8Array;
+const isIsobmffTrackBacking = (backing) => {
+	if (!backing || typeof backing !== "object") return false;
+	const maybeBacking = backing;
+	const internalTrack = maybeBacking.internalTrack;
+	return Boolean(internalTrack && internalTrack.demuxer && typeof internalTrack.demuxer.getSampleTableForTrack === "function" && maybeBacking.packetToSampleIndex instanceof WeakMap && maybeBacking.packetToFragmentLocation instanceof WeakMap);
+};
+const getTrackEncryptionInfo = (backing) => backing.internalTrack.encryptionInfo;
+const getKeyId = (backing) => backing.internalTrack.encryptionInfo?.defaultKid ?? null;
+const getEncryptedSample = async (backing, packet) => {
+	const internalTrack = backing.internalTrack;
+	const fragmentLocation = backing.packetToFragmentLocation.get(packet);
+	if (fragmentLocation) {
+		const fragment = fragmentLocation.fragment;
+		const sample = fragment.trackData.get(internalTrack.id)?.samples[fragmentLocation.sampleIndex];
+		if (!sample?.encryption) return null;
+		return {
+			data: await readSampleBytes(internalTrack, sample.byteOffset, sample.byteSize),
+			sampleEncryption: sample.encryption,
+			fragment
+		};
+	}
+	const sampleIndex = backing.packetToSampleIndex.get(packet);
+	if (sampleIndex === void 0) return null;
+	const sampleInfo = getSampleInfo(internalTrack.demuxer.getSampleTableForTrack(internalTrack), sampleIndex);
+	if (!sampleInfo) return null;
+	const auxInfo = internalTrack.encryptionAuxInfo;
+	if (!auxInfo) return null;
+	const sampleEncryption = (await resolveEncryptionAuxInfo(internalTrack, auxInfo))[sampleIndex];
+	if (!sampleEncryption) return null;
+	return {
+		data: await readSampleBytes(internalTrack, sampleInfo.sampleOffset, sampleInfo.sampleSize),
+		sampleEncryption,
+		fragment: null
+	};
+};
+const getPsshBoxes = (backing, keyId, fragment) => {
+	const { psshBoxes } = backing.internalTrack.demuxer;
+	if (!fragment) return psshBoxes;
+	const boxes = [...psshBoxes, ...fragment.psshBoxes].filter((psshBox) => psshBox.keyIds === null || psshBox.keyIds.includes(keyId));
+	for (let i = 0; i < boxes.length - 1; i++) for (let j = i + 1; j < boxes.length; j++) if (psshBoxesAreEqual(boxes[i], boxes[j])) {
+		boxes.splice(j, 1);
+		j--;
+	}
+	return boxes;
+};
+//#endregion
+//#region src/isobmff-decrypt-sample-patcher.ts
+const createMetadataOnlyOptions = (options) => ({
+	...options,
+	metadataOnly: true,
+	verifyKeyPackets: false
+});
+var IsobmffDecryptSamplePatcher = class {
+	input;
+	decryptSample;
+	reportEncryptionInfo;
+	patchableTrackBackings = /* @__PURE__ */ new WeakSet();
+	patchTrackBackingsPromise = null;
+	constructor(input, decryptSample, reportEncryptionInfo) {
+		this.input = input;
+		this.decryptSample = decryptSample;
+		this.reportEncryptionInfo = reportEncryptionInfo;
+	}
+	async ensurePatched() {
+		this.patchTrackBackingsPromise ??= (async () => {
+			const tracks = await this.input.getTracks();
+			for (const track of tracks) {
+				const backing = track._backing;
+				if (!isIsobmffTrackBacking(backing) || this.patchableTrackBackings.has(backing)) continue;
+				this.patchableTrackBackings.add(backing);
+				this.patchTrackBacking(backing);
+			}
+		})();
+		await this.patchTrackBackingsPromise;
+	}
+	patchTrackBacking(backing) {
+		const packetToMetadataPacket = /* @__PURE__ */ new WeakMap();
+		const getOriginalPacket = (packet) => packetToMetadataPacket.get(packet) ?? packet;
+		const getFirstPacket = backing.getFirstPacket.bind(backing);
+		backing.getFirstPacket = async (options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getFirstPacket(options);
+			const metadataPacket = await getFirstPacket(createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getFirstPacket(options), packetToMetadataPacket);
+		};
+		const getPacket = backing.getPacket.bind(backing);
+		backing.getPacket = async (timestamp, options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getPacket(timestamp, options);
+			const metadataPacket = await getPacket(timestamp, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getPacket(timestamp, options), packetToMetadataPacket);
+		};
+		const getNextPacket = backing.getNextPacket.bind(backing);
+		backing.getNextPacket = async (packet, options) => {
+			const originalPacket = getOriginalPacket(packet);
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getNextPacket(originalPacket, options);
+			const metadataPacket = await getNextPacket(originalPacket, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getNextPacket(originalPacket, options), packetToMetadataPacket);
+		};
+		const getKeyPacket = backing.getKeyPacket.bind(backing);
+		backing.getKeyPacket = async (timestamp, options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getKeyPacket(timestamp, options);
+			const metadataPacket = await getKeyPacket(timestamp, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getKeyPacket(timestamp, options), packetToMetadataPacket);
+		};
+		const getNextKeyPacket = backing.getNextKeyPacket.bind(backing);
+		backing.getNextKeyPacket = async (packet, options) => {
+			const originalPacket = getOriginalPacket(packet);
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getNextKeyPacket(originalPacket, options);
+			const metadataPacket = await getNextKeyPacket(originalPacket, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getNextKeyPacket(originalPacket, options), packetToMetadataPacket);
+		};
+	}
+	shouldUseCustomDecryptSample(backing, options) {
+		return Boolean(!options.metadataOnly && getTrackEncryptionInfo(backing)?.defaultIsProtected !== false);
+	}
+	async materializePacket(backing, metadataPacket, fallback, packetToMetadataPacket) {
+		if (!metadataPacket) return null;
+		const decryptedPacket = await this.decryptPacket(backing, metadataPacket, fallback);
+		if (decryptedPacket && decryptedPacket !== metadataPacket) packetToMetadataPacket.set(decryptedPacket, metadataPacket);
+		return decryptedPacket;
+	}
+	async decryptPacket(backing, metadataPacket, fallback) {
+		const encryptionInfo = getTrackEncryptionInfo(backing);
+		if (!encryptionInfo?.defaultIsProtected) return fallback();
+		const keyId = getKeyId(backing);
+		if (!keyId) throw new Error("Encrypted sample encountered without a key ID.");
+		const encryptedSample = await getEncryptedSample(backing, metadataPacket);
+		if (!encryptedSample) return fallback();
+		const psshBoxes = getPsshBoxes(backing, keyId, encryptedSample.fragment);
+		this.reportEncryptionInfo(keyId, psshBoxes);
+		const decryptedData = await this.decryptSample({
+			data: encryptedSample.data,
+			keyId,
+			psshBoxes,
+			scheme: encryptionInfo.scheme,
+			iv: encryptedSample.sampleEncryption.iv.slice(),
+			timestamp: metadataPacket.microsecondTimestamp,
+			subsamples: cloneSubsamples(encryptedSample.sampleEncryption.subsamples),
+			pattern: getPattern(encryptionInfo)
+		});
+		if (!isUint8Array(decryptedData)) throw new TypeError("decryption callback must return a Uint8Array.");
+		if (decryptedData.byteLength !== metadataPacket.byteLength) throw new Error("decryption callback must return the same number of bytes as the encrypted sample.");
+		return new EncodedPacket(decryptedData, metadataPacket.type, metadataPacket.timestamp, metadataPacket.duration, metadataPacket.sequenceNumber, metadataPacket.byteLength, metadataPacket.sideData);
+	}
+};
+//#endregion
 //#region src/index.ts
+const createEncryptionReporter = (handleEncryptionInfo) => {
+	const reportedEncryptionInfo = /* @__PURE__ */ new Set();
+	return (keyId, psshBoxes) => {
+		if (!handleEncryptionInfo || reportedEncryptionInfo.has(keyId)) return;
+		reportedEncryptionInfo.add(keyId);
+		handleEncryptionInfo({
+			keyId,
+			psshBoxes
+		});
+	};
+};
 var Input$1 = class extends Input {
-	constructor({ keys, handleEncryptionInfo, ...options }) {
+	decryptSamplePatcher;
+	constructor({ keys, decryptSample, handleEncryptionInfo, ...options }) {
+		if (!keys?.size && !decryptSample) throw new Error("Either keys or decryptSample must be provided.");
+		const reportEncryptionInfo = createEncryptionReporter(handleEncryptionInfo);
 		super({
 			...options,
 			formats: ALL_FORMATS,
 			formatOptions: { isobmff: { resolveKeyId: ({ keyId, psshBoxes }) => {
-				handleEncryptionInfo?.({
-					keyId,
-					psshBoxes
-				});
-				const key = keys.get(keyId);
+				reportEncryptionInfo(keyId, psshBoxes);
+				const key = keys?.get(keyId);
 				if (!key) throw new Error("Unknown key ID.");
 				return key;
 			} } }
 		});
+		this.decryptSamplePatcher = decryptSample ? new IsobmffDecryptSamplePatcher({ getTracks: (query) => this.getTracksWithoutPatching(query) }, decryptSample, reportEncryptionInfo) : null;
+	}
+	async getTracks(query) {
+		await this.decryptSamplePatcher?.ensurePatched();
+		return super.getTracks(query);
+	}
+	async getTracksWithoutPatching(query) {
+		return super.getTracks(query);
 	}
 };
 var Output$1 = class extends Output {

package/dist/index.d.mts

@@ -1,21 +1,97 @@
-import { Conversion, FilePathSource, FilePathTarget, Input as Input$1, InputOptions, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output as Output$1, OutputFormat, OutputOptions, PsshBox, ReadableStreamSource, StreamSource, StreamSourceOptions, StreamTarget, StreamTargetOptions, UrlSource } from "mediabunny";
+import { Conversion, FilePathSource, FilePathTarget, Input as Input$1, InputOptions as MediabunnyInputOptions, InputTrack, InputTrackQuery, MaybePromise, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output as Output$1, OutputFormat, OutputOptions, PsshBox, ReadableStreamSource, StreamSource, StreamSourceOptions, StreamTarget, StreamTargetOptions, UrlSource } from "mediabunny";
 
-//#region src/index.d.ts
+//#region src/decrypt-sample.d.ts
 type KeyId = string;
 type Key = string;
 type KeyMap = Map<KeyId, Key>;
+type EncryptionScheme = 'cenc' | 'cens' | 'cbcs';
+type SubsampleEncryption = {
+  /** Number of clear bytes that appear before the protected bytes in this subsample. */clearLen: number; /** Number of encrypted bytes in this subsample. */
+  protectedLen: number;
+};
+type EncryptionPattern = {
+  /** Number of consecutive 16-byte blocks that are encrypted in each pattern step. */cryptByteBlock: number; /** Number of consecutive 16-byte blocks that are skipped in each pattern step. */
+  skipByteBlock: number;
+};
+/**
+ * Options passed to {@link DecryptSample}.
+ *
+ * This is the advanced callback contract. `data` contains the full sample bytes exactly as they appear in the
+ * container, including any clear regions. `subsamples` and `pattern` describe which parts of `data` are protected.
+ *
+ * Use this callback when the decryption backend needs the original sample layout, or when working with content
+ * that cannot be safely represented as a single flattened protected-byte stream, such as patterned `cbcs`
+ * subsample encryption.
+ */
+type EncryptedSample = {
+  /** Full sample bytes as stored in the container. Clear and protected regions are both present in this buffer. */data: Uint8Array; /** Key ID from the track encryption metadata. */
+  keyId: string; /** PSSH boxes associated with this key/sample and useful for DRM-specific key resolution. */
+  psshBoxes: PsshBox[]; /** Sample encryption scheme. */
+  scheme: EncryptionScheme; /** Per-sample IV resolved from container metadata. */
+  iv: Uint8Array; /** Presentation timestamp of the sample in microseconds. */
+  timestamp: number; /** Subsample layout describing which parts of `data` are clear vs protected, or `null` for whole-sample encryption. */
+  subsamples: SubsampleEncryption[] | null; /** Pattern encryption parameters, or `null` when no pattern is used. */
+  pattern: EncryptionPattern | null;
+};
+/** Options passed to {@link decryptBytes}. */
+type EncryptedBytes = Omit<EncryptedSample, 'data'> & {
+  /** Only the encrypted bytes that should be decrypted. Clear sample bytes are not included. */data: Uint8Array;
+};
+/**
+ * Advanced sample decryption callback.
+ *
+ * The callback receives the full encrypted sample layout and must return the fully decrypted sample bytes with the
+ * exact same length. This is the most general integration point and should be used when a backend needs explicit
+ * subsample and pattern metadata.
+ */
+type DecryptSample = (options: EncryptedSample) => MaybePromise<Uint8Array>;
+/** Raw byte decryption callback used by {@link decryptBytes}. */
+type DecryptBytesCallback = (options: EncryptedBytes) => MaybePromise<Uint8Array>;
+declare const decryptBytes: (decryptBytesCallback: DecryptBytesCallback) => DecryptSample;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Options for creating a `shifro` {@link Input}.
+ *
+ * In addition to the regular Mediabunny input options, `shifro` accepts either raw content keys or one of the
+ * decryption callbacks used to delegate decryption to another library.
+ */
+type ShifroInputOptions = Omit<MediabunnyInputOptions, 'formats' | 'formatOptions'> & {
+  /**
+   * Content decryption keys indexed by key ID.
+   *
+   * Use this when the caller already has the actual content keys and wants `shifro`/Mediabunny to perform the
+   * sample decryption internally.
+   */
+  keys?: KeyMap;
+  /**
+   * Advanced decryption callback that receives the full encrypted sample layout.
+   *
+   * Use this when the decryption backend needs explicit access to the sample's clear/protected layout, subsample
+   * metadata, or pattern encryption information.
+   */
+  decryptSample?: DecryptSample;
+  /**
+   * Optional callback invoked when encryption metadata is discovered for a sample.
+   *
+   * This is useful when the caller wants access to the key ID and PSSH boxes without providing the key directly,
+   * for example to perform external DRM license handling.
+   */
+  handleEncryptionInfo?: (options: {
+    keyId: string;
+    psshBoxes: PsshBox[];
+  }) => void;
+};
 declare class Input extends Input$1 {
+  private readonly decryptSamplePatcher;
   constructor({
     keys,
+    decryptSample,
     handleEncryptionInfo,
     ...options
-  }: Omit<InputOptions, 'formats' | 'formatOptions'> & {
-    keys: KeyMap;
-    handleEncryptionInfo?: (options: {
-      keyId: string;
-      psshBoxes: PsshBox[];
-    }) => void;
-  });
+  }: ShifroInputOptions);
+  getTracks(query?: InputTrackQuery<InputTrack>): Promise<InputTrack[]>;
+  private getTracksWithoutPatching;
 }
 declare class Output extends Output$1 {
   constructor({
@@ -25,4 +101,4 @@ declare class Output extends Output$1 {
   });
 }
 //#endregion
-export { Conversion as Decryption, FilePathSource, FilePathTarget, Input, type InputOptions, type Key, type KeyId, type KeyMap, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output, type OutputFormat, type OutputOptions, ReadableStreamSource, StreamSource, type StreamSourceOptions, StreamTarget, type StreamTargetOptions, UrlSource };
+export { type DecryptBytesCallback, type DecryptSample, Conversion as Decryption, type EncryptedBytes, type EncryptedSample, type EncryptionPattern, FilePathSource, FilePathTarget, Input, type MediabunnyInputOptions as InputOptions, type Key, type KeyId, type KeyMap, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output, type OutputFormat, type OutputOptions, ReadableStreamSource, ShifroInputOptions, StreamSource, type StreamSourceOptions, StreamTarget, type StreamTargetOptions, type SubsampleEncryption, UrlSource, decryptBytes };

package/dist/index.mjs

@@ -1,20 +1,464 @@
-import { ALL_FORMATS, Conversion, FilePathSource, FilePathTarget, Input as Input$1, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output as Output$1, ReadableStreamSource, StreamSource, StreamTarget, UrlSource } from "mediabunny";
+import { ALL_FORMATS, Conversion, EncodedPacket, FilePathSource, FilePathTarget, Input as Input$1, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output as Output$1, ReadableStreamSource, StreamSource, StreamTarget, UrlSource } from "mediabunny";
+//#region src/decrypt-sample.ts
+const AES_BLOCK_SIZE = 16;
+const isUint8Array$1 = (value) => value instanceof Uint8Array;
+const cloneSubsamples$1 = (subsamples) => {
+	if (!subsamples) return null;
+	return subsamples.map((subsample) => ({
+		clearLen: subsample.clearLen,
+		protectedLen: subsample.protectedLen
+	}));
+};
+const clonePattern = (pattern) => {
+	if (!pattern) return null;
+	return {
+		cryptByteBlock: pattern.cryptByteBlock,
+		skipByteBlock: pattern.skipByteBlock
+	};
+};
+const collectProtectedRanges = (offset, protectedLen, pattern, fullBlocksOnly) => {
+	if (!pattern) {
+		const length = fullBlocksOnly ? protectedLen - protectedLen % AES_BLOCK_SIZE : protectedLen;
+		return length > 0 ? [{
+			offset,
+			length
+		}] : [];
+	}
+	if (pattern.cryptByteBlock <= 0) return [];
+	const ranges = [];
+	const cryptLen = AES_BLOCK_SIZE * pattern.cryptByteBlock;
+	const skipLen = AES_BLOCK_SIZE * pattern.skipByteBlock;
+	let remaining = protectedLen;
+	let position = offset;
+	while (remaining > 0) {
+		if (remaining < cryptLen) break;
+		ranges.push({
+			offset: position,
+			length: cryptLen
+		});
+		position += cryptLen;
+		remaining -= cryptLen;
+		const currentSkipLen = Math.min(skipLen, remaining);
+		position += currentSkipLen;
+		remaining -= currentSkipLen;
+	}
+	return ranges;
+};
+const collectCtrRanges = (options) => {
+	if (!options.subsamples) return [{
+		offset: 0,
+		length: options.data.byteLength
+	}];
+	const ranges = [];
+	let cursor = 0;
+	for (const subsample of options.subsamples) {
+		cursor += subsample.clearLen;
+		ranges.push(...collectProtectedRanges(cursor, subsample.protectedLen, options.pattern, false));
+		cursor += subsample.protectedLen;
+	}
+	return ranges;
+};
+const collectCbcsGroups = (options) => {
+	if (!options.subsamples) return [{
+		iv: options.iv.slice(),
+		ranges: [{
+			offset: 0,
+			length: options.data.byteLength - options.data.byteLength % AES_BLOCK_SIZE
+		}]
+	}];
+	if (!options.pattern) throw new Error("decryptBytes does not support cbcs subsample encryption without pattern encryption.");
+	const groups = [];
+	let cursor = 0;
+	for (const subsample of options.subsamples) {
+		cursor += subsample.clearLen;
+		groups.push({
+			iv: options.iv.slice(),
+			ranges: collectProtectedRanges(cursor, subsample.protectedLen, options.pattern, true)
+		});
+		cursor += subsample.protectedLen;
+	}
+	return groups;
+};
+const getRangeData = (data, ranges) => {
+	let totalLength = 0;
+	for (const range of ranges) totalLength += range.length;
+	const protectedData = new Uint8Array(totalLength);
+	let writeOffset = 0;
+	for (const range of ranges) {
+		protectedData.set(data.subarray(range.offset, range.offset + range.length), writeOffset);
+		writeOffset += range.length;
+	}
+	return protectedData;
+};
+const mergeRangeData = (target, decryptedData, ranges) => {
+	let readOffset = 0;
+	for (const range of ranges) {
+		target.set(decryptedData.subarray(readOffset, readOffset + range.length), range.offset);
+		readOffset += range.length;
+	}
+};
+const decryptGroups = async (options, groups, decryptBytesCallback) => {
+	const decryptedSample = new Uint8Array(options.data);
+	for (const group of groups) {
+		const encryptedData = getRangeData(options.data, group.ranges);
+		if (encryptedData.byteLength === 0) continue;
+		const decryptedData = await decryptBytesCallback({
+			data: encryptedData,
+			keyId: options.keyId,
+			psshBoxes: options.psshBoxes,
+			scheme: options.scheme,
+			iv: group.iv.slice(),
+			timestamp: options.timestamp,
+			subsamples: cloneSubsamples$1(options.subsamples),
+			pattern: clonePattern(options.pattern)
+		});
+		if (!isUint8Array$1(decryptedData)) throw new TypeError("decryptBytes callback must return a Uint8Array.");
+		if (decryptedData.byteLength !== encryptedData.byteLength) throw new Error("decryptBytes callback must return the same number of bytes as the encrypted input.");
+		mergeRangeData(decryptedSample, decryptedData, group.ranges);
+	}
+	return decryptedSample;
+};
+const decryptBytes = (decryptBytesCallback) => async (options) => {
+	if (options.scheme === "cbcs") return decryptGroups(options, collectCbcsGroups(options), decryptBytesCallback);
+	return decryptGroups(options, [{
+		iv: options.iv.slice(),
+		ranges: collectCtrRanges(options)
+	}], decryptBytesCallback);
+};
+//#endregion
+//#region src/mediabunny-isobmff.ts
+const binarySearchLessOrEqual = (items, needle, getValue) => {
+	let low = 0;
+	let high = items.length - 1;
+	let result = -1;
+	while (low <= high) {
+		const middle = low + Math.floor((high - low) / 2);
+		if (getValue(items[middle]) <= needle) {
+			result = middle;
+			low = middle + 1;
+		} else high = middle - 1;
+	}
+	return result;
+};
+const binarySearchExact = (items, needle, getValue) => {
+	let low = 0;
+	let high = items.length - 1;
+	while (low <= high) {
+		const middle = low + Math.floor((high - low) / 2);
+		const value = getValue(items[middle]);
+		if (value === needle) return middle;
+		if (value < needle) low = middle + 1;
+		else high = middle - 1;
+	}
+	return -1;
+};
+const readBytes = (slice, length) => {
+	const bytes = slice.bytes.slice(slice.bufferPos, slice.bufferPos + length);
+	slice.bufferPos += length;
+	return bytes;
+};
+const readU16Be = (slice) => {
+	const value = slice.view.getUint16(slice.bufferPos, false);
+	slice.bufferPos += 2;
+	return value;
+};
+const readU32Be = (slice) => {
+	const value = slice.view.getUint32(slice.bufferPos, false);
+	slice.bufferPos += 4;
+	return value;
+};
+const readSampleBytes = async (internalTrack, byteOffset, byteLength) => {
+	let slice = internalTrack.demuxer.reader.requestSlice(byteOffset, byteLength);
+	if (slice instanceof Promise) slice = await slice;
+	if (!slice) throw new Error("Failed to read encrypted sample bytes.");
+	return readBytes(slice, byteLength);
+};
+const resolveEncryptionAuxInfo = async (internalTrack, auxInfo) => {
+	if (auxInfo.resolved) return auxInfo.resolved;
+	const encryptionInfo = internalTrack.encryptionInfo;
+	if (!encryptionInfo || encryptionInfo.defaultPerSampleIvSize === null) throw new Error("Missing track encryption info.");
+	if (auxInfo.offset === null || auxInfo.sampleCount === 0) throw new Error("Incomplete saiz/saio info; cannot resolve encryption data.");
+	if (auxInfo.defaultSampleInfoSize === 0 && !auxInfo.sampleSizes) throw new Error("Invalid auxiliary encryption info: auxInfo.sampleSizes is required when auxInfo.defaultSampleInfoSize is 0.");
+	let totalSize = 0;
+	if (auxInfo.defaultSampleInfoSize > 0) totalSize = auxInfo.defaultSampleInfoSize * auxInfo.sampleCount;
+	else if (auxInfo.sampleSizes) for (const size of auxInfo.sampleSizes) totalSize += size;
+	let slice = internalTrack.demuxer.reader.requestSlice(auxInfo.offset, totalSize);
+	if (slice instanceof Promise) slice = await slice;
+	if (!slice) throw new Error("Failed to read auxiliary encryption info.");
+	const entries = [];
+	const ivSize = encryptionInfo.defaultPerSampleIvSize;
+	for (let i = 0; i < auxInfo.sampleCount; i++) {
+		const entrySize = auxInfo.defaultSampleInfoSize > 0 ? auxInfo.defaultSampleInfoSize : auxInfo.sampleSizes?.[i] ?? 0;
+		const iv = new Uint8Array(16);
+		if (ivSize > 0) iv.set(readBytes(slice, ivSize), 0);
+		else if (encryptionInfo.defaultConstantIv) iv.set(encryptionInfo.defaultConstantIv, 0);
+		let subsamples = null;
+		if (entrySize > ivSize) {
+			const subsampleCount = readU16Be(slice);
+			subsamples = [];
+			for (let j = 0; j < subsampleCount; j++) subsamples.push({
+				clearLen: readU16Be(slice),
+				protectedLen: readU32Be(slice)
+			});
+		}
+		entries.push({
+			iv,
+			subsamples
+		});
+	}
+	auxInfo.resolved = entries;
+	return entries;
+};
+const getSampleInfo = (sampleTable, sampleIndex) => {
+	const timingEntryIndex = binarySearchLessOrEqual(sampleTable.sampleTimingEntries, sampleIndex, (entry) => entry.startIndex);
+	const timingEntry = sampleTable.sampleTimingEntries[timingEntryIndex];
+	if (!timingEntry || timingEntry.startIndex + timingEntry.count <= sampleIndex) return null;
+	let presentationTimestamp = timingEntry.startDecodeTimestamp + (sampleIndex - timingEntry.startIndex) * timingEntry.delta;
+	const offsetEntryIndex = binarySearchLessOrEqual(sampleTable.sampleCompositionTimeOffsets, sampleIndex, (entry) => entry.startIndex);
+	const offsetEntry = sampleTable.sampleCompositionTimeOffsets[offsetEntryIndex];
+	if (offsetEntry && sampleIndex - offsetEntry.startIndex < offsetEntry.count) presentationTimestamp += offsetEntry.offset;
+	const sampleSize = sampleTable.sampleSizes[Math.min(sampleIndex, sampleTable.sampleSizes.length - 1)];
+	if (sampleSize === void 0) return null;
+	const chunkEntryIndex = binarySearchLessOrEqual(sampleTable.sampleToChunk, sampleIndex, (entry) => entry.startSampleIndex);
+	const chunkEntry = sampleTable.sampleToChunk[chunkEntryIndex];
+	if (!chunkEntry) return null;
+	const chunkIndex = chunkEntry.startChunkIndex + Math.floor((sampleIndex - chunkEntry.startSampleIndex) / chunkEntry.samplesPerChunk);
+	const chunkOffset = sampleTable.chunkOffsets[chunkIndex];
+	if (chunkOffset === void 0) return null;
+	const startSampleIndexOfChunk = chunkEntry.startSampleIndex + (chunkIndex - chunkEntry.startChunkIndex) * chunkEntry.samplesPerChunk;
+	let chunkSize = 0;
+	let sampleOffset = chunkOffset;
+	if (sampleTable.sampleSizes.length === 1) {
+		sampleOffset += sampleSize * (sampleIndex - startSampleIndexOfChunk);
+		chunkSize += sampleSize * chunkEntry.samplesPerChunk;
+	} else for (let i = startSampleIndexOfChunk; i < startSampleIndexOfChunk + chunkEntry.samplesPerChunk; i++) {
+		const currentSampleSize = sampleTable.sampleSizes[i];
+		if (currentSampleSize === void 0) return null;
+		if (i < sampleIndex) sampleOffset += currentSampleSize;
+		chunkSize += currentSampleSize;
+	}
+	let duration = timingEntry.delta;
+	if (sampleTable.presentationTimestamps && sampleTable.presentationTimestampIndexMap) {
+		const presentationIndex = sampleTable.presentationTimestampIndexMap[sampleIndex];
+		if (presentationIndex !== void 0 && presentationIndex < sampleTable.presentationTimestamps.length - 1) {
+			const nextEntry = sampleTable.presentationTimestamps[presentationIndex + 1];
+			if (nextEntry) duration = nextEntry.presentationTimestamp - presentationTimestamp;
+		}
+	}
+	const isKeyFrame = sampleTable.keySampleIndices ? binarySearchExact(sampleTable.keySampleIndices, sampleIndex, (value) => value) !== -1 : true;
+	return {
+		presentationTimestamp,
+		duration,
+		sampleOffset,
+		sampleSize,
+		chunkOffset,
+		chunkSize,
+		isKeyFrame
+	};
+};
+const psshBoxesAreEqual = (left, right) => {
+	if (left.systemId !== right.systemId) return false;
+	if (left.data.byteLength !== right.data.byteLength) return false;
+	for (let i = 0; i < left.data.byteLength; i++) if (left.data[i] !== right.data[i]) return false;
+	return true;
+};
+const cloneSubsamples = (subsamples) => {
+	if (!subsamples) return null;
+	return subsamples.map((subsample) => ({
+		clearLen: subsample.clearLen,
+		protectedLen: subsample.protectedLen
+	}));
+};
+const getPattern = (encryptionInfo) => {
+	const cryptByteBlock = encryptionInfo.defaultCryptByteBlock ?? 0;
+	const skipByteBlock = encryptionInfo.defaultSkipByteBlock ?? 0;
+	if (cryptByteBlock === 0 && skipByteBlock === 0) return null;
+	return {
+		cryptByteBlock,
+		skipByteBlock
+	};
+};
+const isUint8Array = (value) => value instanceof Uint8Array;
+const isIsobmffTrackBacking = (backing) => {
+	if (!backing || typeof backing !== "object") return false;
+	const maybeBacking = backing;
+	const internalTrack = maybeBacking.internalTrack;
+	return Boolean(internalTrack && internalTrack.demuxer && typeof internalTrack.demuxer.getSampleTableForTrack === "function" && maybeBacking.packetToSampleIndex instanceof WeakMap && maybeBacking.packetToFragmentLocation instanceof WeakMap);
+};
+const getTrackEncryptionInfo = (backing) => backing.internalTrack.encryptionInfo;
+const getKeyId = (backing) => backing.internalTrack.encryptionInfo?.defaultKid ?? null;
+const getEncryptedSample = async (backing, packet) => {
+	const internalTrack = backing.internalTrack;
+	const fragmentLocation = backing.packetToFragmentLocation.get(packet);
+	if (fragmentLocation) {
+		const fragment = fragmentLocation.fragment;
+		const sample = fragment.trackData.get(internalTrack.id)?.samples[fragmentLocation.sampleIndex];
+		if (!sample?.encryption) return null;
+		return {
+			data: await readSampleBytes(internalTrack, sample.byteOffset, sample.byteSize),
+			sampleEncryption: sample.encryption,
+			fragment
+		};
+	}
+	const sampleIndex = backing.packetToSampleIndex.get(packet);
+	if (sampleIndex === void 0) return null;
+	const sampleInfo = getSampleInfo(internalTrack.demuxer.getSampleTableForTrack(internalTrack), sampleIndex);
+	if (!sampleInfo) return null;
+	const auxInfo = internalTrack.encryptionAuxInfo;
+	if (!auxInfo) return null;
+	const sampleEncryption = (await resolveEncryptionAuxInfo(internalTrack, auxInfo))[sampleIndex];
+	if (!sampleEncryption) return null;
+	return {
+		data: await readSampleBytes(internalTrack, sampleInfo.sampleOffset, sampleInfo.sampleSize),
+		sampleEncryption,
+		fragment: null
+	};
+};
+const getPsshBoxes = (backing, keyId, fragment) => {
+	const { psshBoxes } = backing.internalTrack.demuxer;
+	if (!fragment) return psshBoxes;
+	const boxes = [...psshBoxes, ...fragment.psshBoxes].filter((psshBox) => psshBox.keyIds === null || psshBox.keyIds.includes(keyId));
+	for (let i = 0; i < boxes.length - 1; i++) for (let j = i + 1; j < boxes.length; j++) if (psshBoxesAreEqual(boxes[i], boxes[j])) {
+		boxes.splice(j, 1);
+		j--;
+	}
+	return boxes;
+};
+//#endregion
+//#region src/isobmff-decrypt-sample-patcher.ts
+const createMetadataOnlyOptions = (options) => ({
+	...options,
+	metadataOnly: true,
+	verifyKeyPackets: false
+});
+var IsobmffDecryptSamplePatcher = class {
+	input;
+	decryptSample;
+	reportEncryptionInfo;
+	patchableTrackBackings = /* @__PURE__ */ new WeakSet();
+	patchTrackBackingsPromise = null;
+	constructor(input, decryptSample, reportEncryptionInfo) {
+		this.input = input;
+		this.decryptSample = decryptSample;
+		this.reportEncryptionInfo = reportEncryptionInfo;
+	}
+	async ensurePatched() {
+		this.patchTrackBackingsPromise ??= (async () => {
+			const tracks = await this.input.getTracks();
+			for (const track of tracks) {
+				const backing = track._backing;
+				if (!isIsobmffTrackBacking(backing) || this.patchableTrackBackings.has(backing)) continue;
+				this.patchableTrackBackings.add(backing);
+				this.patchTrackBacking(backing);
+			}
+		})();
+		await this.patchTrackBackingsPromise;
+	}
+	patchTrackBacking(backing) {
+		const packetToMetadataPacket = /* @__PURE__ */ new WeakMap();
+		const getOriginalPacket = (packet) => packetToMetadataPacket.get(packet) ?? packet;
+		const getFirstPacket = backing.getFirstPacket.bind(backing);
+		backing.getFirstPacket = async (options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getFirstPacket(options);
+			const metadataPacket = await getFirstPacket(createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getFirstPacket(options), packetToMetadataPacket);
+		};
+		const getPacket = backing.getPacket.bind(backing);
+		backing.getPacket = async (timestamp, options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getPacket(timestamp, options);
+			const metadataPacket = await getPacket(timestamp, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getPacket(timestamp, options), packetToMetadataPacket);
+		};
+		const getNextPacket = backing.getNextPacket.bind(backing);
+		backing.getNextPacket = async (packet, options) => {
+			const originalPacket = getOriginalPacket(packet);
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getNextPacket(originalPacket, options);
+			const metadataPacket = await getNextPacket(originalPacket, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getNextPacket(originalPacket, options), packetToMetadataPacket);
+		};
+		const getKeyPacket = backing.getKeyPacket.bind(backing);
+		backing.getKeyPacket = async (timestamp, options) => {
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getKeyPacket(timestamp, options);
+			const metadataPacket = await getKeyPacket(timestamp, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getKeyPacket(timestamp, options), packetToMetadataPacket);
+		};
+		const getNextKeyPacket = backing.getNextKeyPacket.bind(backing);
+		backing.getNextKeyPacket = async (packet, options) => {
+			const originalPacket = getOriginalPacket(packet);
+			if (!this.shouldUseCustomDecryptSample(backing, options)) return getNextKeyPacket(originalPacket, options);
+			const metadataPacket = await getNextKeyPacket(originalPacket, createMetadataOnlyOptions(options));
+			return this.materializePacket(backing, metadataPacket, () => getNextKeyPacket(originalPacket, options), packetToMetadataPacket);
+		};
+	}
+	shouldUseCustomDecryptSample(backing, options) {
+		return Boolean(!options.metadataOnly && getTrackEncryptionInfo(backing)?.defaultIsProtected !== false);
+	}
+	async materializePacket(backing, metadataPacket, fallback, packetToMetadataPacket) {
+		if (!metadataPacket) return null;
+		const decryptedPacket = await this.decryptPacket(backing, metadataPacket, fallback);
+		if (decryptedPacket && decryptedPacket !== metadataPacket) packetToMetadataPacket.set(decryptedPacket, metadataPacket);
+		return decryptedPacket;
+	}
+	async decryptPacket(backing, metadataPacket, fallback) {
+		const encryptionInfo = getTrackEncryptionInfo(backing);
+		if (!encryptionInfo?.defaultIsProtected) return fallback();
+		const keyId = getKeyId(backing);
+		if (!keyId) throw new Error("Encrypted sample encountered without a key ID.");
+		const encryptedSample = await getEncryptedSample(backing, metadataPacket);
+		if (!encryptedSample) return fallback();
+		const psshBoxes = getPsshBoxes(backing, keyId, encryptedSample.fragment);
+		this.reportEncryptionInfo(keyId, psshBoxes);
+		const decryptedData = await this.decryptSample({
+			data: encryptedSample.data,
+			keyId,
+			psshBoxes,
+			scheme: encryptionInfo.scheme,
+			iv: encryptedSample.sampleEncryption.iv.slice(),
+			timestamp: metadataPacket.microsecondTimestamp,
+			subsamples: cloneSubsamples(encryptedSample.sampleEncryption.subsamples),
+			pattern: getPattern(encryptionInfo)
+		});
+		if (!isUint8Array(decryptedData)) throw new TypeError("decryption callback must return a Uint8Array.");
+		if (decryptedData.byteLength !== metadataPacket.byteLength) throw new Error("decryption callback must return the same number of bytes as the encrypted sample.");
+		return new EncodedPacket(decryptedData, metadataPacket.type, metadataPacket.timestamp, metadataPacket.duration, metadataPacket.sequenceNumber, metadataPacket.byteLength, metadataPacket.sideData);
+	}
+};
+//#endregion
 //#region src/index.ts
+const createEncryptionReporter = (handleEncryptionInfo) => {
+	const reportedEncryptionInfo = /* @__PURE__ */ new Set();
+	return (keyId, psshBoxes) => {
+		if (!handleEncryptionInfo || reportedEncryptionInfo.has(keyId)) return;
+		reportedEncryptionInfo.add(keyId);
+		handleEncryptionInfo({
+			keyId,
+			psshBoxes
+		});
+	};
+};
 var Input = class extends Input$1 {
-	constructor({ keys, handleEncryptionInfo, ...options }) {
+	decryptSamplePatcher;
+	constructor({ keys, decryptSample, handleEncryptionInfo, ...options }) {
+		if (!keys?.size && !decryptSample) throw new Error("Either keys or decryptSample must be provided.");
+		const reportEncryptionInfo = createEncryptionReporter(handleEncryptionInfo);
 		super({
 			...options,
 			formats: ALL_FORMATS,
 			formatOptions: { isobmff: { resolveKeyId: ({ keyId, psshBoxes }) => {
-				handleEncryptionInfo?.({
-					keyId,
-					psshBoxes
-				});
-				const key = keys.get(keyId);
+				reportEncryptionInfo(keyId, psshBoxes);
+				const key = keys?.get(keyId);
 				if (!key) throw new Error("Unknown key ID.");
 				return key;
 			} } }
 		});
+		this.decryptSamplePatcher = decryptSample ? new IsobmffDecryptSamplePatcher({ getTracks: (query) => this.getTracksWithoutPatching(query) }, decryptSample, reportEncryptionInfo) : null;
+	}
+	async getTracks(query) {
+		await this.decryptSamplePatcher?.ensurePatched();
+		return super.getTracks(query);
+	}
+	async getTracksWithoutPatching(query) {
+		return super.getTracks(query);
 	}
 };
 var Output = class extends Output$1 {
@@ -26,4 +470,4 @@ var Output = class extends Output$1 {
 	}
 };
 //#endregion
-export { Conversion as Decryption, FilePathSource, FilePathTarget, Input, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output, ReadableStreamSource, StreamSource, StreamTarget, UrlSource };
+export { Conversion as Decryption, FilePathSource, FilePathTarget, Input, MkvOutputFormat, MovOutputFormat, Mp3OutputFormat, Mp4OutputFormat, Output, ReadableStreamSource, StreamSource, StreamTarget, UrlSource, decryptBytes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shifro",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "description": "A lightweight library and command-line tool for decrypting MP4 files",
   "files": [
     "dist"