Add fastStart: 'reserve' option (closes #119)

src/output.ts

@@ -74,6 +74,21 @@ export type BaseTrackMetadata = {
 	languageCode?: string;
 	/** A user-defined name for this track, like "English" or "Director Commentary". */
 	name?: string;
+	/**
+	 * The maximum amount of encoded packets that will be added to this track. Setting this field provides the muxer
+	 * with an additional signal that it can use to preallocate space in the file.
+	 *
+	 * When this field is set, it is an error to provide more packets than whatever this field specifies.
+	 *
+	 * Predicting the maximum packet count requires considering both the maximum duration as well as the codec.
+	 * - For video codecs, you can assume one packet per frame.
+	 * - For audio codecs, there is one packet for each "audio chunk", the duration of which depends on the codec. For
+	 * simplicity, you can assume each packet is roughly 10 ms or 512 samples long, whichever is shorter.
+	 * - For subtitles, assume each cue and each gap in the subtitles adds a packet.
+	 *
+	 * If you're not fully sure, make sure to add a buffer of around 33% to make sure you stay below the maximum.
+	 */
+	maximumPacketCount?: number;
 };
 
 /**
@@ -114,6 +129,12 @@ const validateBaseTrackMetadata = (metadata: BaseTrackMetadata) => {
 	if (metadata.name !== undefined && typeof metadata.name !== 'string') {
 		throw new TypeError('metadata.name, when provided, must be a string.');
 	}
+	if (
+		metadata.maximumPacketCount !== undefined
+		&& (!Number.isInteger(metadata.maximumPacketCount) || metadata.maximumPacketCount < 0)
+	) {
+		throw new TypeError('metadata.maximumPacketCount, when provided, must be a non-negative integer.');
+	}
 };
 
 /**