Appearance
ADR 0012: Clipper handoff and frame board
- Status: Accepted
- Date: 2026-11-20
- Spec version: 1.2.0
- Builds on: ADR 0011
Context
ADR 0011 keeps video on the editor's machine. The production spec (Production pipeline) has a stage "Footage clipped and handed off", and the app already stores uploaded footage and edits as versions of a video (video_version, R2). Editors need to put the clips they made into that flow without a second manual upload, and need a quick way to inspect every clip before they do.
Decision
- Handoff is the one exception to "video never leaves the machine". A user chooses clips in the Clipper and sends them to one video. The upload goes through
/clipper/v1/videos/...and reuses the crew upload logic (startUpload,uploadPart,completeUpload) with the key owner as the actor, so stage rules, content types, versioning, audit and staff notification are exactly those of the web upload. - Who can send: a videographer (footage, while the video is in shoot or handoff) or an editor (edit, while it is in edit or review), only for videos assigned to them. Owners and managers can hold keys and see usage and the library, but upload from the web app, as they do today. Nothing new is added to
access.tsbeyond key scope. - Always a user action. The send dialog says what will be uploaded and where before anything starts. Each clip sent is audited (
handoff.clip) and the project file records where it went. - Frame board. Every rendered clip gets about ten frames chosen from the finished clip, a tiled contact sheet (
NN-title.board.jpg), the single frames, and a project-levelframeboard.html. The studio shows the strip under each clip and a full board view. It is generated on the editor's machine and never uploaded unless the clip itself is. - Rendering stays local. Video processing must not run inside a Worker request (Stack); the server still only transcribes, scores and writes copy.
Consequences
- Handoff inherits the crew upload limits (part size, content types, one version per upload) and its failure modes. A refused send shows the server's reason; nothing is uploaded for a refused clip.
- The project file on the editor's machine, not the database, records which clip went to which video version. The video's own version history is the server-side record.
- A clip sent to a video is a copy: re-rendering the clip later does not change the uploaded version.
Revisit when
Owners or managers need to send from the app (they would need a role on the video), or the upload path moves to presigned browser-to-R2 uploads (the app would need presigned parts too).