@bubo-squared/gyroview 0.2.0 → 0.3.0

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 };

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

@@ -0,0 +1,175 @@
+import { seconds } from "../../shared/units/time.js";
+import { ByteRange } from "../../shared/binary/ByteRange.js";
+import { ByteRangeSet } from "../../shared/binary/ByteRangeSet.js";
+import { needsOf, withinBytes } from "./trackNeeds.js";
+import { resumeThresholdOf } from "./isReadyToResume.js";
+//#region ../../packages/core/src/domain/download/planDownloads.ts
+/**
+* The download's plan, from where its readers stand (ADR 0029). The window starts at the
+* slowest picture reader, where the picture last stood once its readers closed (so the sound
+* after the last frame still comes), or at the sound where no picture was ever read; once
+* playing it reaches as far ahead as the policy's seconds and bytes allow, before that only to
+* what the readers wait for. Every picture reader's next frame is read, however far from the
+* others, so none waits for ever; a reader a seek left behind wants nothing until it follows.
+* What is wanted is asked for lowest first and in large ranges: at once when playback needs it
+* now, otherwise once a refill's worth is missing.
+*/
+function planDownloads(state) {
+	const pictures = state.cursors.filter((cursor) => isPicture(cursor));
+	const anchor = pictures.length > 0 ? anchorOf(pictures) : state.anchor;
+	const windowStart = anchor ?? soundLeadOf(state);
+	if (!windowStart) return nothingToRead(state);
+	const ahead = state.isReadingAhead ? state.policy.aheadSeconds : 0;
+	const windowEnd = seconds(windowStart.time + ahead);
+	const wanted = wantedBytes({
+		state,
+		windowStart,
+		windowEnd
+	}).bridgingGapsBelow(state.policy.bridgedGap);
+	const kept = state.transfers.filter((transfer) => transfer.remaining.length === 0 || wanted.overlaps(transfer.remaining));
+	const coming = ByteRangeSet.of(kept.map((transfer) => transfer.remaining));
+	const missing = wanted.subtract(state.held).subtract(coming).subtract(state.unreadable);
+	const room = state.policy.requestsInFlight - kept.length;
+	return {
+		start: isTopUpDue({
+			state,
+			windowStart,
+			windowEnd,
+			missing,
+			threshold: thresholdOf(state, windowStart)
+		}) ? requestsFor(missing, state.policy, room) : [],
+		cancel: state.transfers.filter((transfer) => !kept.includes(transfer)).map((transfer) => transfer.id),
+		release: state.held.subtract(wanted.union(keptBehind(windowStart, state.policy))),
+		anchor
+	};
+}
+/**
+* Where the window starts once playing where no picture was ever read: at the sound, which then
+* has no picture to follow, and follows it as it moves on.
+*/
+function soundLeadOf(state) {
+	return state.isReadingAhead && state.cursors.length > 0 ? anchorOf(state.cursors) : void 0;
+}
+function nothingToRead(state) {
+	return {
+		start: [],
+		cancel: state.transfers.map((transfer) => transfer.id),
+		release: ByteRangeSet.empty,
+		anchor: void 0
+	};
+}
+function anchorOf(cursors) {
+	return {
+		time: seconds(Math.min(...cursors.map((cursor) => timeOf(cursor)))),
+		offset: Math.min(...cursors.map((cursor) => offsetOf(cursor))),
+		keyframeOffset: Math.min(...cursors.map((cursor) => keyframeOffsetOf(cursor)))
+	};
+}
+/**
+* Every sample the readers following the picture will hand out within the window, clipped to
+* the bytes the policy allows ahead, nearest first; and the next sample of every picture reader
+* and of every reader waiting within the window, whatever the budget and wherever the file
+* puts it, so no reader waits for ever.
+*/
+function wantedBytes(window) {
+	const { state, windowEnd } = window;
+	const following = state.cursors.filter((cursor) => isFollowing(cursor, window));
+	const needs = following.flatMap((cursor) => needsOf(cursor, laterOf(windowEnd, cursor.target)));
+	const next = following.filter((cursor) => isNextSampleOwed(cursor, windowEnd));
+	const nextSamples = ByteRangeSet.of(next.map((cursor) => cursor.track.rangeOf(cursor.sample)));
+	return withinBytes(ByteRangeSet.of(needs), state.policy.aheadBytes).union(nextSamples);
+}
+/**
+* A reader no further behind the picture than the policy allows: the sound lags the picture
+* by the decoders' lead, and until it follows a seek it stands far behind.
+*/
+function isFollowing(cursor, window) {
+	return timeOf(cursor) >= window.windowStart.time - window.state.policy.keepBehindSeconds;
+}
+function isNextSampleOwed(cursor, windowEnd) {
+	const isWaitingWithin = cursor.isWaiting && timeOf(cursor) <= windowEnd;
+	return !isAtItsEnd(cursor) && (isPicture(cursor) || isWaitingWithin);
+}
+function laterOf(time, other) {
+	return other !== void 0 && other > time ? other : time;
+}
+function isPicture(cursor) {
+	return cursor.track.kind === "video";
+}
+/**
+* Once playing, what playback that starved would wait for, which the download keeps held; none
+* before.
+*/
+function thresholdOf(state, windowStart) {
+	const need = {
+		cursors: state.cursors,
+		time: windowStart.time,
+		policy: state.policy
+	};
+	return state.isReadingAhead ? resumeThresholdOf(need) : ByteRangeSet.empty;
+}
+/**
+* Whether to ask for what is missing now: a reader needs it at once, the resume threshold is
+* not all held, or a refill's worth is missing. The last seconds of the tracks come as the
+* threshold reaches them, however few their bytes.
+*/
+function isTopUpDue(topUp) {
+	const { state, missing, threshold } = topUp;
+	if (missing.ranges.some((range) => threshold.overlaps(range))) return true;
+	return state.cursors.some((cursor) => isNeededAtOnce(cursor, topUp) && missing.overlaps(cursor.track.rangeOf(cursor.sample))) || missing.totalLength >= state.policy.refillBytes;
+}
+/**
+* A reader waiting on a sample playback needs now: a picture's, or one due within the resume
+* seconds. Sound that buffers far ahead waits where the downloaded bytes end, and would
+* otherwise ask for a small range every time the picture moved.
+*/
+function isNeededAtOnce(cursor, topUp) {
+	if (!cursor.isWaiting || isAtItsEnd(cursor)) return false;
+	const { windowStart, state } = topUp;
+	const horizon = windowStart.time + (state.isReadingAhead ? state.policy.resumeSeconds : 0);
+	return isPicture(cursor) || timeOf(cursor) <= horizon;
+}
+/**
+* The missing ranges in order, cut to the request size, as many as there is room for.
+*/
+function requestsFor(missing, policy, room) {
+	const requests = [];
+	for (const range of missing.ranges) for (let offset = range.offset; offset < range.end && requests.length < room; offset += policy.requestSize) requests.push(ByteRange.of(offset, Math.min(policy.requestSize, range.end - offset)));
+	return requests;
+}
+/**
+* The stretch behind the picture that is kept for short seeks back: its group of pictures from
+* the key frame, or the policy's distance, whichever reaches further back.
+*/
+function keptBehind(anchor, policy) {
+	const start = keptBehindStart(anchor, policy);
+	return ByteRangeSet.of([ByteRange.of(start, anchor.offset - start)]);
+}
+function keptBehindStart(anchor, policy) {
+	return Math.max(0, Math.min(anchor.keyframeOffset, anchor.offset - policy.keepBehindBytes));
+}
+function isAtItsEnd(cursor) {
+	return cursor.sample >= cursor.track.sampleCount;
+}
+/**
+* When a picture reader stands: at its next frame, or at its track's end once it read them all.
+*/
+function timeOf(cursor) {
+	return isAtItsEnd(cursor) ? cursor.track.end : cursor.track.timestampOf(cursor.sample);
+}
+/**
+* Where the key frame before a reader's next sample lies; a sound sample is its own.
+*/
+function keyframeOffsetOf(cursor) {
+	const { track } = cursor;
+	const last = Math.min(cursor.sample, track.sampleCount - 1);
+	const keyframe = track.syncSampleAtOrBefore(last);
+	return keyframe === void 0 ? offsetOf(cursor) : track.rangeOf(keyframe).offset;
+}
+function offsetOf(cursor) {
+	const { track } = cursor;
+	if (!isAtItsEnd(cursor)) return track.rangeOf(cursor.sample).offset;
+	return track.sampleCount > 0 ? track.rangeOf(track.sampleCount - 1).end : 0;
+}
+//#endregion
+export { planDownloads };