@bubo-squared/gyroview 0.1.0 → 0.3.0

package/dist/packages/core/src/application/download/startFileDownload.js

@@ -0,0 +1,37 @@
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { DownloadedAudioSamples } from "./DownloadedAudioSamples.js";
+import { DownloadedVideoTrack } from "./DownloadedVideoTrack.js";
+import { FileDownload } from "./FileDownload.js";
+//#region ../../packages/core/src/application/download/startFileDownload.ts
+/**
+* Use case: download a file while it plays, its tracks joined to their codecs by track id.
+*/
+function startFileDownload(start) {
+	const download = new FileDownload(start);
+	return {
+		download,
+		videoTracks: start.codecs.video.map((codec) => new DownloadedVideoTrack({
+			download,
+			track: trackOf(start.table, codec.trackId, "video"),
+			codec
+		})),
+		audioTracks: start.codecs.audio.map((codec) => ({
+			samples: new DownloadedAudioSamples({
+				download,
+				track: trackOf(start.table, codec.trackId, "audio")
+			}),
+			configuration: codec.configuration
+		})),
+		duration: start.table.duration,
+		dispose: () => {
+			download.dispose();
+		}
+	};
+}
+function trackOf(table, trackId, kind) {
+	const track = table.trackWithId(trackId);
+	if (track?.kind !== kind) throw new GyroViewError("unsupported-container", `the movie box has no ${kind} track ${trackId} to read`);
+	return track;
+}
+//#endregion
+export { startFileDownload };

package/dist/packages/core/src/application/playback/Buffering.js

@@ -0,0 +1,53 @@
+import { Deferred } from "../../shared/async/Deferred.js";
+//#region ../../packages/core/src/application/playback/Buffering.ts
+/**
+* A session's `buffering`: entering it and why, the `play` waiting for the clock to start
+* meanwhile, and what ends it, told in one place.
+*/
+var Buffering = class {
+	lifecycle;
+	cause = "priming";
+	startAttempt;
+	constructor(lifecycle) {
+		this.lifecycle = lifecycle;
+	}
+	/**
+	* The `play` waiting for buffering to end, if one is.
+	*/
+	get waitingStart() {
+		return this.startAttempt?.promise;
+	}
+	enter(cause) {
+		this.cause = cause;
+		this.lifecycle.moveTo("buffering");
+	}
+	/**
+	* Buffers for the first frames of a start, which the promise waits for.
+	*/
+	enterForStart() {
+		const attempt = new Deferred();
+		this.startAttempt = attempt;
+		this.enter("priming");
+		return attempt.promise;
+	}
+	/**
+	* Buffering is over at `now`: what its cause waits for is there.
+	*/
+	isOverAt(run, now) {
+		if (!run || !this.lifecycle.is("buffering")) return false;
+		return this.cause === "priming" ? run.isPrimedAt(now) : run.isReadyToResumeAt(now);
+	}
+	/**
+	* The waiting `play`, taken out to be settled by whoever ends the wait.
+	*/
+	takeStart() {
+		const attempt = this.startAttempt;
+		this.startAttempt = void 0;
+		return attempt;
+	}
+	settleStart() {
+		this.takeStart()?.resolve();
+	}
+};
+//#endregion
+export { Buffering };

package/dist/packages/core/src/application/playback/DecodePipeline.js

