@hraness/slopcamera 3.2.4

package/apps/desktop/cli/audio-analysis.ts

@@ -0,0 +1,252 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  AnalysisSubjectSchema,
+  type AudioAlignmentAnalysisV1,
+  type AnalysisSubject,
+  type ProjectAssetV1,
+  type ProjectPlacementV1,
+  type VideoProjectV1,
+} from "../contracts";
+import { canonicalJsonSha256, hashPlacementSync, type EnvelopeSeries } from "../core";
+import { CliError } from "./errors";
+import type { ProcessRunner } from "./io";
+import { ensurePrivateDirectory } from "./paths";
+import { resolveVerifiedProjectMedia } from "./project-media-integrity";
+
+const ALIGNMENT_SAMPLE_RATE_HZ = 8_000;
+const ALIGNMENT_HOP_SAMPLES = 400;
+const MAXIMUM_PCM_BYTES = 32 * 1024 * 1024 * 1024;
+
+function parseSubjectReference(reference: string): { readonly assetId: string; readonly streamId: string } {
+  const separator = reference.indexOf(":");
+  if (separator <= 0 || separator === reference.length - 1 || reference.indexOf(":", separator + 1) !== -1) {
+    throw new CliError("usage", `Media stream must use <asset-id>:<stream-id>: ${reference}`);
+  }
+  return { assetId: reference.slice(0, separator), streamId: reference.slice(separator + 1) };
+}
+
+export function resolveAudioAnalysisSubject(
+  project: VideoProjectV1,
+  reference: string,
+): { readonly asset: ProjectAssetV1; readonly stream: Extract<ProjectAssetV1["streams"][number], { readonly kind: "audio" }>; readonly subject: AnalysisSubject } {
+  const selected = parseSubjectReference(reference);
+  const asset = project.assets.find(candidate => candidate.assetId === selected.assetId);
+  if (asset === undefined) throw new CliError("not-found", `Unknown project asset: ${selected.assetId}`);
+  const stream = asset.streams.find(candidate => candidate.streamId === selected.streamId);
+  if (stream?.kind !== "audio") throw new CliError("not-found", `Unknown audio stream on ${selected.assetId}: ${selected.streamId}`);
+  const subject = AnalysisSubjectSchema.parse({
+    assetId: asset.assetId,
+    integritySha256: canonicalJsonSha256({ assetDurationUs: asset.durationUs, stream }),
+    streamId: stream.streamId,
+  });
+  return { asset, stream, subject };
+}
+
+export function alignmentInputDigest(input: {
+  readonly config: AudioAlignmentAnalysisV1["config"];
+  readonly reference: AnalysisSubject;
+  readonly referencePlacement: ProjectPlacementV1;
+  readonly target: AnalysisSubject;
+  readonly targetPlacement: ProjectPlacementV1;
+}): string {
+  return canonicalJsonSha256({
+    config: input.config,
+    reference: input.reference,
+    referencePlacement: {
+      assetId: input.referencePlacement.assetId,
+      assetRange: input.referencePlacement.assetRange,
+      placementId: input.referencePlacement.placementId,
+      syncMapSha256: hashPlacementSync(input.referencePlacement),
+    },
+    target: input.target,
+    targetPlacement: {
+      assetId: input.targetPlacement.assetId,
+      assetRange: input.targetPlacement.assetRange,
+      placementId: input.targetPlacement.placementId,
+    },
+  });
+}
+
+function seconds(microseconds: number): string {
+  return (microseconds / 1_000_000).toFixed(6).replace(/0+$/u, "").replace(/\.$/u, "");
+}
+
+export async function decodeAlignmentPcm(
+  projectDirectory: string,
+  repositoryRoot: string,
+  ffmpeg: string,
+  runner: ProcessRunner,
+  stream: Extract<ProjectAssetV1["streams"][number], { readonly kind: "audio" }>,
+  maximumOutputBytes = MAXIMUM_PCM_BYTES,
+): Promise<string> {
+  if (!Number.isSafeInteger(maximumOutputBytes) || maximumOutputBytes < Float32Array.BYTES_PER_ELEMENT) {
+    throw new CliError("usage", "Decoded alignment PCM byte limit must be a positive safe integer.");
+  }
+  const assetDurationUs = stream.segments.at(-1)?.assetRange.endUs ?? 0;
+  const expectedSamples = Math.round(assetDurationUs * ALIGNMENT_SAMPLE_RATE_HZ / 1_000_000);
+  const expectedBytes = expectedSamples * Float32Array.BYTES_PER_ELEMENT;
+  if (!Number.isSafeInteger(expectedBytes) || expectedBytes <= 0 || expectedBytes > maximumOutputBytes) {
+    throw new CliError(
+      "invalid-data",
+      `Decoded alignment PCM would exceed its ${maximumOutputBytes}-byte resource bound.`,
+      { expectedBytes, maximumOutputBytes },
+    );
+  }
+  const cacheRoot = join(projectDirectory, "analysis", "cache");
+  await ensurePrivateDirectory(join(projectDirectory, "analysis"));
+  await ensurePrivateDirectory(cacheRoot);
+  const output = join(cacheRoot, `.alignment-${randomUUID()}.f32le`);
+  const inputArguments: string[] = [];
+  const filters: string[] = [];
+  const labels: string[] = [];
+  let priorEndUs = 0;
+  for (const [index, segment] of stream.segments.entries()) {
+    if (segment.assetRange.startUs > priorEndUs) {
+      const gap = `gap_${index}`;
+      filters.push(`anullsrc=r=${ALIGNMENT_SAMPLE_RATE_HZ}:cl=mono:d=${seconds(segment.assetRange.startUs - priorEndUs)}[${gap}]`);
+      labels.push(gap);
+    }
+    inputArguments.push("-i", await resolveVerifiedProjectMedia({
+      expected: { bytes: segment.bytes, sha256: segment.sha256 },
+      label: `Audio segment ${segment.path}:${segment.streamIndex}`,
+      path: segment.path,
+      repositoryRoot,
+    }));
+    const label = `audio_${index}`;
+    filters.push(
+      `[${index}:${segment.streamIndex}]atrim=start=${seconds(segment.fileRange.startUs)}:end=${seconds(segment.fileRange.endUs)},asetpts=PTS-STARTPTS,aresample=${ALIGNMENT_SAMPLE_RATE_HZ},aformat=sample_fmts=flt:channel_layouts=mono[${label}]`,
+    );
+    labels.push(label);
+    priorEndUs = segment.assetRange.endUs;
+  }
+  if (labels.length === 0) throw new CliError("invalid-data", `Audio stream ${stream.streamId} has no media segments.`);
+  filters.push(`${labels.map(label => `[${label}]`).join("")}concat=n=${labels.length}:v=0:a=1[decoded]`);
+  const result = await runner.run([
+    ffmpeg,
+    "-hide_banner", "-nostdin", "-y",
+    ...inputArguments,
+    "-filter_complex", filters.join(";"),
+    "-map", "[decoded]",
+    "-f", "f32le",
+    "-ac", "1",
+    "-ar", String(ALIGNMENT_SAMPLE_RATE_HZ),
+    "-t", seconds(assetDurationUs),
+    "-fs", String(maximumOutputBytes),
+    output,
+  ], { maxOutputBytes: 1_000_000 });
+  if (result.exitCode !== 0) {
+    await rm(output, { force: true });
+    throw new CliError("subprocess", `FFmpeg audio decode failed: ${result.stderr.trim().slice(-4_000) || `exit ${result.exitCode}`}`);
+  }
+  const details = await lstat(output);
+  const actualSamples = details.size / Float32Array.BYTES_PER_ELEMENT;
+  const sampleTolerance = Math.max(2, stream.segments.length * 2);
+  if (
+    !details.isFile()
+    || details.isSymbolicLink()
+    || details.size <= 0
+    || details.size > maximumOutputBytes
+    || details.size % Float32Array.BYTES_PER_ELEMENT !== 0
+    || Math.abs(actualSamples - expectedSamples) > sampleTolerance
+  ) {
+    await rm(output, { force: true });
+    throw new CliError(
+      "invalid-data",
+      "FFmpeg alignment decode produced unsafe, oversized, or incomplete PCM timeline coverage.",
+      { actualSamples, expectedSamples, sampleTolerance },
+    );
+  }
+  return output;
+}
+
+export async function readAlignmentEnvelope(path: string): Promise<EnvelopeSeries> {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const values: number[] = [];
+  const buffer = Buffer.allocUnsafe(256 * 1024);
+  let carry = Buffer.alloc(0);
+  let samplesInHop = 0;
+  let squareSum = 0;
+  let differenceSum = 0;
+  let priorSample = 0;
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const read = await handle.read(buffer, 0, buffer.length, null);
+      if (read.bytesRead === 0) break;
+      totalBytes += read.bytesRead;
+      if (totalBytes > MAXIMUM_PCM_BYTES) throw new CliError("invalid-data", "Decoded alignment PCM exceeds its 32 GiB bound.");
+      const bytes = carry.length === 0
+        ? buffer.subarray(0, read.bytesRead)
+        : Buffer.concat([carry, buffer.subarray(0, read.bytesRead)]);
+      const usable = bytes.length - bytes.length % 4;
+      for (let offset = 0; offset < usable; offset += 4) {
+        const sample = bytes.readFloatLE(offset);
+        if (!Number.isFinite(sample)) throw new CliError("invalid-data", "Decoded alignment PCM contains a non-finite sample.");
+        squareSum += sample * sample;
+        differenceSum += Math.abs(sample - priorSample);
+        priorSample = sample;
+        samplesInHop += 1;
+        if (samplesInHop === ALIGNMENT_HOP_SAMPLES) {
+          const rms = Math.sqrt(squareSum / samplesInHop);
+          values.push(rms + differenceSum / samplesInHop);
+          samplesInHop = 0;
+          squareSum = 0;
+          differenceSum = 0;
+        }
+      }
+      carry = Buffer.from(bytes.subarray(usable));
+    }
+    if (carry.length !== 0) throw new CliError("invalid-data", "Decoded alignment PCM has a partial float sample.");
+    if (samplesInHop > 0) values.push(Math.sqrt(squareSum / samplesInHop) + differenceSum / samplesInHop);
+  } finally {
+    await handle.close();
+  }
+  return {
+    hopUs: Math.round(ALIGNMENT_HOP_SAMPLES * 1_000_000 / ALIGNMENT_SAMPLE_RATE_HZ),
+    startUs: 0,
+    values,
+  };
+}
+
+export async function withAlignmentEnvelopes<T>(
+  options: {
+    readonly ffmpeg: string;
+    readonly projectDirectory: string;
+    readonly reference: Extract<ProjectAssetV1["streams"][number], { readonly kind: "audio" }>;
+    readonly repositoryRoot: string;
+    readonly runner: ProcessRunner;
+    readonly target: Extract<ProjectAssetV1["streams"][number], { readonly kind: "audio" }>;
+  },
+  callback: (reference: EnvelopeSeries, target: EnvelopeSeries) => Promise<T> | T,
+): Promise<T> {
+  const paths: string[] = [];
+  try {
+    const referencePath = await decodeAlignmentPcm(
+      options.projectDirectory,
+      options.repositoryRoot,
+      options.ffmpeg,
+      options.runner,
+      options.reference,
+    );
+    paths.push(referencePath);
+    const targetPath = await decodeAlignmentPcm(
+      options.projectDirectory,
+      options.repositoryRoot,
+      options.ffmpeg,
+      options.runner,
+      options.target,
+    );
+    paths.push(targetPath);
+    const [reference, target] = await Promise.all([
+      readAlignmentEnvelope(referencePath),
+      readAlignmentEnvelope(targetPath),
+    ]);
+    return await callback(reference, target);
+  } finally {
+    await Promise.all(paths.map(async path => await rm(path, { force: true })));
+  }
+}

