Skip to content

Clipper server ​

Clipper is the downloadable clipping app. It runs on the editor's machine and works offline on its own. Connected to this server it gets three things the offline engine cannot do well: speech-to-text, clip scoring, and titles with hashtags. The app itself is in Clipper app. The wire contract is packages/domain/src/clipper.ts, and the decision is 0011 Clipper.

The server never receives video. The app sends only the audio it needs for transcription, plus small JSON summaries for scoring and metadata, and, when the model takes images, up to four small still frames per candidate for scoring (ADR 0013).

Setup ​

  1. Set the transcription and language-model variables below (all optional; without them the app stays offline and says so).
  2. Migrations apply on deploy and on alchemy dev (packages/infra/alchemy.run.ts); the Clipper migration is 20261120172029_clipper_server.
  3. Publish the app builds to R2 (see Releases).
  4. Check Settings → Clipper (clipper.enabled is on by default).

Without a transcription provider, features.transcribe is false in the handshake and the app transcribes offline. The same applies to score and metadata with no language model. A feature is reported only when its provider is really configured.

Issuing keys ​

Only owners, managers, editors and videographers can hold or use a key. Clients and sales accounts are refused (FORBIDDEN).

  • In the web app (Clipper page, once built), or through oRPC: v1.clipper.keys.create({ name, expiresInDays? }). The secret (sgc_…) is shown once.
  • expiresInDays (1 to 365) sets an expiry.
  • v1.clipper.keys.list shows each user only their own keys; owners and managers see all.
  • v1.clipper.keys.revoke({ id }) disables a key at once. Editors and videographers can revoke only their own keys; a foreign key is NOT_FOUND.
  • Every key carries the permissions clipper: connect, ai, sync.

The app connects with bun src/main.ts connect <server-url> <key>. It then sends the key as x-api-key on every request.

Protocol ​

Base path: /clipper/v1. Except GET /releases/latest (public) and GET /download/:platform (a key or a session), every route needs x-api-key. Replies are JSON; errors are { code, message, requestId?, retryAfterSeconds? }.