@@ -16,6 +16,11 @@ var DecodePipeline = class {
 	options;
 	stop = new RunStop();
 	hasRun = false;
+	/**
+	* The run's packet reads, which an abort returns at once: a read left to the run's unwinding
+	* would go on reading until its awaits settle.
+	*/
+	iterators = [];
 	constructor(frameSources, decoderPort, options) {
 		this.frameSources = frameSources;
 		this.decoderPort = decoderPort;
@@ -40,10 +45,12 @@ var DecodePipeline = class {
 		}
 	}
 	/**
-	* Ends the run early; pending decodes are discarded. Safe before, during and after the run.
+	* Ends the run early: its packet reads are let go of at once, pending decodes discarded. Safe
+	* before, during and after the run.
 	*/
 	abort() {
 		this.stop.stop();
+		closeIterators(this.iterators);
 	}
 	async openRun(from, output) {
 		const { stop } = this;
@@ -59,7 +66,8 @@ var DecodePipeline = class {
 		const pairer = new FramePairer(this.frameSources.length, this.options.pairTolerance, (pair) => {
 			gate.push(pair);
 		});
-		const iterators = stop.wasStopped ? [] : await this.packetIteratorsFrom(from);
+		const iterators = stop.wasStopped ? [] : this.packetIteratorsFrom(from);
+		this.iterators = iterators;
 		const onError = (error) => {
 			failure.resolve(error);
 			stop.stop();
@@ -123,11 +131,7 @@ var DecodePipeline = class {
 		}
 	}
 	packetIteratorsFrom(from) {
-		return Promise.all(this.frameSources.map(async (track) => {
-			const start = await track.keyPacketAt(from) ?? await track.firstKeyPacket();
-			if (!start) throw new GyroViewError("no-key-frame", `track ${track.description.trackIndex} has no key frame`);
-			return track.packetsFrom(start)[Symbol.asyncIterator]();
-		}));
+		return this.frameSources.map((track) => track.packetsFrom(from)[Symbol.asyncIterator]());
 	}
 };
 function shouldStop(run) {

package/dist/packages/core/src/application/playback/DecodeRun.js

@@ -17,19 +17,25 @@ var STARVATION_LAG_SECONDS = .25;
 * what arrives late and reports nothing, so a run a seek replaced never speaks for its successor.
 */
 var DecodeRun = class DecodeRun {
+	parts;
 	listener;
 	queue;
 	pipeline;
 	primingPairs;
+	stopFollowingBuffer;
 	isAborted = false;
 	hasReachedEnd = false;
 	hasHandedOutPair = false;
 	constructor(parts, listener) {
+		this.parts = parts;
 		this.listener = listener;
 		this.primingPairs = Math.min(PRIMING_PAIRS, parts.queueCapacity);
 		this.queue = new FramePairQueue(parts.queueCapacity, () => {
 			if (!this.isAborted) listener.onProgress();
 		});
+		this.stopFollowingBuffer = parts.buffer?.onProgress(() => {
+			listener.onProgress();
+		}) ?? (() => void 0);
 		this.pipeline = new DecodePipeline(parts.frameSources, parts.decoderPort, parts.pipeline);
 	}
 	static start(parts, from, listener) {
@@ -53,6 +59,14 @@ var DecodeRun = class DecodeRun {
 		return this.hasReachedEnd || hasCaughtUp && this.queue.length >= this.primingPairs;
 	}
 	/**
+	* Primed, and after a starvation enough downloaded ahead to go on with (ADR 0011), unless the
+	* run is over and nothing more will come.
+	*/
+	isReadyToResumeAt(now) {
+		const isDownloaded = () => this.parts.buffer?.isReadyToResumeAt(now) ?? true;
+		return this.isPrimedAt(now) && (this.hasReachedEnd || isDownloaded());
+	}
+	/**
 	* Nothing is queued, the run is not over, and the frame on screen (shown for `shownAt`, if any)
 	* is well behind the clock: the decoders cannot keep up, even when each tick still finds a
 	* pair to show.
@@ -75,6 +89,7 @@ var DecodeRun = class DecodeRun {
 	}
 	abort() {
 		this.isAborted = true;
+		this.stopFollowingBuffer();
 		this.pipeline.abort();
 		this.queue.close();
 	}

package/dist/packages/core/src/application/playback/PlaybackSession.js

@@ -2,11 +2,11 @@ import { asGyroViewError } from "../../shared/errors/GyroViewError.js";
 import { seconds } from "../../shared/units/time.js";
 import { clamp } from "../../shared/math/clamp.js";
 import { closeFramePair } from "../../ports/FramePair.js";
-import { Deferred } from "../../shared/async/Deferred.js";
 import { TypedEmitter } from "../../shared/events/TypedEmitter.js";
 import { ClockWatch, isAtEndOfMedia, isStoppedFromOutside } from "./ClockWatch.js";
 import { SeekOrder } from "./SeekOrder.js";
 import { TimeUpdates } from "./TimeUpdates.js";
+import { Buffering } from "./Buffering.js";
 import { SessionLifecycle } from "./SessionLifecycle.js";
 import { DecodeRun } from "./DecodeRun.js";
 import { keyframeTimeAt } from "./keyframeTimeAt.js";
@@ -35,10 +35,7 @@ var PlaybackSession = class {
 	*/
 	presented;
 	timeUpdates = new TimeUpdates(this.lifecycle);
-	/**
-	* The `play` call waiting for the clock to start once frames are ready.
-	*/
-	startAttempt;
+	buffering = new Buffering(this.lifecycle);
 	clockWatch = new ClockWatch();
 	seeks = new SeekOrder();
 	constructor(parts) {
@@ -60,7 +57,7 @@ var PlaybackSession = class {
 	async play() {
 		if (this.lifecycle.current === "playing") return;
 		if (this.lifecycle.current === "buffering") {
-			await this.startAttempt?.promise;
+			await this.buffering.waitingStart;
 			return;
 		}
 		await this.lifecycle.change(() => this.beginStart());
@@ -77,7 +74,7 @@ var PlaybackSession = class {
 			if (wasRunning) this.clockWatch.stoppedAt(this.parts.clock.currentTime);
 			if (!this.lifecycle.canMoveTo("paused")) return;
 			this.lifecycle.moveTo("paused");
-			this.settleStartAttempt();
+			this.buffering.settleStart();
 			this.timeUpdates.announce(this.parts.clock.currentTime);
 		});
 	}
@@ -102,7 +99,8 @@ var PlaybackSession = class {
 			this.moveClockTo(target);
 			this.startRun(target);
 			this.lifecycle.moveTo("seeking");
-			this.lifecycle.moveTo(this.seeks.resumesPlaying ? "buffering" : "paused");
+			if (this.seeks.resumesPlaying) this.buffering.enter("priming");
+			else this.lifecycle.moveTo("paused");
 			this.timeUpdates.announce(target);
 		});
 	}
@@ -176,7 +174,7 @@ var PlaybackSession = class {
 			this.presented = void 0;
 			this.parts.clock.pause();
 			this.lifecycle.moveTo("disposed");
-			this.settleStartAttempt();
+			this.buffering.settleStart();
 		});
 		this.events.removeAll();
 	}
@@ -197,11 +195,8 @@ var PlaybackSession = class {
 	* started (a media key's play). A pause settles the wait.
 	*/
 	startOncePrimed() {
-		const attempt = new Deferred();
-		this.startAttempt = attempt;
 		this.parts.clock.pause();
-		this.lifecycle.moveTo("buffering");
-		return attempt.promise;
+		return this.buffering.enterForStart();
 	}
 	/**
 	* Starts the clock once `playing` has been heard, unless a listener paused on it: an audio
@@ -239,7 +234,7 @@ var PlaybackSession = class {
 		}
 		if (this.run?.isStarvedAt(now, this.presented?.pair.timestamp) === true) {
 			this.parts.clock.pause();
-			this.lifecycle.moveTo("buffering");
+			this.buffering.enter("starvation");
 			return;
 		}
 		this.timeUpdates.followPlayback(now);
@@ -299,8 +294,12 @@ var PlaybackSession = class {
 		const wasRunning = clock.isRunning;
 		clock.pause();
 		this.startRun(now);
-		this.lifecycle.moveTo(wasRunning ? "buffering" : "paused");
-		if (!wasRunning) this.timeUpdates.announce(now);
+		if (wasRunning) {
+			this.buffering.enter("priming");
+			return;
+		}
+		this.lifecycle.moveTo("paused");
+		this.timeUpdates.announce(now);
 	}
 	/**
 	* Ended, or paused at the end: a play from there starts over, as a media element does.
@@ -315,14 +314,14 @@ var PlaybackSession = class {
 	* Called as pairs arrive and when a run ends: the moment `buffering` has what it waits for.
 	*/
 	resumeIfPrimed() {
-		if (this.lifecycle.current === "buffering" && this.isPrimed()) this.resume();
+		if (this.buffering.isOverAt(this.run, this.parts.clock.currentTime)) this.resume();
 	}
 	/**
 	* Leaves `buffering` for `playing` and starts the clock; a refusal (only possible before the
 	* first start) lands `paused` and is reported to the waiting `play`.
 	*/
 	async resume() {
-		const attempt = this.takeStartAttempt();
+		const attempt = this.buffering.takeStart();
 		this.enterPlaying();
 		try {
 			await this.startClockOnceHeard();
@@ -339,14 +338,6 @@ var PlaybackSession = class {
 			throw error;
 		}
 	}
-	settleStartAttempt() {
-		this.takeStartAttempt()?.resolve();
-	}
-	takeStartAttempt() {
-		const attempt = this.startAttempt;
-		this.startAttempt = void 0;
-		return attempt;
-	}
 	/**
 	* The clock's own media ran out (an audio track shorter than the video: the pairs after it are
 	* unreachable, and the decoders may wait for room to decode them forever), or everything
@@ -408,7 +399,7 @@ var PlaybackSession = class {
 			this.parts.clock.pause();
 			this.abortRun();
 			this.lifecycle.moveTo("error");
-			this.settleStartAttempt();
+			this.buffering.settleStart();
 			this.lifecycle.announce("error", asGyroViewError(error, "decode", "playback failed"));
 		});
 	}

package/dist/packages/core/src/application/playback/keyframeTimeAt.js

@@ -6,7 +6,7 @@
 */
 async function keyframeTimeAt(track, time) {
 	try {
-		return (await track.keyPacketAt(time))?.timestamp ?? time;
+		return (await track.keyframeAt(time))?.timestamp ?? time;
 	} catch {
 		return time;
 	}

package/dist/packages/core/src/application/playback/probeDecoding.js

@@ -93,8 +93,10 @@ var SourceProbe = class {
 		const configuration = await this.track.decoderConfiguration();
 		if (!await this.decoderPort.isSupported(configuration)) return unsupported(configuration);
 		if (this.isClosed) return TIMED_OUT;
+		const firstKeyframe = await this.track.firstKeyframe();
+		if (!firstKeyframe) return NO_KEY_FRAME;
 		this.isReadingKeyFrame = true;
-		const keyPacket = await this.track.firstKeyPacket();
+		const keyPacket = await firstPacketFrom(this.track, firstKeyframe.timestamp);
 		this.isReadingKeyFrame = false;
 		return keyPacket ? await this.decodeFirst(configuration, keyPacket) : NO_KEY_FRAME;
 	}
@@ -164,5 +166,17 @@ function failedWith(error) {
 		detail: message
 	};
 }
+/**
+* The first packet the track hands out from `time`, its iteration let go of at once.
+*/
+async function firstPacketFrom(track, time) {
+	const packets = track.packetsFrom(time)[Symbol.asyncIterator]();
+	try {
+		const first = await packets.next();
+		return first.done === true ? void 0 : first.value;
+	} finally {
+		packets.return?.();
+	}
+}
 //#endregion
 export { probeDecoding };

package/dist/packages/core/src/application/recording/readSampleTable.js

@@ -0,0 +1,27 @@
+import { GyroViewError } from "../../shared/errors/GyroViewError.js";
+import { scanBoxes } from "../../domain/format/boxes/scanBoxes.js";
+import { Mp4BoxType } from "../../domain/format/mp4/mp4BoxTypes.js";
+import { parseMovie } from "../../domain/format/mp4/parseMovie.js";
+import { concatenated } from "../../shared/binary/concatenated.js";
+//#region ../../packages/core/src/application/recording/readSampleTable.ts
+/**
+* Use case: read where every sample of a file lies and when it shows. The top-level boxes are
+* walked header by header, then the file type and the movie box are read whole, once each; not
+* a byte of the media data is read.
+*/
+async function readSampleTable(source) {
+	const boxes = await scanBoxes(source, await source.size());
+	const movie = boxes.find((box) => box.type === Mp4BoxType.Movie);
+	if (!movie) throw new GyroViewError("unsupported-container", "the file has no movie box to read its samples from");
+	const fileType = boxes.find((box) => box.type === Mp4BoxType.FileType);
+	const [fileTypeBytes, movieBox] = await Promise.all([bytesOf(source, fileType), bytesOf(source, movie)]);
+	return {
+		table: parseMovie(movieBox),
+		movieBytes: concatenated([fileTypeBytes, movieBox])
+	};
+}
+function bytesOf(source, box) {
+	return box ? source.read(box.range) : Promise.resolve(/* @__PURE__ */ new Uint8Array());
+}
+//#endregion
+export { readSampleTable };

package/dist/packages/core/src/application/recording/timeRecording.js

@@ -33,12 +33,12 @@ async function timeByTheClock(recording, frameSource) {
 	};
 }
 /**
-* Where the frame source's frames lie in time: the first shows where the first key packet does
-* (a track without one does not decode), and the rest follow at that packet's duration, the
+* Where the frame source's frames lie in time: the first shows where the first key frame does
+* (a track without one does not decode), and the rest follow at that frame's duration, the
 * cameras recording at a constant rate.
 */
 async function timelineOf(recordingClock, frameSource) {
-	const firstKey = await frameSource.firstKeyPacket();
+	const firstKey = await frameSource.firstKeyframe();
 	const hasDuration = firstKey !== void 0 && firstKey.duration > 0;
 	return {
 		clock: recordingClock.withFirstFrameAt(firstKey?.timestamp ?? seconds(0)),

package/dist/packages/core/src/domain/container/KeyframeRule.js

@@ -0,0 +1,7 @@
+//#region ../../packages/core/src/domain/container/KeyframeRule.ts
+/**
+* For tracks whose every sample decodes on its own, as audio does.
+*/
+var EVERY_SAMPLE_IS_A_KEYFRAME = { isKeyframe: () => true };
+//#endregion
+export { EVERY_SAMPLE_IS_A_KEYFRAME };

package/dist/packages/core/src/domain/container/SampleTable.js

@@ -0,0 +1,29 @@
+import { seconds } from "../../shared/units/time.js";
+//#region ../../packages/core/src/domain/container/SampleTable.ts
+/**
+* Every sample of one file, track by track, as its movie box describes them: the player's own
+* reading of the container, from which it downloads and decodes.
+*/
+var SampleTable = class {
+	tracks;
+	constructor(tracks) {
+		this.tracks = tracks;
+	}
+	get videoTracks() {
+		return this.tracks.filter((track) => track.kind === "video");
+	}
+	get audioTracks() {
+		return this.tracks.filter((track) => track.kind === "audio");
+	}
+	/**
+	* Until the last sample of any track stops showing.
+	*/
+	get duration() {
+		return seconds(Math.max(0, ...this.tracks.map((track) => track.end)));
+	}
+	trackWithId(trackId) {
+		return this.tracks.find((track) => track.trackId === trackId);
+	}
+};
+//#endregion
+export { SampleTable };

package/dist/packages/core/src/domain/container/TrackSampleTable.js

@@ -0,0 +1,96 @@
+import { ensureIndexInRange, ensureInvariant } from "../../shared/errors/GyroViewError.js";
+import { seconds } from "../../shared/units/time.js";
+import { ByteRange } from "../../shared/binary/ByteRange.js";
+import { presentationOrderOf } from "./presentationOrder.js";
+import { countAtOrBelow } from "../../shared/math/countAtOrBelow.js";
+//#region ../../packages/core/src/domain/container/TrackSampleTable.ts
+/**
+* One track's samples as its sample table describes them: where each lies, when it shows and
+* where decoding may start. Samples are numbered from zero in decode order; the presentation
+* order, which composition offsets may make another, is kept beside it.
+*/
+var TrackSampleTable = class {
+	parts;
+	trackId;
+	kind;
+	end;
+	keyframeRule;
+	/**
+	* The samples in the order they show; ties keep decode order.
+	*/
+	presentationOrder;
+	constructor(parts) {
+		this.parts = parts;
+		const { length } = parts.offsets;
+		const columns = [
+			parts.sizes,
+			parts.timestamps,
+			parts.durations
+		];
+		ensureInvariant(columns.every((column) => column.length === length), `the sample table of track ${parts.trackId} disagrees on its sample count`);
+		ensureInvariant(isAscendingWithin(parts.syncSamples ?? [], length), `the sync samples of track ${parts.trackId} are not samples of it in order`);
+		this.trackId = parts.trackId;
+		this.kind = parts.kind;
+		this.end = parts.end;
+		this.keyframeRule = parts.keyframeRule;
+		this.presentationOrder = presentationOrderOf(parts.timestamps);
+	}
+	get sampleCount() {
+		return this.parts.offsets.length;
+	}
+	rangeOf(sample) {
+		this.ensureSample(sample);
+		return ByteRange.of(this.parts.offsets[sample] ?? 0, this.parts.sizes[sample] ?? 0);
+	}
+	timestampOf(sample) {
+		this.ensureSample(sample);
+		return seconds(this.parts.timestamps[sample] ?? 0);
+	}
+	durationOf(sample) {
+		this.ensureSample(sample);
+		return seconds(this.parts.durations[sample] ?? 0);
+	}
+	isSync(sample) {
+		this.ensureSample(sample);
+		return this.syncSampleAtOrBefore(sample) === sample;
+	}
+	/**
+	* The sample on screen at `time`: the last to show at or before it. Undefined before the first.
+	*/
+	sampleShownAt(time) {
+		const shownSoFar = countAtOrBelow(this.presentationOrder.length, (index) => this.parts.timestamps[this.presentationOrder[index] ?? 0] ?? Infinity, time);
+		return this.presentationOrder[shownSoFar - 1];
+	}
+	/**
+	* The sample decoding for `time` starts at: the sync sample at or before the one on screen.
+	*/
+	keyframeAt(time) {
+		const shown = this.sampleShownAt(time);
+		return shown === void 0 ? void 0 : this.syncSampleAtOrBefore(shown);
+	}
+	syncSampleAtOrBefore(sample) {
+		const { syncSamples } = this.parts;
+		if (!syncSamples) return sample >= 0 ? sample : void 0;
+		return syncSamples[countAtOrBelow(syncSamples.length, (index) => syncSamples[index] ?? 0, sample) - 1];
+	}
+	/**
+	* The first sync sample at or after `sample`; none where no sync sample follows.
+	*/
+	syncSampleAtOrAfter(sample) {
+		const { syncSamples } = this.parts;
+		const first = Math.max(0, sample);
+		if (!syncSamples) return first < this.sampleCount ? first : void 0;
+		return syncSamples[countAtOrBelow(syncSamples.length, (index) => syncSamples[index] ?? 0, first - 1)];
+	}
+	timestampsInPresentationOrder() {
+		return this.presentationOrder.map((sample) => seconds(this.parts.timestamps[sample] ?? 0));
+	}
+	ensureSample(sample) {
+		ensureIndexInRange(sample, this.sampleCount, `sample of track ${this.trackId}`);
+	}
+};
+function isAscendingWithin(samples, count) {
+	return samples.every((sample, index) => Number.isSafeInteger(sample) && sample >= 0 && sample < count && sample > (samples[index - 1] ?? -1));
+}
+//#endregion
+export { TrackSampleTable };

package/dist/packages/core/src/domain/container/presentationOrder.js

@@ -0,0 +1,10 @@
+//#region ../../packages/core/src/domain/container/presentationOrder.ts
+/**
+* The samples in the order they show, given when each shows in decode order; samples that show
+* at the same time keep their decode order, as a stable sort keeps them.
+*/
+function presentationOrderOf(times) {
+	return Array.from({ length: times.length }, (_, sample) => sample).toSorted((left, right) => (times[left] ?? 0) - (times[right] ?? 0));
+}
+//#endregion
+export { presentationOrderOf };

package/dist/packages/core/src/domain/download/DownloadPolicy.js

@@ -0,0 +1,41 @@
+import { seconds } from "../../shared/units/time.js";
+//#region ../../packages/core/src/domain/download/DownloadPolicy.ts
+var MEBIBYTE = 1048576;
+/**
+* What the policy reads ahead and keeps behind, as time and at most as bytes: the byte limits
+* bind first on the X5's 210 Mbit/s, the times on slower recordings. A split recording shares
+* the byte limits among its files.
+*/
+var AHEAD_SECONDS = 10;
+var MOST_AHEAD_MEBIBYTES = 128;
+var KEEP_BEHIND_SECONDS = 2;
+var MOST_KEPT_BEHIND_MEBIBYTES = 32;
+var REQUEST_MEBIBYTES = 8;
+var REQUESTS_IN_FLIGHT = 2;
+var BRIDGED_GAP_MEBIBYTES = 1;
+var REFILL_FRACTION = .25;
+/**
+* Long enough that a link slower than the recording plays in stretches rather than frame by
+* frame, short enough that the wait does not feel like a stop.
+*/
+var RESUME_SECONDS = 4;
+/**
+* The policy for one file of a recording of `fileCount` files, by its bit rate.
+*/
+function downloadPolicyFor(file, fileCount) {
+	const bytesPerSecond = file.size / file.duration;
+	const aheadBytes = Math.min(Math.round(AHEAD_SECONDS * bytesPerSecond), MOST_AHEAD_MEBIBYTES * MEBIBYTE / fileCount);
+	return {
+		aheadSeconds: seconds(AHEAD_SECONDS),
+		aheadBytes,
+		keepBehindBytes: Math.min(Math.round(KEEP_BEHIND_SECONDS * bytesPerSecond), MOST_KEPT_BEHIND_MEBIBYTES * MEBIBYTE / fileCount),
+		keepBehindSeconds: seconds(KEEP_BEHIND_SECONDS),
+		requestSize: REQUEST_MEBIBYTES * MEBIBYTE,
+		requestsInFlight: REQUESTS_IN_FLIGHT,
+		bridgedGap: BRIDGED_GAP_MEBIBYTES * MEBIBYTE,
+		refillBytes: Math.round(aheadBytes * REFILL_FRACTION),
+		resumeSeconds: seconds(RESUME_SECONDS)
+	};
+}
+//#endregion
+export { downloadPolicyFor };

package/dist/packages/core/src/domain/download/isReadyToResume.js

@@ -0,0 +1,27 @@
+import { seconds } from "../../shared/units/time.js";
+import { ByteRangeSet } from "../../shared/binary/ByteRangeSet.js";
+import { needsOf, withinBytes } from "./trackNeeds.js";
+//#region ../../packages/core/src/domain/download/isReadyToResume.ts
+/**
+* What playback that starved at `time` waits for before it plays again (ADR 0011, ADR 0029):
+* every picture reader's frames up to the policy's resume seconds past it, or as many of them as
+* the budget holds less a request (a refill's worth, where that is less), so the download that
+* keeps it held still tops up in large ranges. Sound needs nothing of its own.
+*/
+function resumeThresholdOf(need) {
+	const { policy } = need;
+	const until = seconds(need.time + policy.resumeSeconds);
+	const pictures = need.cursors.filter((cursor) => cursor.track.kind === "video");
+	const needs = ByteRangeSet.of(pictures.flatMap((cursor) => needsOf(cursor, until)));
+	const margin = Math.min(policy.requestSize, policy.refillBytes);
+	return withinBytes(needs, policy.aheadBytes - margin);
+}
+/**
+* Whether the threshold is held: the download keeps it held once playing, so a download that
+* reads ahead is ready as soon as its bytes have come.
+*/
+function isReadyToResume(state) {
+	return resumeThresholdOf(state).subtract(state.held).isEmpty;
+}
+//#endregion
+export { isReadyToResume, resumeThresholdOf };