# Async video ## What this builds A web app for async video messages. The owner records their screen, their camera, or their screen with their face in a round camera bubble, straight from the browser. When they press Stop, the recording stays in the browser and opens in a review step: they play it back, trim the start and end, optionally remove one section from the middle, set the title and choose whether it has sound. Nothing is uploaded until they press Save. Then the browser cuts the file down to the kept part (dropping the sound if muted), uploads only that, and opens it on its own share page. The cut parts never leave the owner's device. They copy the link and send it. Anyone with the link can watch without an account. Viewers can: - play it with a proper player: speed control, keyboard shortcuts, chapters, a seek bar with markers - leave comments pinned to the moment they were watching - react with emoji at a moment in the video - download it, if the owner allows it The owner has a library of their videos, and for each one can rename, cut it again (trim, remove a section, mute: this replaces the stored file and can't be undone), add chapters, turn comments or downloads off, and delete. Recording needs an account, and a deployment can limit accounts to a list of email addresses (R2). Watching never does. It is one Cloudflare Worker: - The React single-page app is the Worker's static assets. - The JSON API runs in the Worker. - Video files and thumbnails live in one R2 bucket. Uploads use R2 multipart uploads, so large files go up in parts. - Accounts, sessions, video details, comments, reactions and views live in one D1 database. Recording happens entirely in the browser with `getDisplayMedia`, `getUserMedia`, a canvas for the camera bubble and `MediaRecorder`. There is no server-side video processing, no transcoding and no third-party service. It runs on a laptop with `npm install` and `npm run dev` (`wrangler dev` with local D1 and R2, no Cloudflare account). It deploys with `npm run deploy`. Read `spekkr.inputs.json` first. It sits at the repository root. If it is missing, create it from the `customize.settings` defaults in `spekkr.json`; with the defaults its full contents are: ```json { "app_name": "Async Video", "accent_color": "#0d9488", "allowed_emails": "" } ``` It has exactly these three keys: - **`app_name`:** the product name (default "Async Video"). It is the page title, the name next to the brand mark, and the name in the sign-in text. - **`accent_color`:** the accent colour (default `#0d9488`). It is used for primary buttons, the seek bar's played part, timestamps, active tabs, switches, selection and focus rings. - **`allowed_emails`:** comma-separated email addresses that may have an account (default empty, which means anyone). The builder copies it into `vars.ALLOWED_EMAILS` in `wrangler.jsonc`. The Worker reads only the var, so a deployment can change it without a rebuild (R2). `design.md` has: - the stack, Cloudflare config and deploy steps - the data model and storage layout - the recording pipeline and upload protocol - the API, the limits - every screen and the look `tasks.md` is the build order. `research.md` records where the design came from; the builder does not need it, and nothing in it is a requirement. ## Names and words - The product is called `app_name` everywhere. The built app never shows the name, logo or wording of any other video messaging product. - The brand mark is a rounded square in the accent colour with a white dot (a record light) in the middle. - Interface text the spec quotes is the text to use. Other text is the builder's own, short and plain. - No image, font or icon file is copied from another product. Icons are inline SVG drawn in the app's own code. The font is Inter (SIL Open Font License) from `@fontsource-variable/inter`, latin subset only. ## Words used here - **Owner:** the signed-in account that recorded a video. **Viewer:** anyone opening a share link, signed in or not. - **Mode:** what a recording captures: `screen_camera` ("Screen + camera"), `screen` ("Screen only") or `camera` ("Camera only"). - **Bubble:** the round camera picture drawn over the screen in `screen_camera` mode. - **Media time:** a position in the stored file, in milliseconds. Comments, reactions and chapters store media time, and the player shows it. - **Selection:** while editing (review step or "Edit video"), the trim window `[trim start, trim end]` and an optional **removed section** strictly inside it. - **Kept parts:** the trim window minus the removed section (one or two segments). **Removed parts:** everything else (up to three spans: before the trim start, the removed section, after the trim end). - **Cut:** a new file made in the browser from the kept parts laid end to end (and without sound if muted). Saving a selection that removes anything, or mutes, makes a cut; the stored file is always exactly what viewers see. - **Viewer id:** 22 random base62 characters kept in the browser's `localStorage` (`av.viewer`) and sent as the `x-viewer` header. It counts views once and lets people delete their own comments. - **MB:** 1,048,576 bytes. ## Out of scope These are not built: - transcripts, captions, AI summaries or AI chapters (no speech-to-text runs; see research.md) - drawing on the screen while recording, cursor highlights, blurring - teams, workspaces, folders, sharing a video with specific people, password-protected links, link expiry - replying with a video, and comment threads (comments are flat) - embedding on other sites, social share buttons, custom thumbnails, CTA buttons - editing beyond one trim, one removed section and mute: no stitching clips, no multiple removed sections, no overlays, no undo after a cut is saved (the old file is deleted), and no server-side transcoding (cuts are made in the browser) - a desktop app or browser extension; recording from another tab works because the browser's own screen picker offers tabs, windows and screens - email of any kind: no sign-in links, no notifications, no password reset - languages other than English ## Requirements Each requirement ends with an "Accept when" line naming the tests that prove it. Test names are in "Tests" at the end. Unit tests are in `tests/shared.test.ts`; end-to-end tests are in `e2e/`. ### R1. Settings, run and store - `spekkr.inputs.json` is read at build time into `src/shared/settings.ts`. An `app_name` longer than 40 characters is cut to 40; an `accent_color` that is not `#rrggbb` falls back to `#0d9488`. - The page title is `app_name` (a share page then sets it to the video's title). `--accent` is set on `:root` from `accent_color` before the first render. - Runtime is Cloudflare Workers only, with Web APIs and no `node:*` module, so no `nodejs_compat` flag. - `wrangler.jsonc` (exact shape in `design.md`, "Cloudflare config") serves `dist/` as assets with single-page-app fallback, runs the Worker first for `/api/*`, and binds `DB` (D1), `MEDIA` (R2), the three rate limits, and the vars `ALLOWED_EMAILS` and `STORAGE_LIMIT_MB`. - The schema is `migrations/0001_init.sql`, applied with `wrangler d1 migrations apply`. The Worker never creates tables. - Scripts: `build`, `dev` (build, migrate the local D1, `wrangler dev`), `typecheck`, `test`, `e2e`, `deploy`, `types`. Accept when: "R1 the page title and accent colour come from spekkr.inputs.json" passes, `npm run typecheck` passes, and `npx wrangler deploy --dry-run --outdir /tmp/dry` lists DB, MEDIA, CREATE_LIMIT, WRITE_LIMIT, AUTH_LIMIT, ALLOWED_EMAILS and STORAGE_LIMIT_MB. ### R2. Accounts and the email allowlist - Accounts have a name, an email (stored lower-case, unique) and a password (at least 8 characters, PBKDF2-SHA-256 with 100,000 iterations and a 16-byte random salt). There is no email sending, so there is no email verification and no password reset. - Signing up or in creates a session: 32 random bytes as base64url in an `HttpOnly; SameSite=Lax; Path=/` cookie named `sid` (plus `Secure` on https), valid 30 days. Only the SHA-256 of the token is stored. - **Allowlist.** `ALLOWED_EMAILS` is a comma-separated, case-insensitive list. When it is non-empty: - Sign-up with any other email is refused with 403 and `{"error": "This site only accepts accounts for approved email addresses.", "fields": {"email": }}`. Nothing is written. - Sign-in with any other email is refused the same way, before the password is checked. - A session whose account email is no longer on the list counts as signed out. - The sign-in page shows that text under the Email field. When it is empty, anyone may sign up. - The allowlist is checked only in the Worker. The client never decides who may sign up. - Signed-out visitors who open `/` or `/record` see the sign-in page. Share pages never need an account. - Wrong email or password: 401 "Email or password is wrong". Existing email at sign-up: 409, field error "Already registered. Sign in instead." - Sign out deletes the session row and clears the cookie. Accept when: "R2 an email that isn't on the allowlist is refused at sign-up and sign-in", "R2 allowlisted owner signs up, signs out and signs back in; wrong password is refused", "R2 signed-out visitors can't reach the recorder or the library API" and the unit test "allowlist" pass. ### R3. Recorder The recorder is at `/record`. - **Modes:** a segmented control "Screen + camera", "Screen only", "Camera only". The last choice is remembered (`localStorage`). - **Options:** a "Microphone on/off" chip, a bubble size control S / M / L (only in Screen + camera), and a "Countdown" switch (on by default). All remembered. - **Setup stage:** a 16:9 dark stage. - In camera modes, it shows the live camera (front camera on phones, `facingMode: "user"`), mirrored. - In Screen + camera, it shows a placeholder window with "Your screen appears here once you choose it" and the bubble over it, with the live camera inside. - The bubble starts at the bottom-left. It can be dragged anywhere inside the stage and never leaves the frame (it keeps a margin of 3.5 % of the shorter side). Its position and size are remembered and used in the recording. - If the camera is blocked, it says so and "Start recording" stays disabled in camera modes. - Under the button: "Up to 10 minutes. You'll pick a screen, window or tab next. You can trim the start and end before saving." (camera mode: "Up to 10 minutes. You can trim it before saving.") - **Start:** "Start recording" asks for the screen first (the browser's own picker, R3b) in screen modes, then shows a 3-2-1 countdown over the stage ("Click to start now" skips it), then records. - If the picker is cancelled: "Screen sharing was cancelled. Pick a screen, window or tab to record." and back to setup. - **While recording:** the stage shows the live result (for Screen + camera, the composited frame), and a control bar shows: - a pulsing red dot, the elapsed time `m:ss` and "/ 10:00" - Pause / Resume, Restart (throws away what was recorded and starts again with the same screen and camera, timer back to 0:00), Cancel (throws everything away and returns to setup; nothing is uploaded), "Pop out controls" (R3b, only where supported and not already open), and "Finish" - The bubble can still be dragged during a recording. - The timer excludes paused time. In the last minute it turns red. At 10:00 the recording stops by itself. - **Stop** happens on Finish, on Stop in the floating controls, on Alt+Shift+S, at 10:00, or when the shared screen stops (the browser's own "Stop sharing"). It shows "Finishing your recording…" and opens the review step (R3a). Nothing is uploaded at this point. - **Phones:** when `navigator.mediaDevices.getDisplayMedia` does not exist (iPhone, iPad, Android browsers), the two screen modes are disabled, Camera only is selected, and the recorder says "Phones and tablets can't share their screen from a browser, so this device records with its camera." Camera recording, review and upload work as on a computer. Accept when: "R3 R4 R5 screen + camera: countdown, pause/resume, review, upload, then the share page plays a seekable MP4", "R3 screen only and camera only record at the source size", "R3 restart resets the timer; cancel discards without creating a video", "R3 the camera bubble can be dragged and resized, and the choice is remembered", "R15 phones without screen capture offer camera recording only" and the unit test "camera bubble" pass. ### R3a. Review before saving After Stop the recorder page shows "Review your recording" with the recording, which is still only in the browser (an object URL of the recorded Blob). - The line under the heading starts "Nothing is uploaded until you save." and goes on: "You shared a whole screen, so the start and end may show this page: drag the handles to cut them." when a whole screen was shared (`displaySurface` "monitor"), otherwise "Drag the handles to cut the start or end." - **Preview:** the video with its thumbnail as poster and a round play button "Play the kept part" / "Pause preview". Playback starts at the trim start, jumps over the removed section frame by frame (`requestVideoFrameCallback` where available, else `requestAnimationFrame`), and stops at the trim end. Dragging a handle pauses and shows that frame. - **Trim timeline** (the same control as in "Edit video", R7): - two handles, "Trim start" and "Trim end" (range inputs, 100 ms steps), over a bar whose kept part is in the accent colour, with a thin playhead line - "Remove a section…" adds a removed section (red, striped) with handles "Remove from" and "Remove to": 20 % of the trim window, between 0.5 s and 3 s wide, centred on the playhead. "Keep that part" takes it away. At most one removed section. The label reads "Removing m:ss–m:ss". - labels "Start m:ss", " kept" (the kept parts' total) and "End m:ss", and a "Reset" button once anything changed - at least one second must be kept, a removed section is at least half a second and sits inside the trim window - **Title** (default "Recording · ") and a **"Mute audio"** switch. With mute on, the preview plays silently. - A note: "Saving cuts the video in this browser and uploads only the kept part. The cut parts (and the sound, if muted) never leave this device. Cutting can take up to as long as the kept part." - **"Save video":** - With nothing removed and mute off, the recording is uploaded as it is (R5). - Otherwise the browser first makes the cut (R7a): the buttons are replaced by "Cutting your video…" with a progress bar and a "Cancel" button. Cancel returns to the review with nothing uploaded. The cut replaces the recording's file, duration, size and thumbnail (taken from the cut), then it is uploaded. - While uploading: "Uploading your video…" with a progress bar. Then the share page opens with the toast "Your video is ready. Copy the link to share it." - If cutting fails: "Couldn't cut the video: . Your recording is still here; try Save again." If the upload fails: "Upload failed: . Your recording is still here; try Save again." Either way the review stays. - **"Discard and record again"** asks "Discard this recording?" ("It hasn't been saved, so it will be gone for good.", "Discard") and returns to setup. Nothing is uploaded. - Leaving the page during recording, review or upload asks the browser's "leave site?" question. Accept when: "R3a nothing is uploaded until Save; Save cuts the file to the trim and removed section, drops muted sound, and uploads only that", "R3a Save without edits uploads the recording as it is", "R3a cutting can be cancelled, and the real-time fallback cuts too", "R3a discard and record again throws the recording away without uploading", "R3a R15 phones: a trimmed camera recording is cut before upload and saved as MP4" and "R3a R15 WebKit (iPhone 13): a video cut before upload plays, seeks and has the cut length on a share page" pass. ### R3b. Not recording the recorder When the recorder page itself is captured, the start and end of a video show that page. The recorder avoids it where the browser allows and makes the rest easy to cut. - `getDisplayMedia` is called with `selfBrowserSurface: "exclude"` (this tab is not offered), `preferCurrentTab: false`, `surfaceSwitching: "include"` (Chrome's "Share this tab instead"), `monitorTypeSurfaces: "include"` and `systemAudio: "include"`, plus a `CaptureController` where the browser has one. - When a tab or window was shared (`displaySurface` "browser" or "window"), `controller.setFocusBehavior("focus-captured-surface")` runs right after the picker, so the browser switches to what is being shared before the countdown and recording start. - **Floating controls** (Document Picture-in-Picture, Chrome 116+): in screen modes, a small always-on-top window opens right after the picker if the browser still counts the Start click as a user gesture; otherwise the "Pop out controls" button opens it. It shows the countdown ("Start now", "Cancel"), then the red dot, timer, Pause/Resume, Cancel and "■ Stop", using the page's styles. It closes on Stop or Cancel. - **Keyboard:** Alt+Shift+S stops and Alt+Shift+P pauses or resumes, in the recorder page and in the floating controls. - The browser's own "Stop sharing" bar stops the recording (the screen track's `ended` event). - Browsers without these (Firefox, Safari) ignore the extra options: recording works the same, and the review step (R3a) cuts away any recorder frames. Accept when: "R3b screen capture excludes this tab, allows switching and jumps to a shared tab", "R3b a whole-screen share says the start and end may show this page; Stop sharing ends the recording", "R3b the keyboard shortcut Alt+Shift+S stops the recording" and "R3b floating controls (Document Picture-in-Picture) open after picking a screen and can stop the recording" pass. ### R4. The recorded file - **Screen only** records the screen track as it comes. **Camera only** records the camera track (not mirrored). Width and height are the frame as a `