SILVER/NODEDC_MISSION_CORE
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

refactor(viewer): profile rerun loading by playback stage

Browse Source
This commit is contained in:
DCCONSTRUCTIONS
2026-08-29 17:46:07 +03:00
parent 856b61be99
commit c06b709fd7
21 changed files with 1313 additions and 609 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/control-station/src/components/RecordedFmp4Player.tsx
+218 -86
View File
@@ -29,7 +29,9 @@ export type RecordedMediaPresentationState = "loading" | "ready" | "waiting" | "
export const RECORDED_MEDIA_DURATION_TOLERANCE_SECONDS = 1;
const RECORDED_MEDIA_SOURCE_OPEN_TIMEOUT_MS = 10_000;
const RECORDED_MEDIA_TARGET_TIMEOUT_MS = 10_000;
// A valid local fragment becomes decoder-ready well below one second. Keeping
// a damaged GOP on screen for ten seconds only delays the keyframe recovery.
const RECORDED_MEDIA_TARGET_TIMEOUT_MS = 2_500;
const RECORDED_MEDIA_FRAGMENT_TIMEOUT_MS = 15_000;
const RECORDED_MEDIA_REQUIRED_AHEAD_SEGMENTS = 12;
const RECORDED_MEDIA_SEGMENTS_AHEAD = 36;
@@ -72,6 +74,39 @@ export function recordedMediaDecodeStartSequence(
return selected;
}
export function nextRecordedMediaRandomAccessSequence(
randomAccessSequences: readonly number[],
failedSequence: number,
): number | null {
if (!Number.isInteger(failedSequence) || failedSequence < 1) return null;
for (const sequence of randomAccessSequences) {
if (!Number.isInteger(sequence) || sequence < 1) return null;
if (sequence > failedSequence) return sequence;
}
return null;
}
export function recordedMediaRecoveryTargetSequence(
requestedSequence: number | null,
failedSequence: number | null,
recoverySequence: number | null,
): number | null {
if (requestedSequence === null) return null;
if (
!Number.isInteger(requestedSequence)
|| requestedSequence < 1
|| failedSequence === null
|| recoverySequence === null
|| !Number.isInteger(failedSequence)
|| !Number.isInteger(recoverySequence)
|| failedSequence < 1
|| recoverySequence <= failedSequence
) return requestedSequence;
return requestedSequence >= failedSequence && requestedSequence < recoverySequence
? recoverySequence
: requestedSequence;
}
export function recordedMediaSegmentAppendOrder(
appended: ReadonlySet<number>,
decodeStartSequence: number,
@@ -90,6 +125,32 @@ export function recordedMediaSegmentAppendOrder(
return missing;
}
/** Resolve a source-clock timestamp to the first fMP4 fragment covering it. */
export function recordedMediaSegmentSequenceAtTime(
segmentEndTimesSeconds: readonly number[],
epochStartSeconds: number,
currentSeconds: number,
): number | null {
if (
!segmentEndTimesSeconds.length ||
!Number.isFinite(epochStartSeconds) ||
!Number.isFinite(currentSeconds)
) return null;
const localSeconds = Math.max(0, currentSeconds - epochStartSeconds);
let left = 0;
let right = segmentEndTimesSeconds.length - 1;
while (left < right) {
const middle = Math.floor((left + right) / 2);
const endSeconds = segmentEndTimesSeconds[middle];
if (!Number.isFinite(endSeconds) || endSeconds <= 0) return null;
if (endSeconds + 0.001 >= localSeconds) right = middle;
else left = middle + 1;
}
const finalEndSeconds = segmentEndTimesSeconds[left];
if (!Number.isFinite(finalEndSeconds) || finalEndSeconds + 0.001 < localSeconds) return null;
return left + 1;
}
export function recordedMediaCanRollTarget(
previousSequence: number,
nextSequence: number,
@@ -151,6 +212,24 @@ export function selectRecordedMediaEpoch(
return selected && currentSeconds <= selected.timelineEndSeconds ? selected : null;
}
/**
* Keep admission bounded even when the shared Rerun clock is currently before,
* between, or after camera epochs. Presentation still reports `waiting`; this
* selector only chooses the nearest epoch whose first/last fragment can prove
* that the camera transport is usable without downloading the whole MP4.
*/
export function selectRecordedMediaPreparationEpoch(
epochs: readonly ObservationRecordedMediaEpoch[],
currentSeconds: number,
): ObservationRecordedMediaEpoch | null {
if (!epochs.length || !Number.isFinite(currentSeconds)) return null;
const active = selectRecordedMediaEpoch(epochs, currentSeconds);
if (active) return active;
return epochs.find((epoch) => epoch.timelineStartSeconds > currentSeconds)
?? epochs.at(-1)
?? null;
}
export function recordedMediaSeekableCoverage(
durationSeconds: number,
seekableEndSeconds: number,
@@ -231,29 +310,14 @@ export async function fetchRecordedMediaArchive(
return { manifest, byteLength: totalBytes };
}
function videoHasSeekableArchive(
function waitForRecordedVideoInitialFrame(
video: HTMLVideoElement,
declaredDurationSeconds: number,
): boolean {
if (video.readyState < 1 || video.seekable.length < 1) return false;
return recordedMediaSeekableCoverage(
video.duration,
video.seekable.end(video.seekable.length - 1),
declaredDurationSeconds,
RECORDED_MEDIA_DURATION_TOLERANCE_SECONDS,
video.seekable.start(0),
);
}
function waitForSeekableArchive(
video: HTMLVideoElement,
declaredDurationSeconds: number,
signal: AbortSignal,
): Promise<void> {
if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
if (videoHasSeekableArchive(video, declaredDurationSeconds)) return Promise.resolve();
if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) return Promise.resolve();
return new Promise((resolve, reject) => {
const events = ["loadedmetadata", "durationchange", "progress", "canplay"] as const;
const events = ["loadeddata", "canplay", "progress"] as const;
let stallTimer: ReturnType<typeof globalThis.setTimeout> | undefined;
const armStallTimer = () => {
if (stallTimer !== undefined) globalThis.clearTimeout(stallTimer);
@@ -270,7 +334,7 @@ function waitForSeekableArchive(
};
const onProgress = () => {
armStallTimer();
if (!videoHasSeekableArchive(video, declaredDurationSeconds)) return;
if (video.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) return;
cleanup();
resolve();
};
@@ -313,11 +377,7 @@ async function mountRecordedEpochStream(
};
video.load();
try {
await waitForSeekableArchive(
video,
descriptor.timelineEndSeconds - descriptor.timelineStartSeconds,
signal,
);
await waitForRecordedVideoInitialFrame(video, signal);
return cleanup;
} catch (error) {
cleanup();
@@ -336,6 +396,11 @@ interface RecordedSegmentTarget {
resetAttempts: number;
}
interface RecordedSegmentRecovery {
readonly failedSequence: number;
readonly recoverySequence: number;
}
interface RecordedSegmentStreamRuntime {
readonly generation: string;
readonly mediaSource: MediaSource;
@@ -768,12 +833,16 @@ export function RecordedFmp4Player({
);
const [archive, setArchive] = useState<RecordedMediaArchive | null>(null);
const [state, setState] = useState<"loading" | "ready" | "error">("loading");
const [errorMessage, setErrorMessage] = useState<string | null>(null);
const [readyGeneration, setReadyGeneration] = useState<string | null>(null);
const [bufferRevision, setBufferRevision] = useState(0);
const [segmentRecoveryGeneration, setSegmentRecoveryGeneration] = useState(0);
const [segmentRecovery, setSegmentRecovery] = useState<RecordedSegmentRecovery | null>(null);
const segmentedRuntimeRef = useRef<RecordedSegmentStreamRuntime | null>(null);
const [segmentedRuntimeGeneration, setSegmentedRuntimeGeneration] = useState<string | null>(null);
const targetRevisionRef = useRef(0);
const targetReadyAbortRef = useRef<AbortController | null>(null);
const lastSegmentRecoveryRef = useRef<string | null>(null);
const playAttemptRevisionRef = useRef(0);
const currentSeconds = playback?.currentSeconds ?? contract?.timelineStartSeconds ?? 0;
const playbackPlayingRef = useRef(Boolean(playback?.playing));
@@ -781,25 +850,60 @@ export function RecordedFmp4Player({
const playbackRate = playback?.rate && Number.isFinite(playback.rate)
? Math.min(4, Math.max(0.25, playback.rate))
: 1;
const epoch = useMemo(
const presentationEpoch = useMemo(
() => selectRecordedMediaEpoch(archive?.manifest.epochs ?? [], currentSeconds),
[archive?.manifest.epochs, currentSeconds],
);
const epoch = useMemo(
() => selectRecordedMediaPreparationEpoch(
archive?.manifest.epochs ?? [],
currentSeconds,
),
[archive?.manifest.epochs, currentSeconds],
);
const segmentClockSeconds = epoch
? Math.min(
Math.max(currentSeconds, epoch.timelineStartSeconds),
epoch.timelineEndSeconds,
)
: currentSeconds;
const effectiveSegmentCount = segmentCount ?? epoch?.segmentCount ?? null;
const requestedSegmentSequence = segmentSequence ?? (epoch
? recordedMediaSegmentSequenceAtTime(
epoch.segmentEndTimesSeconds,
epoch.timelineStartSeconds,
segmentClockSeconds,
)
: null);
const effectiveSegmentSequence = recordedMediaRecoveryTargetSequence(
requestedSegmentSequence,
segmentRecovery?.failedSequence ?? null,
segmentRecovery?.recoverySequence ?? null,
);
const holdingForSegmentRecovery = Boolean(
segmentRecovery
&& requestedSegmentSequence !== null
&& effectiveSegmentSequence !== requestedSegmentSequence,
);
const segmented = Boolean(
segmentCount !== null
&& Number.isInteger(segmentCount)
&& segmentCount >= 1
requestedSegmentSequence !== null
&& Number.isInteger(requestedSegmentSequence)
&& requestedSegmentSequence >= 1
&&
effectiveSegmentCount !== null
&& Number.isInteger(effectiveSegmentCount)
&& effectiveSegmentCount >= 1
&& typeof MediaSource !== "undefined"
&& epoch
&& epoch.segmentCount === segmentCount
&& epoch.segmentCount === effectiveSegmentCount
&& epoch.randomAccessSequences.length > 0
&& epoch.segmentEndTimesSeconds.length === segmentCount
&& epoch.segmentEndTimesSeconds.length === effectiveSegmentCount
&& MediaSource.isTypeSupported(epoch.mediaType),
);
const directPlaybackSeconds = segmented ? null : currentSeconds;
const waitingForEpoch = Boolean(archive && !epoch);
const selectedGeneration = contract && epoch
? `${contract.manifestGenerationSha256}:${epoch.ordinal}:${epoch.timelineStartSeconds}:${epoch.timelineEndSeconds}`
const waitingForEpoch = Boolean(archive && !presentationEpoch);
const selectedGeneration = contract && presentationEpoch
? `${contract.manifestGenerationSha256}:${presentationEpoch.ordinal}:${presentationEpoch.timelineStartSeconds}:${presentationEpoch.timelineEndSeconds}`
: null;
const visualState = recordedMediaPresentationState(
state,
@@ -813,6 +917,7 @@ export function RecordedFmp4Player({
if (!contract) {
setArchive(null);
setReadyGeneration(null);
setErrorMessage("Некорректный descriptor записанной камеры.");
setState("error");
reportAdmission({
phase: "error",
@@ -825,6 +930,9 @@ export function RecordedFmp4Player({
const abort = new AbortController();
setArchive(null);
setReadyGeneration(null);
setSegmentRecovery(null);
lastSegmentRecoveryRef.current = null;
setErrorMessage(null);
setState("loading");
reportAdmission({
phase: "loading",
@@ -842,6 +950,7 @@ export function RecordedFmp4Player({
}
setArchive(null);
setReadyGeneration(null);
setErrorMessage("Архив записанной камеры не прошёл проверку.");
setState("error");
reportAdmission({
phase: "error",
@@ -853,43 +962,14 @@ export function RecordedFmp4Player({
}, [admissionKey, contract, prepare]);
useEffect(() => {
if (!archive || !contract || !prepare || segmented) return;
const abort = new AbortController();
let disposed = false;
void (async () => {
for (const candidate of archive.manifest.epochs) {
const probe = document.createElement("video");
probe.muted = true;
probe.playsInline = true;
const cleanup = await mountRecordedEpochStream(probe, candidate, abort.signal);
cleanup();
if (disposed || abort.signal.aborted) return;
}
if (disposed || abort.signal.aborted) return;
reportAdmission({
phase: "ready",
byteLength: archive.byteLength,
message: null,
});
})().catch((error: unknown) => {
if (
disposed ||
abort.signal.aborted ||
(error instanceof DOMException && error.name === "AbortError")
) return;
setReadyGeneration(null);
setState("error");
reportAdmission({
phase: "error",
byteLength: archive.byteLength,
message: "Не все codec epoch записанной камеры декодируются и доступны для seek.",
});
});
return () => {
disposed = true;
abort.abort();
};
}, [admissionKey, archive, contract, prepare, segmented]);
if (!segmentRecovery || requestedSegmentSequence === null) return;
if (
requestedSegmentSequence >= segmentRecovery.failedSequence
&& requestedSegmentSequence < segmentRecovery.recoverySequence
) return;
lastSegmentRecoveryRef.current = null;
setSegmentRecovery(null);
}, [requestedSegmentSequence, segmentRecovery]);
useEffect(() => {
const video = videoRef.current;
@@ -910,6 +990,7 @@ export function RecordedFmp4Player({
setReadyGeneration(null);
setSegmentedRuntimeGeneration(null);
setErrorMessage(null);
setState("loading");
video.pause();
const sourceOpened = waitForMediaSourceOpen(mediaSource, abort.signal);
@@ -957,6 +1038,7 @@ export function RecordedFmp4Player({
return;
}
setReadyGeneration(null);
setErrorMessage("Покадровый буфер записанной камеры не открылся.");
setState("error");
reportAdmission({
phase: "error",
@@ -982,7 +1064,14 @@ export function RecordedFmp4Player({
}
URL.revokeObjectURL(objectUrl);
};
}, [archive, contract, epoch, segmentCount, segmented]);
}, [
archive,
contract,
effectiveSegmentCount,
epoch,
segmented,
segmentRecoveryGeneration,
]);
useEffect(() => {
const runtime = segmentedRuntimeRef.current;
@@ -993,18 +1082,19 @@ export function RecordedFmp4Player({
|| !archive
|| !segmented
|| segmentedRuntimeGeneration !== runtime.generation
|| segmentSequence === null
|| !Number.isInteger(segmentSequence)
|| segmentSequence < 1
|| segmentSequence > runtime.segmentCount
|| effectiveSegmentSequence === null
|| !Number.isInteger(effectiveSegmentSequence)
|| effectiveSegmentSequence < 1
|| effectiveSegmentSequence > runtime.segmentCount
) return;
const archiveByteLength = archive.byteLength;
const decodeStart = recordedMediaDecodeStartSequence(
runtime.randomAccessSequences,
segmentSequence,
effectiveSegmentSequence,
);
if (decodeStart === null) {
setReadyGeneration(null);
setErrorMessage("Для кадра записанной камеры нет random-access фрагмента.");
setState("error");
reportAdmission({
phase: "error",
@@ -1015,10 +1105,11 @@ export function RecordedFmp4Player({
}
const targetSeconds = recordedSegmentStartSeconds(
runtime.segmentEndTimesSeconds,
segmentSequence,
effectiveSegmentSequence,
);
if (targetSeconds === null) {
setReadyGeneration(null);
setErrorMessage("Для кадра записанной камеры нет точной media timestamp.");
setState("error");
reportAdmission({
phase: "error",
@@ -1030,15 +1121,15 @@ export function RecordedFmp4Player({
const previousTarget = runtime.target;
const readyEnd = Math.min(
runtime.segmentCount,
segmentSequence + RECORDED_MEDIA_REQUIRED_AHEAD_SEGMENTS,
effectiveSegmentSequence + RECORDED_MEDIA_REQUIRED_AHEAD_SEGMENTS,
);
const desiredEnd = Math.min(
runtime.segmentCount,
segmentSequence + RECORDED_MEDIA_SEGMENTS_AHEAD,
effectiveSegmentSequence + RECORDED_MEDIA_SEGMENTS_AHEAD,
);
const candidateTarget: RecordedSegmentTarget = {
revision: previousTarget?.revision ?? 0,
sequence: segmentSequence,
sequence: effectiveSegmentSequence,
decodeStart,
readyEnd,
desiredEnd,
@@ -1046,6 +1137,24 @@ export function RecordedFmp4Player({
forceReset: false,
resetAttempts: 0,
};
const recoverFromSegmentFailure = (failedSequence: number): boolean => {
const recoverySequence = nextRecordedMediaRandomAccessSequence(
runtime.randomAccessSequences,
failedSequence,
);
if (recoverySequence === null) return false;
const recoveryToken = `${runtime.generation}:${failedSequence}:${recoverySequence}`;
if (lastSegmentRecoveryRef.current === recoveryToken) return true;
lastSegmentRecoveryRef.current = recoveryToken;
setReadyGeneration(null);
setSegmentRecovery({ failedSequence, recoverySequence });
setErrorMessage(
`Восстанавливаем камеру с ключевого кадра ${recoverySequence}.`,
);
setState("loading");
setSegmentRecoveryGeneration((generation) => generation + 1);
return true;
};
const rollingTarget = Boolean(previousTarget && recordedMediaCanRollTarget(
previousTarget.sequence,
candidateTarget.sequence,
@@ -1059,12 +1168,19 @@ export function RecordedFmp4Player({
|| runtime.abort.signal.aborted
|| (error instanceof DOMException && error.name === "AbortError")
) return;
const failedSequence = runtime.target?.sequence ?? effectiveSegmentSequence;
if (failedSequence !== null && recoverFromSegmentFailure(failedSequence)) return;
const detail = error instanceof Error && error.message
? `: ${error.message}`
: ".";
const message = `Покадровый фрагмент записанной камеры недоступен${detail}`;
setReadyGeneration(null);
setErrorMessage(message);
setState("error");
reportAdmission({
phase: "error",
byteLength: archiveByteLength,
message: "Покадровый фрагмент записанной камеры недоступен.",
message,
});
};
if (rollingTarget && previousTarget) {
@@ -1128,6 +1244,7 @@ export function RecordedFmp4Player({
setBufferRevision((revision) => revision + 1);
runtime.hasPresentedFrame = true;
setReadyGeneration(runtime.generation);
setErrorMessage(null);
setState("ready");
reportAdmission({
phase: "ready",
@@ -1139,7 +1256,9 @@ export function RecordedFmp4Player({
targetReadyAbort.signal.aborted
|| (error instanceof DOMException && error.name === "AbortError")
) return;
if (recoverFromSegmentFailure(bufferedTarget.sequence)) return;
setReadyGeneration(null);
setErrorMessage("Кадр записанной камеры не стал decoder-ready.");
setState("error");
reportAdmission({
phase: "error",
@@ -1160,7 +1279,7 @@ export function RecordedFmp4Player({
if (targetReadyAbortRef.current === targetReadyAbort) targetReadyAbortRef.current = null;
if (runtime.onTargetBuffered === markBuffered) runtime.onTargetBuffered = null;
};
}, [archive?.byteLength, segmentSequence, segmented, segmentedRuntimeGeneration]);
}, [archive?.byteLength, effectiveSegmentSequence, segmented, segmentedRuntimeGeneration]);
useEffect(() => {
const video = videoRef.current;
@@ -1170,6 +1289,7 @@ export function RecordedFmp4Player({
? `${contract.manifestGenerationSha256}:${epochDescriptor.ordinal}:${epochDescriptor.timelineStartSeconds}:${epochDescriptor.timelineEndSeconds}`
: null;
setReadyGeneration(null);
setErrorMessage(null);
setState("loading");
const abort = new AbortController();
let disposed = false;
@@ -1185,7 +1305,13 @@ export function RecordedFmp4Player({
}
setBufferRevision((revision) => revision + 1);
setReadyGeneration(generation);
setErrorMessage(null);
setState("ready");
reportAdmission({
phase: "ready",
byteLength: archive?.byteLength ?? null,
message: null,
});
} catch (error) {
if (
disposed ||
@@ -1195,11 +1321,12 @@ export function RecordedFmp4Player({
return;
}
setReadyGeneration(null);
setErrorMessage("Записанная камера не открыла первый декодируемый кадр.");
setState("error");
reportAdmission({
phase: "error",
byteLength: archive?.byteLength ?? null,
message: "Записанная камера не стала seekable.",
message: "Записанная камера не открыла первый декодируемый кадр.",
});
}
};
@@ -1234,6 +1361,7 @@ export function RecordedFmp4Player({
video.currentTime = target;
} catch {
setReadyGeneration(null);
setErrorMessage("Seek записанной камеры завершился ошибкой.");
setState("error");
reportAdmission({
phase: "error",
@@ -1244,11 +1372,12 @@ export function RecordedFmp4Player({
}
}
video.playbackRate = playbackRate;
if (playback?.playing) {
if (playback?.playing && !holdingForSegmentRecovery) {
void video.play().catch(() => {
if (playAttemptRevisionRef.current !== playAttemptRevision) return;
onPlayingRejectedRef.current?.();
setReadyGeneration(null);
setErrorMessage("Запуск записанной камеры отклонён браузером.");
setState("error");
reportAdmission({
phase: "error",
@@ -1264,6 +1393,7 @@ export function RecordedFmp4Player({
bufferRevision,
directPlaybackSeconds,
epoch,
holdingForSegmentRecovery,
playback?.playing,
playbackRate,
segmented,
@@ -1327,7 +1457,9 @@ export function RecordedFmp4Player({
{visualState === "waiting"
? "Камера на этой позиции ещё не записывалась"
: visualState === "error"
? "Записанное видео недоступно"
? errorMessage ?? "Записанное видео недоступно"
: errorMessage
? errorMessage
: archive
? "Проверяем seek и codec записанного видео…"
: "Читаем manifest записанного видео…"}
apps/control-station/src/components/RerunViewport.tsx
+119 -452
View File
@@ -11,10 +11,18 @@ import {
LIVE_RECEIVER_OPEN_CHECK_INTERVAL_MS,
requestLiveReceiverRecovery,
} from "../core/observation/liveReceiverWatchdog";
import {
claimExclusiveLiveViewer,
createReentrantViewerDisposer,
isLiveRerunPresentationReady,
liveRerunReceiverBindingIdentity,
liveTimelineNeedsSynchronization,
} from "../core/observation/liveRerunLifecycle";
import {
createLiveViewerDiagnosticLifecycle,
createLiveViewerInstanceId,
createLiveViewerLineage,
reloadRecordedViewerAfterStaleModuleFailure,
subscribeToLiveViewerBuildFence,
type LiveViewerFailureStage,
} from "../core/observation/liveViewerDiagnostics";
@@ -22,10 +30,63 @@ import {
fetchPerceptionPreparationStatus,
perceptionPreparationMessage,
} from "../core/observation/perceptionPreparation";
import type { RecordedAdmissionPhase } from "../core/observation/recordedSessionAdmission";
import {
RECORDED_BASE_POINT_COLOR_KEY,
canPublishRecordedPlaybackController,
createRecordedAutoplayGate,
createRecordedOpenWatchdog,
} from "../core/observation/recordedRerunLifecycle";
import type {
RecordedPerceptionLayers,
RecordedRerunView,
RecordedRrdArtifactDescriptor,
RerunPlaybackController,
RerunPlaybackState,
RerunViewerProfile,
RerunViewportStatus,
} from "../core/observation/viewerProfile";
export type {
RecordedPerceptionLayers,
RecordedRerunView,
RecordedRrdArtifactDescriptor,
RerunPlaybackController,
RerunPlaybackState,
RerunViewerProfile,
RerunViewportStatus,
} from "../core/observation/viewerProfile";
export {
attemptRecordedAutoplay,
canPublishRecordedPlaybackController,
createRecordedAutoplayGate,
createRecordedOpenWatchdog,
isRecordedPlaybackFullyBuffered,
isRecordedPlaybackPresentationReady,
isRecordedPlaybackReady,
isUsableRecordedPlaybackRange,
recordedOpenWatchdogTimeoutMs,
recordedPlaybackBufferState,
recordedPlaybackRangeWhenReady,
recordedPointColorKey,
rerunPresentationStatus,
type RecordedPlaybackBufferState,
} from "../core/observation/recordedRerunLifecycle";
export {
claimExclusiveLiveViewer,
createReentrantViewerDisposer,
isLiveRerunPresentationReady,
liveRerunReceiverBindingIdentity,
liveTimelineNeedsSynchronization,
} from "../core/observation/liveRerunLifecycle";
import {
isRecordedPlaybackReady,
recordedPlaybackBufferState,
recordedPlaybackRangeWhenReady,
recordedPointColorKey,
rerunPresentationStatus,
} from "../core/observation/recordedRerunLifecycle";
export type RerunViewportStatus = "idle" | "loading" | "ready" | "error";
export type RecordedRerunView = "spatial" | "perception" | "perception3d" | "metrics";
export type RecordedPerceptionLoadPhase =
| "idle"
| "loading"
@@ -46,55 +107,14 @@ export type RecordedPointColorLoadState = Pick<
"phase" | "receivedBytes" | "totalBytes" | "progress" | "message"
>;
export interface RecordedPerceptionLayers {
enabled: boolean;
detections2d: boolean;
segmentation: boolean;
cuboids3d: boolean;
}
export interface RerunSelection {
entityPath: string;
viewName?: string;
position?: [number, number, number];
}
export interface RerunPlaybackState {
recordingId: string;
timeline: string;
rangeNs: { min: number; max: number } | null;
currentNs: number;
playing: boolean;
/** Latest session-time value currently available to the browser receiver. */
bufferedEndNs: number | null;
/** Declared first session-time value, when the archive descriptor provides it. */
expectedStartNs: number | null;
/** Declared final session-time value, when the archive descriptor provides it. */
expectedEndNs: number | null;
/** Download progress in the closed interval 0..1, or null without a valid expectation. */
bufferProgress: number | null;
/** True only when the buffered range has reached the declared archive end. */
fullyBuffered: boolean;
}
export interface RerunPlaybackController {
seek: (timeNs: number) => void;
setPlaying: (playing: boolean) => void;
jumpToEnd: () => void;
}
export interface RerunViewportProps {
sourceUrl: string;
recordedArtifact?: RecordedRrdArtifactDescriptor | null;
followLive?: boolean;
liveActivitySequence?: number | null;
liveStreamId?: string | null;
liveRecoveryAuthorityIdentity?: string | null;
autoplayWhenReady?: boolean;
presentationGate?: RecordedAdmissionPhase;
expectedTimelineStartSeconds?: number;
expectedTimelineEndSeconds?: number;
initialPlaybackStartSeconds?: number;
profile: RerunViewerProfile;
onStatusChange?: (status: RerunViewportStatus, message?: string) => void;
onSelectionChange?: (selection: RerunSelection | null) => void;
onPlaybackChange?: (state: RerunPlaybackState | null) => void;
@@ -110,23 +130,10 @@ export interface RerunViewportProps {
| "palette"
| "customColor"
>;
recordedView?: RecordedRerunView;
recordedViewResetGeneration?: 0 | 1;
recordedFollowTrajectory?: boolean;
recordedPerceptionLayers?: RecordedPerceptionLayers;
recordedPerceptionRetryGeneration?: number;
lockPerceptionCameraInteraction?: boolean;
onPerceptionLoadChange?: (state: RecordedPerceptionLoadState) => void;
onPointColorLoadChange?: (state: RecordedPointColorLoadState) => void;
}
export interface RecordedRrdArtifactDescriptor {
sourceUrl: string;
viewerSourceUrl: string;
byteLength: number;
sha256: string;
}
interface RerunBlueprintChannel {
endpointUrl: string;
channel: {
@@ -147,375 +154,6 @@ const RECORDED_PERCEPTION_PATH = /^\/api\/v1\/observation-sessions\/[A-Za-z0-9][
const RECORDED_POINT_COLORS_PATH = /^\/api\/v1\/observation-sessions\/[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\/point-colors\.rrd$/;
const MAX_BLUEPRINT_BYTES = 1_048_576;
const MAX_PERCEPTION_BYTES = 512 * 1024 * 1024;
const BUFFER_END_TOLERANCE_NS = 1_000_000;
const RECORDED_OPEN_MIN_TIMEOUT_MS = 120_000;
const RECORDED_OPEN_MAX_TIMEOUT_MS = 1_800_000;
const RECORDED_OPEN_GRACE_MS = 30_000;
const RECORDED_OPEN_MIN_BYTES_PER_SECOND = 2 * 1024 * 1024;
const RECORDED_BASE_POINT_COLOR_KEY = "intensity|turbo|-";
export function recordedPointColorKey(
settings: Pick<SceneSettings, "colorMode" | "palette" | "customColor">,
): string {
const custom = settings.palette === "custom" || settings.colorMode === "class"
? settings.customColor.toLowerCase()
: "-";
return `${settings.colorMode}|${settings.palette}|${custom}`;
}
export function recordedOpenWatchdogTimeoutMs(byteLength: number): number {
if (!Number.isSafeInteger(byteLength) || byteLength < 4) {
throw new Error("Unsafe recorded RRD byte length");
}
const transferBudgetMs = Math.ceil(
(byteLength / RECORDED_OPEN_MIN_BYTES_PER_SECOND) * 1_000,
);
return Math.min(
RECORDED_OPEN_MAX_TIMEOUT_MS,
Math.max(RECORDED_OPEN_MIN_TIMEOUT_MS, transferBudgetMs + RECORDED_OPEN_GRACE_MS),
);
}
export function createRecordedOpenWatchdog<T>({
byteLength,
schedule,
cancel,
onTimeout,
}: {
byteLength: number;
schedule: (callback: () => void, timeoutMs: number) => T;
cancel: (handle: T) => void;
onTimeout: () => void;
}): { arm: () => void; clear: () => void; pending: () => boolean } {
const timeoutMs = recordedOpenWatchdogTimeoutMs(byteLength);
let handle: T | null = null;
return {
arm() {
if (handle !== null) return;
handle = schedule(() => {
handle = null;
onTimeout();
}, timeoutMs);
},
clear() {
if (handle === null) return;
cancel(handle);
handle = null;
},
pending: () => handle !== null,
};
}
export function createReentrantViewerDisposer(
cleanupOnce: () => void,
releaseNativeViewer: () => void,
): () => void {
let cleanupComplete = false;
return () => {
try {
if (!cleanupComplete) {
cleanupComplete = true;
cleanupOnce();
}
} finally {
// `viewer.start()` can resolve after an earlier pre-ready stop. Reapply
// native release on every disposal boundary so that a stale viewer can
// never reopen after React and diagnostics have already unmounted it.
releaseNativeViewer();
}
};
}
interface ActiveLiveViewerOwner {
release: () => void;
}
let activeLiveViewerOwner: ActiveLiveViewerOwner | null = null;
/**
* Own exactly one native live receiver per application document.
*
* React route/StrictMode transitions can overlap two mounted workspaces for a
* render turn. Rerun keeps each native gRPC receiver alive independently, so
* the overlap used to consume the bounded live replay slots and leave the
* operator's visible canvas black. Claiming the next owner synchronously
* retires the previous native receiver before the next one starts.
*/
export function claimExclusiveLiveViewer(release: () => void): () => void {
const owner = { release };
const previous = activeLiveViewerOwner;
activeLiveViewerOwner = owner;
previous?.release();
return () => {
if (activeLiveViewerOwner === owner) activeLiveViewerOwner = null;
};
}
export interface RecordedPlaybackBufferState {
bufferedEndNs: number | null;
expectedStartNs: number | null;
expectedEndNs: number | null;
bufferProgress: number | null;
fullyBuffered: boolean;
}
/**
* A Rerun time range is usable as soon as it contains one finite timestamp.
* A first frame commonly has min === max; waiting for positive duration would
* needlessly keep that visible frame behind the loading screen.
*/
export function isUsableRecordedPlaybackRange(
rangeNs: { min: number; max: number } | null,
): rangeNs is { min: number; max: number } {
return Boolean(
rangeNs &&
Number.isFinite(rangeNs.min) &&
Number.isFinite(rangeNs.max) &&
rangeNs.max >= rangeNs.min,
);
}
/**
* A live receiver is presentable only after the exact browser store exposes
* real timeline data that the backend has also confirmed publishing.
* `WebViewer.start()` and a non-null active recording id are transport setup,
* not evidence that the spatial scene can render.
*/
export function isLiveRerunPresentationReady(
viewerStarted: boolean,
rangeNs: { min: number; max: number } | null,
backendActivitySequence: number | null,
): boolean {
return viewerStarted &&
Number.isSafeInteger(backendActivitySequence) &&
(backendActivitySequence ?? 0) > 0 &&
isUsableRecordedPlaybackRange(rangeNs);
}
/**
* `recording_open` can arrive before Rerun has registered the live timeline.
* Selecting it at that point is a silent no-op, so keep retrying only until
* the exact live timeline is both available and active.
*/
export function liveTimelineNeedsSynchronization(
followLive: boolean,
activeTimeline: string | null | undefined,
rangeNs: { min: number; max: number } | null,
): boolean {
return followLive &&
isUsableRecordedPlaybackRange(rangeNs) &&
activeTimeline !== "stream_time";
}
/**
* Key the native receiver to its data-plane binding. Recovery authority is a
* retry fence projected from changing supervisor snapshots; it must not tear
* down a healthy WebViewer while this acquisition and URL remain unchanged.
*/
export function liveRerunReceiverBindingIdentity(
sourceUrl: string,
liveStreamId: string | null,
followLive: boolean,
): string {
return JSON.stringify([
followLive ? "live" : "recorded",
sourceUrl.trim(),
followLive ? liveStreamId?.trim() ?? "" : "",
]);
}
/** Describe progressive archive availability without gating first rendering. */
export function recordedPlaybackBufferState(
rangeNs: { min: number; max: number } | null,
expectedTimelineEndSeconds?: number,
expectedTimelineStartSeconds?: number,
): RecordedPlaybackBufferState {
const usableRange = isUsableRecordedPlaybackRange(rangeNs) ? rangeNs : null;
const bufferedEndNs = usableRange?.max ?? null;
if (expectedTimelineEndSeconds === undefined) {
return {
bufferedEndNs,
expectedStartNs: null,
expectedEndNs: null,
bufferProgress: null,
fullyBuffered: usableRange !== null,
};
}
if (!Number.isFinite(expectedTimelineEndSeconds) || expectedTimelineEndSeconds < 0) {
return {
bufferedEndNs,
expectedStartNs: null,
expectedEndNs: null,
bufferProgress: null,
fullyBuffered: false,
};
}
const expectedEndNs = expectedTimelineEndSeconds * 1_000_000_000;
const expectedStartNs = expectedTimelineStartSeconds === undefined
? 0
: expectedTimelineStartSeconds * 1_000_000_000;
if (
!Number.isFinite(expectedEndNs) ||
!Number.isFinite(expectedStartNs) ||
expectedStartNs < 0 ||
expectedEndNs < expectedStartNs
) {
return {
bufferedEndNs,
expectedStartNs: null,
expectedEndNs: null,
bufferProgress: null,
fullyBuffered: false,
};
}
// Rerun split preserves whole boundary chunks so that all generated splits
// still sum exactly to the source recording. A verified bounded artifact can
// therefore begin slightly before its declared operator window. Admission
// requires coverage of the declared window, not byte-chunk boundary equality.
const fullyBuffered = usableRange !== null &&
usableRange.min <= expectedStartNs + BUFFER_END_TOLERANCE_NS &&
usableRange.max >= expectedEndNs - BUFFER_END_TOLERANCE_NS;
const expectedDurationNs = expectedEndNs - expectedStartNs;
const bufferProgress = bufferedEndNs === null
? 0
: expectedDurationNs <= 0
? (fullyBuffered ? 1 : 0)
: Math.min(1, Math.max(0, (bufferedEndNs - expectedStartNs) / expectedDurationNs));
return {
bufferedEndNs,
expectedStartNs,
expectedEndNs,
bufferProgress,
fullyBuffered,
};
}
/** A recorded viewport is publishable only after its declared range is complete. */
export function isRecordedPlaybackReady(
viewerStarted: boolean,
artifactVerified: boolean,
buffer: RecordedPlaybackBufferState,
): boolean {
return viewerStarted && artifactVerified && buffer.fullyBuffered;
}
/** Keep the host scrubber and its controls disconnected from a partial archive. */
export function recordedPlaybackRangeWhenReady(
rangeNs: { min: number; max: number } | null,
buffer: RecordedPlaybackBufferState,
artifactVerified: boolean,
): { min: number; max: number } | null {
if (
!artifactVerified ||
!buffer.fullyBuffered ||
!isUsableRecordedPlaybackRange(rangeNs)
) return null;
return {
min: buffer.expectedStartNs === null
? rangeNs.min
: Math.max(rangeNs.min, buffer.expectedStartNs),
max: buffer.expectedEndNs === null
? rangeNs.max
: Math.min(rangeNs.max, buffer.expectedEndNs),
};
}
/** Do not mount host timeline controls while a recorded generation is partial. */
export function isRecordedPlaybackPresentationReady(
status: RerunViewportStatus,
playback: RerunPlaybackState | null,
): boolean {
return status === "ready" &&
playback?.fullyBuffered === true &&
isUsableRecordedPlaybackRange(playback.rangeNs);
}
export function rerunPresentationStatus(
status: RerunViewportStatus,
gate: RecordedAdmissionPhase,
recorded: boolean,
): RerunViewportStatus {
if (!recorded) return status;
if (status === "error" || gate === "error") return "error";
if (gate !== "ready") return "loading";
return status;
}
export function isRecordedPlaybackFullyBuffered(
rangeNs: { min: number; max: number } | null,
expectedTimelineEndSeconds?: number,
): boolean {
return recordedPlaybackBufferState(rangeNs, expectedTimelineEndSeconds).fullyBuffered;
}
export function attemptRecordedAutoplay(
seekToStart: () => void,
startPlaying: () => void,
): boolean {
try {
seekToStart();
startPlaying();
return true;
} catch {
return false;
}
}
/**
* Admit autoplay once, after the viewer and the complete recorded range are
* ready. The attempt is consumed even if a vendor call throws: subsequent
* polling must never seek the operator back to the beginning a second time.
*/
export function createRecordedAutoplayGate(): {
attempt: (
viewerStarted: boolean,
fullyBuffered: boolean,
presentationReady: boolean,
rangeNs: { min: number; max: number } | null,
seekToStart: (startNs: number) => void,
startPlaying: () => void,
preferredStartNs?: number,
) => boolean;
attempted: () => boolean;
} {
let consumed = false;
return {
attempt(
viewerStarted,
fullyBuffered,
presentationReady,
rangeNs,
seekToStart,
startPlaying,
preferredStartNs,
) {
if (
consumed ||
!viewerStarted ||
!fullyBuffered ||
!presentationReady ||
!isUsableRecordedPlaybackRange(rangeNs)
) return false;
consumed = true;
const startNs = Number.isFinite(preferredStartNs)
? Math.min(Math.max(preferredStartNs as number, rangeNs.min), rangeNs.max)
: rangeNs.min;
return attemptRecordedAutoplay(
() => seekToStart(startNs),
startPlaying,
);
},
attempted: () => consumed,
};
}
export function canPublishRecordedPlaybackController(
readyToRender: boolean,
presentationGate: RecordedAdmissionPhase,
): boolean {
return readyToRender && presentationGate === "ready";
}
export function createLatestAnimationFrameEmitter<T>({
emit,
@@ -917,36 +555,43 @@ export async function fetchRecordedPerceptionRrd(
}
export function RerunViewport({
sourceUrl,
recordedArtifact = null,
followLive = false,
liveActivitySequence = null,
liveStreamId = null,
liveRecoveryAuthorityIdentity = null,
autoplayWhenReady = false,
presentationGate = "ready",
expectedTimelineStartSeconds,
expectedTimelineEndSeconds,
initialPlaybackStartSeconds,
profile,
onStatusChange,
onSelectionChange,
onPlaybackChange,
onPlaybackControllerChange,
sceneSettings,
recordedView = "spatial",
recordedViewResetGeneration = 0,
recordedFollowTrajectory = false,
recordedPerceptionLayers = {
onPerceptionLoadChange,
onPointColorLoadChange,
}: RerunViewportProps) {
const recordedProfile = profile.kind === "recorded-session" ? profile : null;
const liveProfile = profile.kind === "live-acquisition" ? profile : null;
const sourceUrl = profile.sourceUrl;
const recordedArtifact = recordedProfile?.artifact ?? null;
const followLive = liveProfile !== null;
const liveActivitySequence = liveProfile?.liveActivitySequence ?? null;
const liveStreamId = liveProfile?.liveStreamId ?? null;
const liveRecoveryAuthorityIdentity =
liveProfile?.liveRecoveryAuthorityIdentity ?? null;
const autoplayWhenReady = recordedProfile?.autoplayWhenReady ?? false;
const presentationGate = recordedProfile?.presentationGate ?? "ready";
const expectedTimelineStartSeconds =
recordedProfile?.expectedTimelineStartSeconds;
const expectedTimelineEndSeconds = recordedProfile?.expectedTimelineEndSeconds;
const initialPlaybackStartSeconds = recordedProfile?.initialPlaybackStartSeconds;
const recordedView = recordedProfile?.view ?? "spatial";
const recordedViewResetGeneration = recordedProfile?.viewResetGeneration ?? 0;
const recordedFollowTrajectory = recordedProfile?.followTrajectory ?? false;
const recordedPerceptionLayers = recordedProfile?.perceptionLayers ?? {
enabled: false,
detections2d: false,
segmentation: false,
cuboids3d: false,
},
recordedPerceptionRetryGeneration = 0,
lockPerceptionCameraInteraction = false,
onPerceptionLoadChange,
onPointColorLoadChange,
}: RerunViewportProps) {
};
const recordedPerceptionRetryGeneration =
recordedProfile?.perceptionRetryGeneration ?? 0;
const lockPerceptionCameraInteraction =
recordedProfile?.lockPerceptionCameraInteraction ?? false;
const hostRef = useRef<HTMLDivElement>(null);
const [status, setStatus] = useState<RerunViewportStatus>(sourceUrl ? "loading" : "idle");
const [recordingBufferProgress, setRecordingBufferProgress] = useState<number | null>(null);
@@ -1588,7 +1233,7 @@ export function RerunViewport({
liveRecoveryRef.current = initialLiveReceiverRecoveryState();
}
if (!followLive) clearRecordedAdmissionWatchdog();
if (!followLive) setRecordingBufferProgress(1);
if (!followLive) setRecordingBufferProgress(recordedBuffer.bufferProgress);
recordedSceneAdmitted = true;
if (!followLive) onPlaybackChange?.(playbackState);
setStatus("ready");
@@ -1597,7 +1242,10 @@ export function RerunViewport({
if (
!followLive &&
!playbackControllerPublished &&
canPublishRecordedPlaybackController(readyToRender, presentationGateRef.current)
canPublishRecordedPlaybackController(
recordedBuffer.fullyBuffered,
presentationGateRef.current,
)
) {
playbackControllerPublished = true;
onPlaybackControllerChange?.(playbackController);
@@ -1740,9 +1388,16 @@ export function RerunViewport({
}
}
})
.catch(() => {
.catch(async () => {
if (disposed) return;
disposeViewer?.();
if (
isRecordedSource &&
await reloadRecordedViewerAfterStaleModuleFailure({
loadedUiBuildId: diagnosticLifecycle.lineage.uiBuildId,
signal: diagnosticLifecycle.signal,
})
) return;
if (requestLiveRecovery("module-load")) return;
reportError("Не удалось загрузить модуль визуализатора.");
});
@@ -1786,7 +1441,18 @@ export function RerunViewport({
}, [recordedPointColorsUrl]);
useEffect(() => {
if (!recordedPerceptionUrl) return;
if (!recordedPerceptionUrl || !recordedPerceptionLayers.enabled) {
if (!recordedPerceptionLayers.enabled) {
onPerceptionLoadChange?.({
phase: "idle",
receivedBytes: 0,
totalBytes: null,
progress: null,
message: "",
});
}
return;
}
const active = perceptionChannelRef.current;
const identity = recordedIdentityRef.current;
if (
@@ -1931,6 +1597,7 @@ export function RerunViewport({
}, [
onPerceptionLoadChange,
perceptionChannelRevision,
recordedPerceptionLayers.enabled,
recordedPerceptionRetryGeneration,
recordedPerceptionUrl,
]);