Setup

Setup — for Peter

The one-time work that stands up the SuperStories video production system. Once these steps are done, the PM operates the system using the workflow page. The editor trains the system using the training page. Why this approach is structurally different from anything you can buy is on the comparison page.

This is a one-day build. Plan a focused day or two for the setup. Quality compounds afterward.

Step 1 — Stand up shared storage (R2 + web uploader)

All video assets and renders live on Cloudflare R2. People put files in and pull them out through a web uploader at uploader.superstories.com — a browser page. No desktop client to install, no per-person keys to hand out: you log in and drag files.

Why R2 and not Google Drive or Dropbox. Drive and Dropbox sync clients are slow and conflict-prone for large video files. R2 stores binaries cheaply with zero egress fees, so clients can rewatch drafts a thousand times at no extra cost. The uploader streams large files straight to R2 with automatic multipart, so there is no 300 MB limit (R2's own dashboard upload caps at 300 MB; the uploader does not).

History worth keeping: we first tried desktop S3 clients (Mountain Duck, then Cyberduck). On our Macs they were unreliable: Gatekeeper quarantine, a File Provider that hung on listing, the menu-bar icon hiding behind the notch, and connections failing at the account root. R2 itself was always fine (verified with a signed request). The web uploader replaced the clients: nothing to install, and access is a login instead of a distributed key.

1a. The bucket

• Bucket name: superstories-videos
• Location: Western Europe (WEUR)
• S3 API endpoint: https://fa246725f963a3b517cc4687bb904c40.r2.cloudflarestorage.com
• Folder layout inside the bucket: <client>/<project>/sources/incoming/, sources/normalized/, renders/, thumbnails/

1b. The web uploader

• Lives in its own repo SuperStoriesAmsterdam/superstories-uploader, deployed on Coolify at uploader.superstories.com.
• The backend holds one R2 API token server-side (uploader-backend, Object Read & Write, scoped to the bucket). Users never see R2 keys.
• Features: login, browse folders, drag-and-drop upload (auto multipart, no size limit), download.
• DNS: the uploader.superstories.com record in Cloudflare is DNS-only (grey cloud), not proxied — otherwise Cloudflare's proxy caps uploads at 100 MB. Coolify issues the TLS certificate.
• Config (Coolify env vars): R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET, SESSION_SECRET, USERS, NODE_ENV=production. All runtime, not buildtime.

1c. Access management — a login, not a key (PM-runnable)

Access is a username + password, set in the uploader's USERS env var in Coolify (format: name:password,name2:password2).

• Add someone: add a name:password pair to USERS, redeploy. Passwords must contain no spaces, commas, or colons (those are separators).
• Remove someone: delete their pair, redeploy. Access is cut instantly.
• No R2 tokens are distributed. The only R2 token is uploader-backend, and it never leaves the server.

1d. Onboarding a remote editor (who cannot set anything up)

Send them three lines: the URL, their username, their password. Nothing to install, no keys, no configuration. They open uploader.superstories.com, log in, and drag files. Done.

1e. Automation uses direct R2 (not the uploader)

The uploader is for humans. The automated pieces — the input normalizer (Step 2), ss-publish (Step 10), and Claude's renders — run on a machine or server with direct R2 access (the backend token, or an rclone mount on that machine). Humans use the browser; automation talks to R2 directly.

1f. When to split into per-client buckets

Today everything lives in one bucket with folders per client, and the login gates the whole bucket — anyone who can log in sees every client's folder. That is fine while it is just Peter + PM + the occasional editor.

Split into a bucket per client (e.g. superstories-wholenesswork) the first time either is true:

• two editors are working on different clients at the same time, or
• a client contractually needs their material walled off.

Then run a second uploader instance pointed at that client's bucket, with its own USERS — and an editor only ever logs into the one for their client.

Step 2 — Set up input normalization

A small folder-watcher transcodes anything dropped into sources/incoming/ into a clean H.264 1080p MP4 in sources/normalized/. Claude reads from normalized/.

The watcher handles: format conversion (MOV, MKV, ProRes, AVI, WebM → MP4), bitrate normalization, frame rate normalization, audio loudness levelling to -14 LUFS, resolution capping at 1080p.

Install ffmpeg on the machine running the watcher. Configure a launchd job that watches sources/incoming/ and runs the transcode command on any new file. The script is small (~30 lines).

A 2GB ProRes file transcodes in 1-3 minutes on an M-series Mac and shrinks ~5-10× in the process.

Step 3 — Install HyperFrames and Claude Code skills

HyperFrames is HeyGen's open-source HTML-to-video framework, Apache 2.0, released April 2026.

On each machine that will edit video:

1. Install Claude Code if not already present.
2. npx skills add heygen-com/hyperframes to install the HyperFrames skill into Claude Code. This adds /hyperframes, /hyperframes-cli, and /gsap slash commands.
3. Per project: npx hyperframes init <project-name> creates the project structure.

Cursor, Gemini CLI, and Codex also support the same skill, so the workflow is not locked to one tool.

Step 4 — Recording tools per use case

Different content types want different recording tools. Configure each on the machines that need them.

• Founder-to-camera (face only). iPhone front camera on a tripod, native iOS recording. AirDrop to Mac. Quality beats any webcam.
• Screen + cam (demos, walkthroughs, training modules with slides). Screen Studio. ~$229, Mac-only, best-in-class. Auto-zoom on clicks, smooth cursor animations, branded backgrounds.
• Quick drafts and multi-source recording. Tella, browser-based.
• Multi-person interviews and podcasts. Riverside.fm, broadcast quality with local recording per participant.

Capture-layer quality matters more than the polish layer. €60 Elgato Key Light + €100 Rode mic produces a bigger quality jump than any software switch.

Step 5 — Set up the git repo for brand foundations and recipes

Brand foundations, motion explorations, component sources, and editorial recipes are text. They live in a private git repo. Never on R2 (R2 is for binaries).

1. Repository at ~/Desktop/Builds/proprietarysuperstories/ (this repo).
2. Private GitHub: SuperStoriesAmsterdam/proprietarysuperstories.
3. Structure:

   video/
   ├── recipes/                  ← cross-client knowledge
   │   ├── cut-recipes.md
   │   ├── motion-recipes.md
   │   └── component-recipes.md
   └── clients/<client>/
       ├── BRANDGUIDE.md         ← canonical, single source of truth
       ├── references/           ← reference videos and notes
       ├── hyperframes/          ← client-specific component sources
       ├── motion-exploration/   ← motion sprint outputs
       └── projects/             ← per-video briefs and decision logs
   

4. Clone the repo on every machine that edits brand foundations. PM uses GitHub Desktop or Cursor's git integration.

Step 6 — Set up brand foundation for the first client

The brand foundation is everything downstream depends on. Without a deep one, output stays generic.

1. If the client has identity assets in a folder, run the /brandguide skill on that folder. It scans, asks questions, and generates a structured BRANDGUIDE.md.
2. If the client already has a brand guide elsewhere, copy it into video/clients/<client>/BRANDGUIDE.md. That location becomes canonical. Update any other references (website builds, etc.) to read from here.
3. Extend the brand guide with the video-specific sections (DRAFT until populated):
   • Motion principles — character, default durations and easing, vocabulary, what we never do
   • Caption styling — font, weight, color, position, animation, language variants
   • Video components — title card, lower-third, chapter marker, key-takeaway card, end card
   • Editorial patterns — how this person speaks, how this brand cuts
4. Add 5-10 reference videos to references/videos.md with one-line notes on why each is a reference (the taste anchor). Without this, output drifts to generic.

Step 7 — Run the first motion exploration sprint

Motion vocabulary is a deliberate choice per brand. Spend half a day per new client doing motion exploration before the first video.

1. Write a brief.md in motion-exploration/ describing the desired motion character, timing, vocabulary, and what to never do.
2. Ask Claude: generate 8 motion concepts based on the brief, each a self-contained HTML file with one looped animation, plus an index.html showing all 8 in a grid.
3. Review the grid. Pick 2-3 that feel right. Discard the rest.
4. Iterate on the winners ("this one but 30% slower with a subtler color shift").
5. Codify the chosen patterns in the brand guide's Motion Principles section.
6. Promote any generalizable patterns to recipes/motion-recipes.md.

Step 8 — Set up the review infrastructure

Reviews run on SuperStories' own annotation infrastructure, not third-party tools.

1. The annotation backend at annotations.superstories.com is already running (Python service, deployed on Coolify, persistent multi-user backend).
2. For a new project, add an API_KEYS entry in the format <project>:<key> to the annotations-api environment in Coolify. Restart the container.
3. Wire the key into the SS_ANNOTATIONS config on any page that hosts review.
4. Each video gets a private review URL at videos.superstories.com/diff/<project> (the video hub).
5. For internal review and client review, the same surface handles both, attributed per user.

Step 9 — Set up the video hub

A single dashboard at videos.superstories.com shows every active draft across all clients.

1. Frontend reads from the annotations backend plus a videos manifest stored on R2.
2. Each card: thumbnail, title, status (draft / in-review / approved), note count, last activity.
3. Filter by client, status, project.
4. Clicking a card opens the review page for that video with the annotation tool attached.

For the Cut Diff Tool (training surface for the editor), the same hub gains a /diff/<project> route. See the training page for what the editor does there.

Step 10 — Configure the publish CLI

A small ss-publish script moves a rendered MP4 from local working folder onto R2 and registers it in the video hub.

ss-publish ./renders/16x9.mp4 --client=<x> --project=<y> --status=review

What it does:

1. Uploads to R2 under <client>/<project>/<slug>.mp4.
2. Generates a thumbnail (first decent frame via ffmpeg).
3. Registers in the videos.superstories.com manifest.
4. Prints the review URL.

Privacy default: obscure-URL slugs. Upgrade to signed, expiring URLs for NDA work.

Step 11 — Bring the editor on board for training

This is the connection between setup and the training methodology. See the training page for the editor's full briefing.

1. Add the editor as a collaborator on the proprietarysuperstories repo (read access to recipes, no write needed).
2. Give the editor a login on the uploader (uploader.superstories.com) — add a name:password pair to the USERS env var in Coolify and redeploy. Send them the URL + credentials; nothing to install. See Step 1c/1d.
3. Brief the editor on the Cut Diff Tool methodology and the "you sell taste, not time" framing.
4. Agree on the rhythm: biweekly recorded sync, 20-minute diff-review per project, training/test split for the first 6 reels.

What does NOT live in this setup

• Video binaries in git. They live on R2.
• Brand foundations in R2. They live in git.
• Client review on Frame.io. Default is our own annotation surface. Frame.io is fallback.
• "Edit this video" as a prompt. The brief is required.
• Cinematic motion design through this system. For that, commission a motion designer.

Build timeline — what you stand up in day one

The whole infrastructure is a focused day of work:

End of day one: PM can drop a video in R2, Claude + HyperFrames renders, output appears on the hub with the annotation tool attached.

The infrastructure is the easy part. The compounding value comes from usage. See the workflow page for what the PM actually does.