Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions packages/core/schemas/edits.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,43 @@
"additionalProperties": false
}
},
"trim": {
"type": "object",
"properties": {
"startMs": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"endMs": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"additionalProperties": false
},
"cuts": {
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"startMs": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"endMs": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["startMs", "endMs"],
"additionalProperties": false
}
},
"cards": {
"type": "object",
"properties": {
Expand Down
145 changes: 145 additions & 0 deletions packages/core/src/edits.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import {
CardTextSchema,
FrameConfigSchema,
} from './project-config.ts';
import type { RunResult } from './run-result.ts';
import { ZoomSchema } from './step.ts';
import type { Timeline } from './timeline.ts';

Expand Down Expand Up @@ -48,6 +49,47 @@ const EditedCaptionsSchema = z
}
});

const MAX_CUTS = 100;

/** The least page a trim and cuts may leave (spec 354). */
const MIN_PAGE_MS = 500;

/** A new start and a new end of the page, either optional. */
const TrimSchema = z
.strictObject({ startMs: msSchema.optional(), endMs: msSchema.optional() })
.refine(
(trim) =>
trim.startMs === undefined ||
trim.endMs === undefined ||
trim.startMs < trim.endMs,
{ message: 'expected endMs to be after startMs', path: ['endMs'] },
);

const CutSchema = z
.strictObject({ startMs: msSchema, endMs: msSchema })
.refine((cut) => cut.endMs > cut.startMs, {
message: 'expected endMs to be after startMs',
path: ['endMs'],
});

/** Ordered by `startMs`, at least 1 ms apart: two touching cuts are one cut. */
const CutsSchema = z
.array(CutSchema)
.max(MAX_CUTS)
.superRefine((cuts, ctx) => {
for (const [index, cut] of cuts.entries()) {
const previous = cuts[index - 1];
if (previous !== undefined && cut.startMs <= previous.endMs) {
ctx.addIssue({
code: 'custom',
message:
'expected cuts ordered by startMs, neither overlapping nor touching',
path: [index, 'startMs'],
});
}
}
});

/** At most one entry per step. */
const ZoomEditsSchema = z
.array(
Expand Down Expand Up @@ -84,6 +126,10 @@ export const RunEditsSchema = z.strictObject({
captions: EditedCaptionsSchema.optional(),
// A step not listed keeps its timeline `zoom`.
zoom: ZoomEditsSchema.optional(),
// Timeline ms (spec 354): the page plays from `startMs` to `endMs`, less
// every cut. The source stays as recorded.
trim: TrimSchema.optional(),
cuts: CutsSchema.optional(),
cards: z
.strictObject({
intro: z
Expand Down Expand Up @@ -121,10 +167,16 @@ export type RunEdits = z.infer<typeof RunEditsSchema>;
* step whose event has a target box (ADR-0012 §2), and no caption past the
* end of the video. `tailMs` is the end hold the renderer keeps after the
* last event and its hold (`render.endHoldMs`).
*
* The trim and the cuts (spec 354) are checked against the run's range — to
* the failed step's end on a failed run, as the renderer ends it: every cut
* inside the trimmed range, nothing hiding the failure (ADR-0004 §4,
* ADR-0020 §2), and at least 500 ms of page left.
*/
export function checkRunEdits(
edits: RunEdits,
timeline: Timeline,
result: RunResult,
{ tailMs = DEFAULT_TAIL_MS }: { tailMs?: number } = {},
): Issue[] {
const issues: Issue[] = [];
Expand Down Expand Up @@ -156,5 +208,98 @@ export function checkRunEdits(
});
}
}
issues.push(...checkTrim(edits, timeline, result, endMs));
return issues;
}

/** `passedEndMs`: where the video of a passed run ends, in timeline ms. */
function checkTrim(
{ trim, cuts = [] }: RunEdits,
timeline: Timeline,
result: RunResult,
passedEndMs: number,
): Issue[] {
if (trim === undefined && cuts.length === 0) return [];
const issues: Issue[] = [];
const failure = failureOf(result);
const failedEvent =
failure?.stepIndex === undefined
? undefined
: timeline.events.find((event) => event.stepIndex === failure.stepIndex);
const lastEvent = timeline.events.at(-1);
// The renderer's range: to the failure, or the end hold after the last event.
const runEndMs =
lastEvent === undefined
? Infinity
: failure === undefined
? passedEndMs
: (failedEvent ?? lastEvent).endMs;
const fromMs = trim?.startMs ?? 0;
const toMs = Math.min(trim?.endMs ?? Infinity, runEndMs);
for (const [index, cut] of cuts.entries()) {
if (cut.startMs < fromMs || cut.endMs > toMs) {
issues.push({
path: `cuts[${index}]`,
code: 'cut-outside-trim',
message: `expected the cut inside the page, ${fromMs}–${toMs} ms`,
});
}
}
if (failedEvent !== undefined) {
if (trim?.endMs !== undefined && trim.endMs < failedEvent.endMs) {
issues.push({
path: 'trim.endMs',
code: 'trim-hides-failure',
message: `expected the trim to end at or after ${failedEvent.endMs} ms, where step ${failedEvent.stepIndex} failed`,
});
}
// A step with no length still shows for the instant it starts.
const failedUntil = Math.max(failedEvent.endMs, failedEvent.startMs + 1);
for (const [index, cut] of cuts.entries()) {
if (cut.startMs < failedUntil && cut.endMs > failedEvent.startMs) {
issues.push({
path: `cuts[${index}]`,
code: 'trim-hides-failure',
message: `expected the cut to leave step ${failedEvent.stepIndex}, which failed, on screen`,
});
}
}
}
if (Number.isFinite(toMs)) {
const cutMs = cuts.reduce(
(sum, cut) =>
sum +
Math.max(0, Math.min(cut.endMs, toMs) - Math.max(cut.startMs, fromMs)),
0,
);
if (toMs - fromMs - cutMs < MIN_PAGE_MS) {
issues.push({
path: trim === undefined ? 'cuts' : 'trim',
code: 'too-short',
message: `expected at least ${MIN_PAGE_MS} ms of page after the trim and the cuts`,
});
}
}
return issues;
}

/** The failure of a capture stage, as the renderer reads it; `undefined` on a passed run. */
function failureOf(result: RunResult): { stepIndex?: number } | undefined {
for (const stage of CAPTURE_STAGES) {
const state = result.stages[stage];
if (state.status === 'failed') {
return state.error?.stepIndex === undefined
? {}
: { stepIndex: state.error.stepIndex };
}
}
return undefined;
}

/** The stages that decide whether the run failed; `rendering` and `storage` do not. */
const CAPTURE_STAGES = [
'readiness',
'execution',
'verification',
'recording',
] as const;
Loading
Loading