Method and pathPurpose
GET /releases/latestPublic. Latest and minimum app version, and per platform whether a build is published.
GET /download/:platformDownload a build. Accepts a connect key or a signed-in owner, manager, editor or videographer session.
POST /handshakeRegister the app install (client.installId, name, platform, appVersion). Returns clientId, features, limits, the month's usage, and the versions.
POST /ai/transcribeAudio body (audio/*, video/* or application/ogg). Headers: x-clipper-duration (seconds, up to 600), x-clipper-language (optional).
POST /ai/scoreRanks candidate windows (features, text and, when the model takes images, up to four still frames per window; never video). Returns scores, categories and tags per clip, plus a visual summary and on-screen moments for clips sent with frames.
POST /ai/metadataTitles, descriptions and hashtags per platform for the kept clips.
POST /eventsLog, metric and audit events from the app (up to 200 per batch).
PUT /projects/:idCreate or update a project. A project id that belongs to someone else is NOT_FOUND.
PUT /projects/:id/clipsReplace the project's clips (up to 80 candidates per sync).
GET /videosThe videos this key can send clips to, with kind (footage or edit), canUpload, reason when not, and the video's version. Owners and managers see every video, read-only.
POST /videos/:id/uploadsStart a crew upload of one clip (fileName, bytes). Same rules as the web app's uploads.
PUT /videos/:id/uploads/:uploadId/parts/:n?key=…One part, at most 8 MiB. Content-Length is required. The key comes from the start reply.
POST /videos/:id/uploads/:uploadId/completeFinish as the video's next version. id is a UUID the app mints; a retry with the same id returns the same version and writes nothing new.
DELETE /videos/:id/uploads/:uploadId?key=…Abandon an open upload.

Headers:

  • x-api-key: the sgc_… key. Required except on the release and download routes.
  • x-clipper-client: optional. The clientId returned by the handshake. The request's rows then attach to that client; without it they are not attached to one.
  • Content-Length: required on /ai/transcribe (the app's fetch sets it for a Uint8Array body). Without it the reply is 400.

Error codes and their HTTP statuses:

CodeStatusMeaning
UNAUTHORIZED401Missing, unknown, disabled or mismatched key.
KEY_EXPIRED401The key's expiry has passed.
FORBIDDEN403The owner's role or account cannot use Clipper (banned, demoted).
NOT_FOUND404Also used for records that belong to someone else.
BAD_REQUEST400Invalid body, header or content type.
PAYLOAD_TOO_LARGE413Audio over 12 MiB, an upload part over 8 MiB, or a JSON body over its route limit (1 MiB; 2 MiB for clip sync and metadata; 4 MiB for scoring).
CONFLICT409The video is not in a stage that accepts this upload, or the version id belongs to another video.
CLIENT_TOO_OLD426The app is below clipper.minVersion.
QUOTA_EXCEEDED429Monthly AI requests or audio minutes used up.
RATE_LIMITED429Over clipper.ratePerMinute; retryAfterSeconds says when to retry.
UPSTREAM_FAILED502The provider failed or returned an unusable reply (after one repair retry for JSON).
NOT_CONFIGURED503The step has no provider configured.

Sending clips to production ​

A key sends clips to a video it can see. Videographers send footage (stages shoot, footage handoff and edit). Editors send the edit (stages edit, internal review and changes requested). Owners and managers see the list but cannot send; they upload from the web app. A key with no crew seat sees an empty list with a message.

A send is the web app's upload. The server checks the stage, stores the clip as the video's next version, and records the crew audit clipper.handoff and the same notifications. The app sends each clip in parts of at most 8 MiB and completes only when every part is in. If a send fails, the app aborts that upload and reports how many clips were sent before the failure; clips already sent stay sent.

Environment ​

VariableUsed for
AI (Workers binding)Transcription with Workers AI (@cf/openai/whisper-large-v3-turbo) when no OpenAI key is set. Bind it in packages/infra/alchemy.run.ts.
OPENAI_API_KEYTranscription with OpenAI. Takes precedence over the AI binding.
OPENAI_BASE_URLOptional. Overrides the OpenAI endpoint (for example a proxy).
OPENAI_TRANSCRIBE_MODELOptional. The OpenAI speech model.
RESEARCH_LLM, ANTHROPIC_API_KEY, ANTHROPIC_MODELThe language model for scoring and metadata. Clipper uses the same model as research. RESEARCH_LLM is auto, claude-cli, anthropic or off.
CLAUDE_BRIDGE_URL, CLAUDE_BRIDGE_TOKENDevelopment only: the Claude app through bun run claude:bridge.
WHISPER_CLI, WHISPER_MODELDevelopment only (apps/server/dev/whisper-cpp.ts). Used by the local server when set; never imported by the Worker.

Keep secrets in the deploy environment. See apps/server/.env.schema for the full list.

Quotas and settings ​

Settings group clipper (changes apply on the next request):

  • clipper.enabled: when off, the handshake, AI, sync and handoff routes refuse with a clear message and no provider is called. Release downloads still work.
  • clipper.enabled: when off, every Clipper route refuses with a clear message and no provider is called.
  • clipper.ratePerMinute: requests per key per minute. It is applied when a key is created, so a change reaches keys created after it.
  • clipper.monthlyAiRequests and clipper.monthlyAudioMinutes: per user, per UTC month (clipperPeriod). Checked before every AI call. A refusal is QUOTA_EXCEEDED (429) and is recorded as an error usage row, which does not count toward the month. A provider call that fails does count, because it cost money.
  • clipper.latestVersion and clipper.minVersion: set after each app build is uploaded.

What is logged and what never is ​

Stored, per AI call: the kind (transcribe, score, metadata), status, error code, audio seconds, token estimates, latency, the user, the client and the time. Stored, per project and clip: names, mode, engine, status, stats and the clip times and scores the app sends. Stored, for the audit trail: key create and revoke, and the app's audit events.

Never stored or logged: audio bytes, transcript text, file paths, or video. The app never sends video. An error row carries only the error code, not the provider's message or any text that was sent. Event messages are stored as the app sends them, and the app is built not to send paths or transcript text.

Releases ​

Builds live in R2 at:

clipper/releases/<platform>/clipper        (linux, macos-arm64, macos-x64)
clipper/releases/<platform>/clipper.exe    (windows)

Platforms are linux, windows, macos-arm64 and macos-x64. GET /clipper/v1/download/<platform> streams the file as an attachment with cache-control: no-store. A missing build is NOT_FOUND with a clear message. Set clipper.latestVersion and clipper.minVersion after uploading so the app can tell users to update.

Verifying ​

bun test in packages/api covers the server side with fake providers and the in-memory database: key roles and revocation, handshake, quota (429 and the metered row), transcribe, score and metadata (malformed JSON, the repair retry, and an unusable reply as UPSTREAM_FAILED with an error row), project and clip ownership, usage percentiles and per-day totals, the audit merge, and send to production (who can send what, footage and edit uploads, a replayed complete, abort, the part size limit, and the versioned event data).

Internal documentation. Not for clients.