package/apps/desktop/cli/bounded-map.ts

@@ -0,0 +1,39 @@
+import { CliError } from "./errors";
+
+/** Map asynchronous work with a fixed process-safe concurrency ceiling. */
+export async function mapBounded<Value, Result>(
+  values: readonly Value[],
+  concurrency: number,
+  operation: (value: Value, index: number) => Promise<Result>,
+): Promise<readonly Result[]> {
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 64) {
+    throw new CliError("invalid-data", "Bounded-map concurrency must be an integer from 1 through 64.");
+  }
+  if (values.length === 0) return [];
+
+  const results = new Array<Result>(values.length);
+  let nextIndex = 0;
+  let failed = false;
+  let firstFailure: unknown;
+  const worker = async (): Promise<void> => {
+    while (!failed) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= values.length) return;
+      try {
+        results[index] = await operation(values[index]!, index);
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          firstFailure = error;
+        }
+      }
+    }
+  };
+  await Promise.all(Array.from(
+    { length: Math.min(concurrency, values.length) },
+    async () => await worker(),
+  ));
+  if (failed) throw firstFailure;
+  return results;
+}

package/apps/desktop/cli/bundle-service.ts

@@ -0,0 +1,256 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import {
+  parseRecordingEventV1,
+  type EditPlanV1,
+  type RecordingEventV1,
+  type RecordingManifestV1,
+} from "../contracts";
+import {
+  createNodeBundleFileSystem,
+  hashEditPlan,
+  loadEditPlan,
+  loadRecordingManifest,
+  type BundleFileSystem,
+} from "../core";
+import { CliError } from "./errors";
+import { resolveSafePath } from "./paths";
+import { MAX_EVENT_QUERY_LIMIT } from "./query-limits";
+import { resolveRecordingDirectory, type RecordingDirectory } from "./recording-ref";
+
+export const CURRENT_EDIT_PLAN_PATH = "edits/current.json";
+
+export interface OpenRecording {
+  readonly directory: RecordingDirectory;
+  readonly fileSystem: BundleFileSystem;
+  readonly manifest: RecordingManifestV1;
+}
+
+function compareEventOrder(left: RecordingEventV1, right: RecordingEventV1): number {
+  return left.sourceTimeUs - right.sourceTimeUs || left.sequence - right.sequence;
+}
+
+/** Retain the earliest N events with the latest retained event at heap[0]. */
+function retainEarliestEvent(
+  heap: RecordingEventV1[],
+  event: RecordingEventV1,
+  limit: number,
+): void {
+  if (heap.length < limit) {
+    heap.push(event);
+    let index = heap.length - 1;
+    while (index > 0) {
+      const parent = Math.floor((index - 1) / 2);
+      if (compareEventOrder(heap[parent]!, heap[index]!) >= 0) break;
+      [heap[parent], heap[index]] = [heap[index]!, heap[parent]!];
+      index = parent;
+    }
+    return;
+  }
+  if (compareEventOrder(event, heap[0]!) >= 0) return;
+  heap[0] = event;
+  let index = 0;
+  for (;;) {
+    const left = index * 2 + 1;
+    if (left >= heap.length) return;
+    const right = left + 1;
+    let latest = left;
+    if (right < heap.length && compareEventOrder(heap[right]!, heap[left]!) > 0) latest = right;
+    if (compareEventOrder(heap[index]!, heap[latest]!) >= 0) return;
+    [heap[index], heap[latest]] = [heap[latest]!, heap[index]!];
+    index = latest;
+  }
+}
+
+export async function openRecording(artifactRoot: string, reference: string): Promise<OpenRecording> {
+  const directory = await resolveRecordingDirectory(artifactRoot, reference);
+  const fileSystem = createNodeBundleFileSystem(directory.path);
+  try {
+    const manifest = await loadRecordingManifest(fileSystem);
+    if (manifest.recordingId !== directory.id) {
+      throw new CliError(
+        "invalid-data",
+        `Bundle directory ${directory.id} contains manifest for ${manifest.recordingId}.`,
+      );
+    }
+    return { directory, fileSystem, manifest };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError("invalid-data", `Could not load ${directory.id}/manifest.json: ${String(error)}`);
+  }
+}
+
+export async function loadCurrentPlan(recording: OpenRecording): Promise<EditPlanV1> {
+  try {
+    return await loadEditPlan(recording.fileSystem, CURRENT_EDIT_PLAN_PATH);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new CliError(
+        "not-found",
+        `Recording ${recording.manifest.recordingId} has no edit plan. Run: slopcamera edit ${recording.manifest.recordingId} init`,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function tryLoadCurrentPlan(recording: OpenRecording): Promise<EditPlanV1 | null> {
+  try {
+    return await loadEditPlan(recording.fileSystem, CURRENT_EDIT_PLAN_PATH);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function loadRecordingEvents(
+  recording: OpenRecording,
+  options: {
+    readonly endUs?: number;
+    readonly limit?: number;
+    readonly startUs?: number;
+    readonly types?: readonly RecordingEventV1["type"][];
+  } = {},
+): Promise<readonly RecordingEventV1[]> {
+  if (
+    options.limit !== undefined
+    && (!Number.isSafeInteger(options.limit) || options.limit <= 0 || options.limit > MAX_EVENT_QUERY_LIMIT)
+  ) {
+    throw new CliError(
+      "usage",
+      `Event query limit must be a positive integer no greater than ${MAX_EVENT_QUERY_LIMIT}.`,
+    );
+  }
+  const startUs = options.startUs ?? 0;
+  const endUs = options.endUs ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(startUs) || !Number.isSafeInteger(endUs) || startUs < 0 || endUs < startUs) {
+    throw new CliError("usage", "Event query source-time bounds are invalid.");
+  }
+  const acceptedTypes = options.types === undefined ? null : new Set(options.types);
+  const events: RecordingEventV1[] = [];
+  const streams = recording.manifest.eventStreams.filter((stream) =>
+    options.types === undefined || stream.eventKinds.some((kind) => options.types!.includes(kind))
+  );
+  for (const stream of streams) {
+    const path = await resolveSafePath(recording.directory.path, stream.path);
+    const input = createReadStream(path);
+    const hash = createHash("sha256");
+    let bytes = 0;
+    input.on("data", (chunk: Buffer | string) => {
+      const data = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      bytes += data.length;
+      hash.update(data);
+    });
+    const lines = createInterface({ crlfDelay: Number.POSITIVE_INFINITY, input });
+    let lineNumber = 0;
+    let parsedCount = 0;
+    let priorSequence = -1;
+    let priorSourceTimeUs = -1;
+    try {
+      for await (const line of lines) {
+        lineNumber += 1;
+        if (line.trim() === "") continue;
+        if (Buffer.byteLength(line) > 1_048_576) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} exceeds the 1 MiB event-line bound.`);
+        }
+        let value: unknown;
+        try {
+          value = JSON.parse(line) as unknown;
+        } catch (error) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} is not valid JSON: ${String(error)}`);
+        }
+        let event: RecordingEventV1;
+        try {
+          event = parseRecordingEventV1(value);
+        } catch (error) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} is not a recording event: ${String(error)}`);
+        }
+        parsedCount += 1;
+        if (event.sequence <= priorSequence) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} does not increase event sequence.`);
+        }
+        if (event.sourceTimeUs < priorSourceTimeUs) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} moves source time backward.`);
+        }
+        if (event.sourceTimeUs < stream.startUs || event.sourceTimeUs > stream.endUs) {
+          throw new CliError("invalid-data", `${stream.path}:${lineNumber} lies outside its manifest interval.`);
+        }
+        priorSequence = event.sequence;
+        priorSourceTimeUs = event.sourceTimeUs;
+        if (event.sourceTimeUs < startUs || event.sourceTimeUs >= endUs) continue;
+        if (acceptedTypes !== null && !acceptedTypes.has(event.type)) continue;
+        if (options.limit === undefined) events.push(event);
+        else retainEarliestEvent(events, event, options.limit);
+      }
+    } catch (error) {
+      input.destroy();
+      if (error instanceof CliError) throw error;
+      throw new CliError("invalid-data", `Could not read event stream ${stream.path}: ${String(error)}`);
+    }
+    if (parsedCount !== stream.recordCount) {
+      throw new CliError(
+        "invalid-data",
+        `${stream.path} contains ${parsedCount} event(s), but its manifest declares ${stream.recordCount}.`,
+      );
+    }
+    if (stream.integrity.state === "verified") {
+      const sha256 = hash.digest("hex");
+      if (bytes !== stream.integrity.bytes || sha256 !== stream.integrity.sha256) {
+        throw new CliError("invalid-data", `Event stream integrity check failed for ${stream.path}.`);
+      }
+    }
+  }
+  return events.sort(compareEventOrder);
+}
+
+export function recordingSummary(
+  recording: OpenRecording,
+  plan: EditPlanV1 | null,
+): Readonly<Record<string, unknown>> {
+  const manifest = recording.manifest;
+  return {
+    createdAt: manifest.createdAt,
+    diagnostics: manifest.diagnostics,
+    durationUs: manifest.timeline.durationUs,
+    edit: plan === null
+      ? null
+      : {
+          cuts: Math.max(0, plan.keep.length - 1),
+          hash: hashEditPlan(plan),
+          overlays: plan.overlays.length,
+          planId: plan.planId,
+          speedRanges: plan.speed.length,
+          zooms: plan.zooms.length,
+        },
+    eventStreams: manifest.eventStreams.map((stream) => ({
+      eventKinds: stream.eventKinds,
+      eventStreamId: stream.eventStreamId,
+      path: stream.path,
+      recordCount: stream.recordCount,
+    })),
+    path: recording.directory.path,
+    recordingId: manifest.recordingId,
+    state: manifest.state,
+    tracks: manifest.tracks.map((track) => ({
+      enabled: track.enabled,
+      kind: track.kind,
+      label: track.label,
+      segmentCount: track.segments.length,
+      trackId: track.trackId,
+    })),
+    updatedAt: manifest.updatedAt,
+  };
+}
+
+export function bundleRelativePath(recording: OpenRecording, absolutePath: string): string {
+  const prefix = `${recording.directory.path}/`;
+  if (!absolutePath.startsWith(prefix)) {
+    throw new CliError("unsafe-path", `Path is outside ${recording.manifest.recordingId}: ${absolutePath}`);
+  }
+  return absolutePath.slice(prefix.length);
+}
+
+export function defaultPlanId(manifest: RecordingManifestV1): string {
+  return `plan_${manifest.recordingId.slice(4)}`;
+}