sanity-plugin-r2-video 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# sanity-plugin-r2-video
+
+Video for Sanity Studio, stored in Cloudflare R2 as a ladder of plain MP4s.
+
+Encoding happens **in the browser** with [mediabunny](https://mediabunny.dev) —
+WebCodecs, in a Web Worker. Each source becomes one MP4 per rendition tier, and
+the first frame is uploaded to Sanity as a native image, so posters get the
+Sanity CDN, `srcset`, `auto=format` and LQIP for free. A rendition is picked
+once at load from the element's size, and never swapped.
+
+## Installing
+
+```bash
+pnpm add sanity-plugin-r2-video
+```
+
+`sanity`, `react`, `react-dom`, `@sanity/ui`, `@sanity/icons` and
+`styled-components` are peer dependencies. `mediabunny` is the only real
+dependency.
+
+Then add the plugin, and a Worker for it to talk to:
+
+```ts
+// sanity.config.ts
+import { r2Video } from "sanity-plugin-r2-video/studio";
+
+export default defineConfig({
+  plugins: [
+    r2Video({
+      endpointUrl: "https://….workers.dev",  // deployed Worker
+      token: "…",                            // matches the Worker's UPLOAD_TOKEN
+      bucketUrl: "https://….r2.dev",         // origin renditions are served from
+    }),
+  ],
+});
+```
+
+## Using it
+
+Everything happens in the **R2 Video** tool in the Studio.
+
+**Upload** — drop files onto the library, or press Upload. Files stage in a
+list first; nothing encodes until you confirm.
+
+**Settings** — collapsed by default. Open it to change the folder, keep audio,
+or adjust quality for this batch only. **Preview** encodes just the tallest tier,
+so you can see the size and quality those settings produce before committing.
+
+**Details** — click a card. Plays the video, lists every rendition with its
+size, and lets you rename it, move it to another folder, or delete it.
+
+**Sync** — beside Upload. Compares the bucket against the library and offers to
+remove anything no document points at.
+
+In a document, add a video through any `asset` field: pick one from the library,
+or upload without leaving the page.
+
+## Configuring
+
+Only `endpointUrl`, `token` and `bucketUrl` are required. Everything else falls
+back to [`studio/defaults.ts`](studio/defaults.ts), shown here with its defaults.
+
+```ts
+r2Video({
+  endpointUrl: "https://….workers.dev",
+  token: "…",
+  bucketUrl: "https://….r2.dev",
+  apiVersion: "2024-01-01",
+  tool: { name: "r2-video", title: "R2 Video" },
+  folders: {
+    type: "media.folder",             // document type folders are read from
+    poster: "_R2 Video Posters",      // where generated posters are filed
+  },
+  encoding: {
+    heights: [270, 360, 480, 720, 1080],
+    videoCodec: "avc",
+    audioCodec: "aac",
+    quality: 0.75,
+    preferBitrate: false,
+    nativeTopTier: false,
+  },
+});
+```
+
+### Encoding
+
+**`heights`** is the tier ladder. A source shorter than a tier skips it; every
+tier it does reach is another full encode.
+
+**`quality`** maps to a **quantizer** for h264, not a bitrate: constant quality,
+variable file size. `0.75` is QP 22, where h264 stops being distinguishable from
+the source. `1` is QP 16, near-lossless, and routinely produces files **larger
+than the source**.
+
+**`preferBitrate`** flips that trade: predictable size, variable quality. A
+1080p tier lands near 6.1 Mbps at `0.75` whatever the footage.
+
+**`nativeTopTier`** copies the top rendition instead of re-encoding it, when its
+height and codec already match the source — instant and bit-identical. Its size
+is then whatever the source was exported at.
+
+## Setting up a Worker
+
+The Worker holds the R2 binding. Scaffold one — the binding name, entry point
+and compatibility date are fixed, and the CLI fills in the rest:
+
+```bash
+pnpx sanity-plugin-r2-video setup worker
+```
+
+Pass `--account`, `--bucket`, `--name` and `--origins` to skip the prompts.
+
+Then install its dependencies, create the bucket, set the shared secret, and
+deploy:
+
+```bash
+pnpm add sanity-plugin-r2-video
+pnpm add -D wrangler @cloudflare/workers-types
+wrangler r2 bucket create my-bucket
+openssl rand -base64 32
+wrangler secret put UPLOAD_TOKEN --config r2-video-worker/wrangler.jsonc
+wrangler deploy --config r2-video-worker/wrangler.jsonc
+```
+
+Give `r2Video()` the deployed URL as `endpointUrl`, the same secret as `token`,
+and the bucket's public URL as `bucketUrl`.
+
+The generated entry point re-exports this package's handler, so upgrading the
+package upgrades the deployed Worker. Only deployment identity — name, account,
+bucket, origins — is written out.
+
+## How it works
+
+```
+Studio ──encoded renditions──▶ Worker ──binding──▶ R2 bucket
+   │                                                   │
+   └──poster──▶ Sanity image assets        bucket URL ─┘
+```
+
+The Worker holds the only R2 binding, so **no R2 credentials exist outside
+Cloudflare**. Uploads go through it as plain request bodies — nothing is signed,
+and the bucket needs no CORS policy. A rendition has to fit in one request body,
+which caps an upload at 100 MB.
+
+`UPLOAD_TOKEN` ships inside the Studio bundle, since the browser is what sends
+the upload — **anyone who can load the Studio can read it**. The Worker's origin
+allowlist is what restricts access. Put Cloudflare Access in front of the Worker
+if you need authentication.
+
+### Entry points
+
+Three, each with its own tsconfig and its own type universe:
+
+```
+./studio     the Sanity plugin      react, react-dom, @sanity/ui
+./worker     the endpoint           @cloudflare/workers-types
+./storage    where files live       nothing
+```
+
+`./storage` has no dependencies. A web app imports it to build source URLs
+without pulling the Studio UI, or `sanity` and `react`, into its bundle.
+
+```ts
+import { resolveRenditionPath } from "sanity-plugin-r2-video/storage";
+
+const src = `${bucketUrl}/${resolveRenditionPath(asset._id, 720)}`;
+```
+
+### Keys
+
+One directory per video, one object per tier, no folder segment:
+
+```
+j6w3wy2bd0jq/270.mp4
+j6w3wy2bd0jq/360.mp4
+j6w3wy2bd0jq/480.mp4
+j6w3wy2bd0jq/720.mp4
+j6w3wy2bd0jq/1080.mp4
+```
+
+Documents store the id and the heights, not URLs — both the Studio and the web
+build sources from `bucketUrl` plus the key. Moving the bucket behind a custom
+domain is a config change, not a migration.
+
+### Folders
+
+Videos are filed in the **same folder documents the image library uses**, not a
+parallel set. Create a folder in the Media tool and it appears in the video
+picker; rename it there and every video moves with it.
+
+The type is `folders.type`, defaulting to `sanity-plugin-media`'s
+`media.folder`. The plugin never imports that package — it reads a document type
+by name, so `folders.type` can point anywhere.
+
+Keys carry no folder, so renaming or moving a video never touches the bucket.
+The tool's filter lists only folders holding video; the upload dialog offers all
+of them.
+
+Generated posters go to their own folder (`folders.poster`), created on first
+upload, so they stay out of the folders holding real images.
+
+### Deleting
+
+Order matters, and `delete-video.ts` documents it:
+
+1. Preflight `*[references($id)]` — anything found blocks the delete.
+2. Delete the document. This releases the strong reference to the poster.
+3. Delete the poster asset. Now unreferenced, so no `409`.
+4. Delete the R2 objects, batched.
+
+Sanity goes before R2: an orphaned object is invisible and costs pennies, a
+document pointing at deleted media breaks the site.
+
+### When an upload fails
+
+The document is written **last**, so a failure can never leave a video in the
+library pointing at files that aren't there.
+
+Anything created before that point is rolled back. Keys are recorded *before*
+each upload, since a request that times out may still have stored the object.
+Rollback never throws — the failure that started it is what surfaces.
+
+**A closed tab or a crash skips rollback entirely**, and encoded renditions live
+only in memory, so there's no resume. Whatever either case leaves behind is
+unreferenced — **Sync** in the tool finds and removes it.
+
+## Limitations
+
+### Chrome only, for uploading
+
+Uploading needs WebCodecs h264 encoding, which Safari doesn't reliably provide.
+The gate is a capability check — mediabunny's own `canEncodeVideo('avc')`, not
+user-agent sniffing — and unsupported browsers get told so before they pick a
+file. **Playback is unaffected everywhere.**
+
+### The encoder runs in a Web Worker
+
+`transcode.worker.js` is loaded with `new URL(…, import.meta.url)`. Vite serves
+that straight from the package, but if it ever pre-bundles the plugin the URL
+goes stale — if uploads fail to start, exclude the package from dependency
+optimisation:
+
+```ts
+// sanity.cli.ts
+vite: (config) => ({
+  ...config,
+  optimizeDeps: { exclude: ["sanity-plugin-r2-video"] },
+});
+```
+
+## Developing
+
+```bash
+pnpm install
+pnpm run type-check
+pnpm run build      # tsup: ESM + types into dist
+```
+
+`./worker` ships as TypeScript: wrangler compiles it, and the generated Worker
+extends `worker/tsconfig.json` for the compiler options it was written against.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const USAGE = `
+  sanity-plugin-r2-video setup worker [directory]
+
+  Writes a deployable Cloudflare Worker: A wrangler config filled in from your
+  answers, and an entry point that re-exports this package's endpoint — so
+  upgrading the package upgrades the Worker.
+
+  directory   Where to write it. Defaults to ./r2-video-worker
+
+  Options (prompted for when omitted, required when not a terminal):
+
+    --name      Worker name                default r2-video
+    --account   Cloudflare account id      required
+    --bucket    R2 bucket name             required
+    --origins   Allowed Studio origins     default http://localhost:3333
+`;
+
+/** Flags parsed as `--key value`, so the command works unattended in CI. */
+const parseFlags = (argv) => {
+	const flags = {};
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+
+		if (arg.startsWith("--")) {
+			flags[arg.slice(2)] = argv[index + 1];
+			index += 1;
+		}
+	}
+
+	return flags;
+};
+
+/**
+ * The Worker re-exports the package's handler rather than copying it, so
+ * upgrading the package upgrades the deployed endpoint. Only identity —
+ * name, account, bucket, origins — is generated.
+ */
+const ENTRY = `// The endpoint itself lives in the plugin, so upgrading the package upgrades
+// this Worker. Only deployment identity belongs here, in \`wrangler.jsonc\`.
+export { default } from "sanity-plugin-r2-video/worker";
+`;
+
+const TSCONFIG = `{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "sanity-plugin-r2-video/worker/tsconfig.json"
+}
+`;
+
+const ask = async (rl, question, fallback) => {
+	if (!rl) {
+		return fallback ?? "";
+	}
+
+	const suffix = fallback ? ` (${fallback})` : "";
+	const answer = (await rl.question(`  ${question}${suffix}: `)).trim();
+
+	return answer || fallback || "";
+};
+
+/**
+ * Only the values that differ per deployment. The binding name, the entry point
+ * and the compatibility date are fixed — the Worker source expects them, so
+ * asking would only create a way to get them wrong.
+ */
+const createConfig = ({ name, accountId, bucket, origins }) => {
+	return `{
+	"$schema": "./node_modules/wrangler/config-schema.json",
+	"name": ${JSON.stringify(name)},
+	"account_id": ${JSON.stringify(accountId)},
+	"main": "src/index.ts",
+	"compatibility_date": "2026-08-01",
+
+	// The binding is what keeps R2 credentials out of your repo entirely — the
+	// Worker reaches the bucket directly, so nothing has to be signed or stored
+	"r2_buckets": [
+		{
+			"binding": "BUCKET",
+			"bucket_name": ${JSON.stringify(bucket)}
+		}
+	],
+
+	"vars": {
+		// Studio origins allowed to call this Worker, comma separated
+		"ALLOWED_ORIGINS": ${JSON.stringify(origins)}
+	}
+
+	// UPLOAD_TOKEN is set separately, with: wrangler secret put UPLOAD_TOKEN
+	// Not because it's secret — the Studio ships the same value to browsers —
+	// but so it stays out of this file, out of git, and out of deploy logs
+}
+`;
+};
+
+const setupWorker = async (target, flags) => {
+	const directory = resolve(process.cwd(), target ?? "r2-video-worker");
+
+	if (existsSync(directory)) {
+		console.error(
+			`\n  ${directory} already exists. Move it or pick another.\n`,
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	// Prompt only for what wasn't passed, and only when there's someone to ask
+	const rl =
+		(!flags.account || !flags.bucket) && process.stdin.isTTY
+			? createInterface({ input: process.stdin, output: process.stdout })
+			: null;
+
+	const answers = {
+		name: flags.name ?? (await ask(rl, "Worker name", "r2-video")),
+		accountId: flags.account ?? (await ask(rl, "Cloudflare account id")),
+		bucket: flags.bucket ?? (await ask(rl, "R2 bucket name")),
+		origins:
+			flags.origins ??
+			(await ask(rl, "Allowed Studio origins", "http://localhost:3333")),
+	};
+
+	if (rl) {
+		rl.close();
+	}
+
+	if (!answers.accountId || !answers.bucket) {
+		console.error(
+			"\n  An account id and a bucket name are both required." +
+				"\n  Pass --account and --bucket, or run this in a terminal.\n",
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	await mkdir(join(directory, "src"), { recursive: true });
+	await writeFile(join(directory, "src", "index.ts"), ENTRY);
+	await writeFile(join(directory, "tsconfig.json"), TSCONFIG);
+	await writeFile(join(directory, "wrangler.jsonc"), createConfig(answers));
+
+	const config = `${target ?? "r2-video-worker"}/wrangler.jsonc`;
+
+	console.info(`
+  Written to ${directory}
+
+  Next:
+
+    1. Install its dependencies there:
+         pnpm add sanity-plugin-r2-video
+         pnpm add -D wrangler @cloudflare/workers-types
+    2. wrangler secret put UPLOAD_TOKEN --config ${config}
+    3. wrangler deploy --config ${config}
+    4. Pass the deployed URL, the same token, and the bucket's public origin
+       to r2Video() in sanity.config.ts.
+`);
+};
+
+const argv = process.argv.slice(2);
+const [command, subcommand] = argv;
+const target = argv[2] && !argv[2].startsWith("--") ? argv[2] : undefined;
+
+if (command === "setup" && subcommand === "worker") {
+	await setupWorker(target, parseFlags(argv));
+} else {
+	console.info(USAGE);
+	process.exitCode = command ? 1 : 0;
+}

package/dist/chunk-D5VS4ED7.js

@@ -0,0 +1,6 @@
+// storage.ts
+var resolveRenditionPath = (id, height) => {
+  return `${id}/${height}.mp4`;
+};
+
+export { resolveRenditionPath };

package/dist/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Get the R2 object key for one rendition:
+ *
+ * ```
+ * k3m9p2xq7wvt/1080.mp4
+ * └─── id ───┘ └height┘
+ * ```
+ *
+ * One folder per video, one object per tier inside it. Deliberately flat - no
+ * folder segment, because folders are a Sanity concern only, so moving or
+ * renaming one never has to match anything stored.
+ */
+declare const resolveRenditionPath: (id: string, height: number) => string;
+
+export { resolveRenditionPath };

package/dist/storage.js

@@ -0,0 +1 @@
+export { resolveRenditionPath } from './chunk-D5VS4ED7.js';