@homie-rocks/studio 0.3.0 → 0.5.0

package/lib/media.mjs

@@ -0,0 +1,126 @@
+/**
+ * A studio's music/ and videos/ manifests (media/MEDIA.md): what the site shows,
+ * and where each file's bytes come from (R2 key, a file in the repository copied
+ * into the site, or an absolute https address).
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, normalize, relative, resolve, sep } from 'node:path';
+
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const KINDS = {
+  music: ['song', 'score', 'loop', 'stem', 'sfx'],
+  videos: ['trailer', 'music-video', 'cutscene', 'clip'],
+};
+/** Cloudflare Workers static assets: one file may be at most 25 MiB. */
+export const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+const TYPES = {
+  '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.wav': 'audio/wav', '.flac': 'audio/flac',
+  '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp', '.vtt': 'text/vtt', '.json': 'application/json',
+};
+export const typeOf = (path) => TYPES[(/\.[a-z0-9]+$/i.exec(String(path)) ?? [''])[0].toLowerCase()] ?? 'application/octet-stream';
+
+export function manifestPath(root, kind) { return join(root, kind, 'manifest.json'); }
+
+export function readManifest(root, kind) {
+  const file = manifestPath(root, kind);
+  if (!existsSync(file)) return { v: 1, items: [] };
+  const m = JSON.parse(readFileSync(file, 'utf8'));
+  return { v: 1, ...m, items: Array.isArray(m.items) ? m.items : [] };
+}
+
+export function writeManifest(root, kind, manifest) {
+  mkdirSync(join(root, kind), { recursive: true });
+  writeFileSync(manifestPath(root, kind), `${JSON.stringify({ v: 1, ...manifest }, null, 2)}\n`);
+}
+
+/** A path inside the studio, or null (no absolute paths, no `..` out of the repository). */
+function inside(root, rel) {
+  if (typeof rel !== 'string' || !rel || rel.startsWith('/') || /^[a-z]+:/i.test(rel)) return null;
+  const abs = resolve(root, normalize(rel));
+  return abs.startsWith(`${resolve(root)}${sep}`) ? abs : null;
+}
+
+/**
+ * Every entry of one manifest with its files resolved, and why anything is left out.
+ * `r2`: the studio has its own bucket (so a `key` is served at /media/<key>).
+ */
+export function resolveMedia(root, kind, { r2 = false } = {}) {
+  const manifest = readManifest(root, kind);
+  const entries = [];
+  const skipped = [];
+  const seen = new Set();
+  for (const item of manifest.items) {
+    if (!item || typeof item !== 'object') continue;
+    const label = item.slug ?? item.key ?? item.file ?? '(unnamed)';
+    if (!SLUG.test(String(item.slug ?? '')) || !item.title) { if (item.published !== false) skipped.push({ kind, item: label, why: 'no slug and title: kept in the manifest, no page' }); continue; }
+    if (seen.has(item.slug)) { skipped.push({ kind, item: label, why: 'a second entry with the same slug' }); continue; }
+    seen.add(item.slug);
+    if (item.published !== true) { skipped.push({ kind, item: label, why: 'not published yet ("published": true shows it)' }); continue; }
+    const files = [];
+    for (const f of Array.isArray(item.files) ? item.files : []) {
+      if (!f || f.public === false) continue;
+      let src = null;
+      if (typeof f.key === 'string' && f.key && r2) src = { from: 'r2', url: `/media/${f.key.split('/').map(encodeURIComponent).join('/')}` };
+      if (!src && f.path) {
+        const abs = inside(root, f.path);
+        if (!abs) { skipped.push({ kind, item: item.slug, file: f.path, why: 'the path is outside the studio' }); continue; }
+        if (existsSync(abs) && statSync(abs).isFile()) {
+          const bytes = statSync(abs).size;
+          if (bytes <= MAX_ASSET_BYTES) src = { from: 'site', url: `/${relative(root, abs).split(sep).map(encodeURIComponent).join('/')}`, abs, rel: relative(root, abs), bytes };
+          else skipped.push({ kind, item: item.slug, file: f.path, why: `${Math.round(bytes / 1048576)} MiB is over the 25 MiB the site serves itself: make it smaller, or give the studio storage (homie-studio storage add; Cloudflare asks for a payment method first, so ask the person) and upload it (homie-studio media put ${f.path})` });
+        } else if (f.key && !r2) skipped.push({ kind, item: item.slug, file: f.path, why: `the file is not on this computer and its storage key "${f.key}" needs the studio's storage (homie-studio storage add)` });
+        else if (!f.key && !f.url) skipped.push({ kind, item: item.slug, file: f.path, why: 'the file is not on this computer and has no R2 key or url' });
+      }
+      if (!src && typeof f.url === 'string' && /^https:\/\//.test(f.url)) src = { from: 'url', url: f.url };
+      if (!src) continue;
+      files.push({ role: String(f.role ?? 'file'), name: f.name ?? null, type: f.type ?? typeOf(f.path ?? f.key ?? f.url), bytes: f.bytes ?? src.bytes ?? null, bars: f.bars ?? null, url: src.url, from: src.from, ...(src.abs ? { abs: src.abs, rel: src.rel } : {}) });
+    }
+    const main = kind === 'music' ? 'audio' : 'video';
+    if (!files.some((f) => f.role === main)) { skipped.push({ kind, item: item.slug, why: `no playable "${main}" file reachable (see the file lines above)` }); continue; }
+    entries.push({
+      slug: item.slug, kind: KINDS[kind].includes(item.kind) ? item.kind : KINDS[kind][0], title: String(item.title).slice(0, 120), blurb: String(item.blurb ?? '').slice(0, 600),
+      duration: Number.isFinite(item.duration) ? item.duration : null, bpm: Number.isFinite(item.bpm) ? item.bpm : null, key: item.key ?? null,
+      lyrics: typeof item.lyrics === 'string' ? item.lyrics.slice(0, 8000) : null, credits: typeof item.credits === 'string' ? item.credits.slice(0, 600) : null,
+      rights: item.rights && typeof item.rights === 'object' ? item.rights : null, for: item.for && typeof item.for === 'object' ? item.for : null,
+      honesty: typeof item.honesty === 'string' ? item.honesty.slice(0, 600) : null, made: item.made?.at ? { at: item.made.at, provider: item.made.provider ?? null } : null,
+      files,
+    });
+  }
+  return { entries, skipped };
+}
+
+/** Copy the site-served files into site/dist and return the catalogue rows (no local paths in them). */
+export function buildMedia(root, dist, { r2 = false, log = () => {} } = {}) {
+  const out = {};
+  const skipped = [];
+  for (const kind of ['music', 'videos']) {
+    const r = resolveMedia(root, kind, { r2 });
+    skipped.push(...r.skipped);
+    out[kind] = r.entries.map((e) => ({
+      ...e,
+      files: e.files.map(({ abs, rel, from, ...f }) => {
+        if (from === 'site') { const dest = join(dist, rel); mkdirSync(dirname(dest), { recursive: true }); cpSync(abs, dest); }
+        return f;
+      }),
+    }));
+    if (out[kind].length) log(`${kind}: ${out[kind].map((e) => e.slug).join(', ')}`);
+  }
+  for (const s of skipped) log(`${s.kind}/${s.item}${s.file ? ` ${s.file}` : ''}: ${s.why}`);
+  return { songs: out.music, videos: out.videos, skipped };
+}
+
+/** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */
+export function recordUpload(root, rel, key, bytes, siteUrl) {
+  const kind = rel.startsWith('videos/') ? 'videos' : 'music';
+  const m = readManifest(root, kind);
+  let hit = false;
+  for (const item of m.items) {
+    for (const f of Array.isArray(item?.files) ? item.files : []) {
+      if (f.path === rel) { f.key = key; f.bytes = bytes; hit = true; }
+    }
+  }
+  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: siteUrl ? `${siteUrl}/media/${key}` : null, at: new Date().toISOString() }];
+  writeManifest(root, kind, m);
+  return { kind, manifest: relative(root, manifestPath(root, kind)), entry: hit };
+}

package/lib/scaffold.mjs

@@ -7,9 +7,12 @@
  *   studio.json          the studio's name, slug, and its Cloudflare resources
  *   package.json         @homie-rocks/studio and wrangler, pinned
  *   games/<id>/          one folder per game (game.json, index.html, src/)
- *   music/ videos/       manifests in the repo; the big files live in the studio's R2
+ *   music/ videos/       manifests in the repo; the big files go to the studio's own storage
+ *                        (R2) once it is added with `homie-studio storage add`
  *   posts/               words the studio publishes
- *   site/                the studio's Worker (pages, rooms), its D1 migrations
+ *   site/                the studio's Worker (pages, rooms), its D1 migrations (no R2
+ *                        binding until the studio adds storage: a free Cloudflare account
+ *                        without a payment method cannot use R2, and a new studio needs none)
  *   .claude/skills/      skills only this studio uses
  *
  * It writes only into a folder that is new or empty, never guesses one, and
@@ -47,7 +50,8 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null }) {
     observability: { enabled: true },
   };
   return `// This studio's site on its own Cloudflare account (written by homie-studio; \`homie-studio deploy\`
-// fills in the D1 id, and drops the R2 binding when the account has no R2).
+// fills in the D1 id). Everything here runs on Cloudflare's Workers Free plan. There is no R2 binding
+// until \`homie-studio storage add\` gives the studio storage for large media.
 ${JSON.stringify(config, null, 2)}
 `;
 }
@@ -55,19 +59,19 @@ ${JSON.stringify(config, null, 2)}
 function agentsMd({ name, slug }) {
   return `# ${name}
 
-This folder is a game studio: **${name}** (\`${slug}\`). It is one repository.
+This folder is a studio: **${name}** (\`${slug}\`). It is one repository.
 Its games, music, videos and posts live here; its website and public game rooms
-run on the studio's **own Cloudflare account** (a Worker, D1, R2, and the
-Table/Lobby Durable Objects), built from \`@homie-rocks/studio\`, pinned in
-\`package.json\`. The homie.rocks directory lists its games; homie.rocks does
-not host them.
+run on the studio's **own Cloudflare account** (one Worker, one D1 database and
+the Table/Lobby Durable Objects, all on Cloudflare's free Workers plan), built
+from \`@homie-rocks/studio\`, pinned in \`package.json\`. The homie.rocks
+directory lists its games; homie.rocks does not host them.
 
 ## Layout
 
 | Path | What it is |
 | --- | --- |
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
-| \`music/\`, \`videos/\` | \`manifest.json\` lists each file and its R2 key. Large files go to R2 (\`npx --no-install homie-studio media put <file>\`), never into git. |
+| \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`, served from the site itself (files up to 25 MiB) or, for larger media, from the studio's storage once it has storage (see below; \`npx --no-install homie-studio media put <file>\`). Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | Markdown the studio publishes. |
 | \`site/\` | The studio's Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
 | \`studio.json\` | The studio's name, slug and Cloudflare resource names. |
@@ -87,11 +91,20 @@ studio's pinned copy, never a registry lookup of the bare name.
 - \`npm run build\` — bundle every game into \`site/dist\`.
 - \`npm run dev\` — the whole site locally (pages, the netplay relay in a local
   Durable Object, D1): open the printed address in two browsers and they share a room.
+  Stop it with \`npx --no-install homie-studio dev --stop\` (this studio's dev server only;
+  never \`pkill\` by name, which stops other projects' dev servers too).
 - \`npx --no-install homie-studio check <id> --url <site>\` — two headless browsers press Play and must
   land in the same room and finish a round. Run it before you say a game works.
-- \`npm run deploy\` — the site on this studio's Cloudflare (Workers, D1, R2).
+- \`npx --no-install homie-studio deploy --plan\` — says what deploy will create on Cloudflare and what it
+  costs, and changes nothing. Tell the person before the first deploy.
+- \`npm run deploy\` — the site on this studio's Cloudflare: one Worker, one D1 database, two
+  SQLite-backed Durable Objects, all on the free Workers plan (no payment method needed).
   If Wrangler is not signed in, run \`npx wrangler login\`: the person approves once in
   their browser. It never overwrites a Worker or database this studio did not create.
+- \`npx --no-install homie-studio storage add\` — only when the studio needs large media (songs,
+  videos): an R2 bucket for \`media put\`, served at \`/media/<key>\`. Cloudflare asks for a
+  payment method on the account before R2 works (its first 10 GB a month are free), so this
+  is a separate step the person agrees to; nothing else needs it.
 - \`npx --no-install homie-studio publish\` — list this studio's games in the homie.rocks directory
   (or call the Homie MCP tool \`studio_publish\`).
 
@@ -113,6 +126,12 @@ studio's pinned copy, never a registry lookup of the bare name.
   keychain. Never write a key, token or password into this repository.
 - Never touch a Cloudflare resource this studio did not create (\`studio.json\` says which).
 - Nothing in this studio needs \`~/.homie\` or a Homie box.
+
+## Beta
+
+Homie for studios is in beta. When something breaks, or a game you want to port does
+not fit, open an issue at https://github.com/homie-rocks/homie/issues/new/choose (a bug,
+a port request or a question). Leave keys, tokens and private addresses out of it.
 `;
 }
 
@@ -159,7 +178,10 @@ site/.wrangler/
 *.log
 # Port checks: receipts and screenshots of each run (games/<id>/.port/check-*/).
 games/*/.port/
-# Large media lives in this studio's R2; the manifests beside it are committed.
+# Large media lives in this studio's storage (R2, after storage add) or is served by the site; the manifests beside it are committed.
+# Working files of the music and video skills (frames, captures, provider answers) stay on this computer.
+music/**/work/
+videos/**/work/
 music/**/*.wav
 music/**/*.mp3
 music/**/*.flac
@@ -174,7 +196,8 @@ export function studioFiles({ name, slug, homie }) {
   const studio = {
     name, slug,
     homie: { studio: STUDIO_VERSION, directory: homie },
-    cloudflare: { worker, d1: `${slug}-db`, r2: `${slug}-media`, accountId: null, url: null, created: [] },
+    // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
+    cloudflare: { worker, d1: `${slug}-db`, r2: null, accountId: null, url: null, created: [] },
   };
   const pkg = {
     name: `${slug}-studio`,
@@ -191,12 +214,12 @@ export function studioFiles({ name, slug, homie }) {
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
     'games/README.md': 'One folder per game. Start one with `npx --no-install homie-studio game new <id> --from gem-rush`.\n',
-    'music/README.md': 'Songs and stems. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
-    'music/manifest.json': '{ "items": [] }\n',
-    'videos/README.md': 'Trailers and clips. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
-    'videos/manifest.json': '{ "items": [] }\n',
+    'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'music/manifest.json': '{ "v": 1, "items": [] }\n',
+    'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'videos/manifest.json': '{ "v": 1, "items": [] }\n',
     'posts/README.md': 'Markdown posts this studio publishes, one file each.\n',
-    'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1 and R2.
+    'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
@@ -254,7 +277,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     'npx --no-install homie-studio game new <id> --from gem-rush --name "<Game Name>"',
     'npm run dev   (then: npx --no-install homie-studio check <id> --url http://127.0.0.1:8787)',
     'npm run deploy   (then the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish)',
-  ] };
+  ], online: 'Going online creates one Worker, one D1 database and two Durable Objects on your own Cloudflare account: free plan, no payment method, no R2. `npx --no-install homie-studio deploy --plan` says exactly what, and changes nothing.' };
 }
 
 export const _test = { relative };

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', 'well-known', 'index', 'play', 'studio', 'studios']);
+const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);

package/media/MEDIA.md

@@ -0,0 +1,81 @@
+# Studio media: music/ and videos/
+
+A studio's songs, scores, loops, trailers, music videos and cutscenes live in the studio
+repository as folders plus one manifest per kind. The manifests are the contract between
+whatever made the media (the Homie plugin's `music` and `video` skills, or a person) and the
+studio site, which turns every published entry into a page:
+
+| Manifest | Page | Listed in |
+| --- | --- | --- |
+| `music/manifest.json` | `/music/<slug>/` (an audio player) | the home page, `/music/`, `/.well-known/homie-studio.json` `songs` |
+| `videos/manifest.json` | `/videos/<slug>/` (a video player) | the home page, `/videos/`, `/.well-known/homie-studio.json` `videos` |
+
+`homie-studio build` reads both manifests. `homie-studio media list` prints what the site will
+show and why anything is left out.
+
+## An entry
+
+```json
+{
+  "v": 1,
+  "items": [
+    {
+      "slug": "theme",
+      "kind": "song",
+      "title": "Night Owls Theme",
+      "blurb": "The studio's theme: a short sung hook over a driving synth line.",
+      "published": true,
+      "duration": 16.0,
+      "bpm": 120,
+      "key": "A minor",
+      "files": [
+        { "role": "audio", "path": "music/theme/theme.mp3", "type": "audio/mpeg" },
+        { "role": "cover", "path": "music/theme/cover.jpg", "type": "image/jpeg" },
+        { "role": "loop", "path": "music/theme/theme-loop.ogg", "type": "audio/ogg", "bars": 8 },
+        { "role": "master", "path": "music/theme/theme-master.wav", "type": "audio/wav", "public": false }
+      ],
+      "lyrics": "…",
+      "credits": "Music made with Eleven Music (ElevenLabs).",
+      "rights": { "provider": "elevenlabs", "plan": "creator", "commercial": true, "attribution": null },
+      "for": { "game": "crown-thief" },
+      "made": { "provider": "elevenlabs", "model": "music_v2", "at": "2026-09-30T02:00:00Z", "receipt": "music/theme/receipt.json" }
+    }
+  ]
+}
+```
+
+- The manifest's order is the site's order (the plugin's skills put a new entry first).
+- `slug`: lowercase letters, digits and hyphens, up to 40; it is the page address and never changes
+  once published. `title` is required for a page; an entry without `slug` and `title` is kept in
+  the manifest but gets no page.
+- `kind`: music is `song`, `score`, `loop`, `stem` or `sfx`; video is `trailer`, `music-video`,
+  `cutscene` or `clip`.
+- `published`: only `true` entries get a page and a directory listing. Work in progress stays
+  `false`.
+- `files[].role`: music uses `audio` (what the player plays), `cover`, `loop`, `stem`,
+  `master`; video uses `video` (the 16:9 cut the player plays), `vertical` (the 9:16 cut),
+  `poster`, `captions` (WebVTT), `master`. `"public": false` keeps a file off the site (masters,
+  raw captures). Loops and stems are offered for download on the song page, so another game can
+  use them.
+- `rights` and `credits` are shown on the page, in plain words. Say what the provider's terms
+  say for the plan the file was made on; nothing on the site claims more.
+
+## Where the bytes come from
+
+A studio needs no storage for songs and videos: the site serves them itself. For every public
+file of a published entry, the build picks the first that exists:
+
+1. `key`: the file is in the studio's storage, an R2 bucket that `homie-studio storage add`
+   creates (Cloudflare asks for a payment method on the account before R2 works, so the person
+   agrees first) and `homie-studio media put <file>` uploads to; the site serves it at
+   `/media/<key>`, with byte ranges so phones can seek.
+2. `path`: the file is in the studio folder; the build copies it into the site as `/<path>` when
+   it is 25 MiB or smaller (Cloudflare's limit for one static file), and the Worker answers byte
+   ranges for it too. This is the default, and it needs nothing but a deploy.
+3. `url`: an absolute `https://` address somewhere else.
+
+A file with none of these is left out and `media list` says so. Media never goes into git: the
+studio's `.gitignore` keeps `*.wav`, `*.mp3`, `*.flac`, `*.mp4`, `*.mov` and `*.webm` under
+`music/` and `videos/` out of the repository, so without storage the site is deployed from the
+computer that has the files. Keep deliveries under 25 MiB (the video skill's cuts do) or add
+storage for bigger ones.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.3.0",
-  "description": "A game studio on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects, D1, R2), deploy, and the homie.rocks directory.",
+  "version": "0.5.0",
+  "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), song and video pages from the music/ and videos/ manifests, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://homie.rocks/studio/",
@@ -36,6 +36,7 @@
     "port/",
     "worker/",
     "starters/",
+    "media/",
     "README.md",
     "LICENSE",
     "NOTICE"

package/worker/index.mjs

@@ -15,19 +15,22 @@
  *   /<game>/api/lobby          which public room to join (Lobby Durable Object)
  *   /api/games                 the catalogue plus live counts (D1 + Lobby)
  *   /.well-known/homie-studio.json   what the homie.rocks directory reads
- *   /media/<key>               the studio's large media, from R2 (when bound)
+ *   /music/, /music/<slug>/    the studio's songs, scores and loops (music/manifest.json)
+ *   /videos/, /videos/<slug>/  its trailers, music videos and cutscenes (videos/manifest.json)
+ *   /media/<key>               the studio's large media, from R2 (once `storage add` bound it), with byte ranges
  *
  * Bindings (site/wrangler.jsonc, written by `homie-studio new`): ASSETS (the
  * built site), TABLE and LOBBY (SQLite-backed Durable Objects, free plan
- * friendly), DB (D1: plays, finished rounds, the directory claim) and, when
- * the account has R2, MEDIA.
+ * friendly), DB (D1: plays, finished rounds, the directory claim) and, only
+ * after `homie-studio storage add` (R2 needs a payment method on the account),
+ * MEDIA. Everything else runs on Cloudflare's free Workers plan.
  *
  * The relay is the netplay contract's own room.mjs (NETPLAY.md v1 rev 2), run
  * unchanged inside the Table, so a game that plays in `homie-studio dev`
  * plays the same way here.
  */
 import { NetRoom } from './room.mjs';
-import { gamePage, homePage, notFoundPage, playPage } from './pages.mjs';
+import { gamePage, homePage, mediaIndexPage, notFoundPage, playPage, songPage, videoPage } from './pages.mjs';
 import { qrSvg } from './qr.mjs';
 
 const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -62,6 +65,71 @@ async function liveCounts(env, games) {
   return out;
 }
 
+const MEDIA_SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** `bytes=a-b`, `bytes=a-`, `bytes=-n` against a length, or null (a malformed or multi-range header is served whole). */
+function parseRange(header, size) {
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header ?? '').trim());
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  let start; let end;
+  if (m[1] === '') { const n = Number(m[2]); start = Math.max(0, size - n); end = size - 1; }
+  else { start = Number(m[1]); end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1); }
+  if (!(start <= end) || start >= size) return { unsatisfiable: true };
+  return { start, end };
+}
+
+/** A media file from the site's own assets, answering a byte range (phones seek audio and video with them). */
+async function assetWithRange(request, env, url) {
+  const res = await env.ASSETS.fetch(new Request(url.toString(), { method: 'GET' }));
+  const range = request.headers.get('range');
+  if (!res.ok || !range || res.status === 206) return res;
+  const body = new Uint8Array(await res.arrayBuffer());
+  const r = parseRange(range, body.byteLength);
+  const headers = new Headers(res.headers);
+  headers.set('accept-ranges', 'bytes');
+  if (!r) return new Response(body, { status: 200, headers });
+  if (r.unsatisfiable) { headers.set('content-range', `bytes */${body.byteLength}`); return new Response(null, { status: 416, headers }); }
+  headers.set('content-range', `bytes ${r.start}-${r.end}/${body.byteLength}`);
+  headers.set('content-length', String(r.end - r.start + 1));
+  return new Response(body.subarray(r.start, r.end + 1), { status: 206, headers });
+}
+
+/** A file from the studio's R2 bucket, with byte ranges. */
+async function mediaObject(request, env, key) {
+  const range = request.headers.get('range');
+  let head = null;
+  if (range) head = await env.MEDIA.head(key);
+  if (range && !head) return new Response('not found', { status: 404 });
+  const r = head ? parseRange(range, head.size) : null;
+  if (r?.unsatisfiable) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${head.size}` } });
+  const obj = await env.MEDIA.get(key, r ? { range: { offset: r.start, length: r.end - r.start + 1 } } : undefined);
+  if (!obj) return new Response('not found', { status: 404 });
+  const headers = new Headers();
+  obj.writeHttpMetadata(headers);
+  headers.set('etag', obj.httpEtag);
+  headers.set('cache-control', 'public, max-age=3600');
+  headers.set('accept-ranges', 'bytes');
+  if (r) {
+    headers.set('content-range', `bytes ${r.start}-${r.end}/${head.size}`);
+    headers.set('content-length', String(r.end - r.start + 1));
+    return new Response(obj.body, { status: 206, headers });
+  }
+  headers.set('content-length', String(obj.size));
+  return new Response(obj.body, { headers });
+}
+
+/** A catalogue media row as the directory reads it (absolute addresses). */
+function mediaRow(e, origin, kind) {
+  const abs = (u) => (u && u.startsWith('/') ? `${origin}${u}` : u ?? null);
+  const main = (e.files ?? []).find((f) => f.role === (kind === 'music' ? 'audio' : 'video'));
+  const art = (e.files ?? []).find((f) => f.role === (kind === 'music' ? 'cover' : 'poster'));
+  return {
+    slug: e.slug, kind: e.kind, title: e.title, blurb: e.blurb ?? '', duration: e.duration ?? null,
+    page: `${origin}/${kind}/${e.slug}/`, [kind === 'music' ? 'audio' : 'video']: abs(main?.url), [kind === 'music' ? 'cover' : 'poster']: abs(art?.url),
+    credits: e.credits ?? null, rights: e.rights ?? null, for: e.for ?? null,
+  };
+}
+
 /** The game's index.html with HOMIE_NET ahead of its modules, in the site's sandbox (an opaque origin). */
 async function gameDocument(request, env, url, game, meta) {
   const res = await env.ASSETS.fetch(new Request(`${url.origin}/games/${game}/index.html`));
@@ -124,6 +192,8 @@ export default {
           id: g.id, name: g.name, blurb: g.blurb ?? '', players: g.players ?? null, roundSeconds: g.roundSeconds ?? null,
           page: `${url.origin}/${g.id}/`, play: `${url.origin}/${g.id}/play`, cover: g.cover ? `${url.origin}/games/${g.id}/${g.cover}` : null,
         })),
+        songs: (cat.songs ?? []).map((e) => mediaRow(e, url.origin, 'music')),
+        videos: (cat.videos ?? []).map((e) => mediaRow(e, url.origin, 'videos')),
       }, 200, { 'access-control-allow-origin': '*' });
     }
     if (path === '/api/games') {
@@ -133,13 +203,26 @@ export default {
     if (path.startsWith('/media/')) {
       if (!env.MEDIA) return new Response('this studio keeps no media in R2 yet', { status: 404 });
       const key = decodeURIComponent(path.slice('/media/'.length));
-      const obj = await env.MEDIA.get(key);
-      if (!obj) return new Response('not found', { status: 404 });
-      const headers = new Headers();
-      obj.writeHttpMetadata(headers);
-      headers.set('etag', obj.httpEtag);
-      headers.set('cache-control', 'public, max-age=3600');
-      return new Response(obj.body, { headers });
+      if (!key || key.includes('..')) return new Response('not found', { status: 404 });
+      return mediaObject(request, env, key);
+    }
+    if (parts[0] === 'music' || parts[0] === 'videos') {
+      const kind = parts[0];
+      if (parts.length === 1 && !path.endsWith('/')) return Response.redirect(`${url.origin}/${kind}/`, 301);
+      const cat = await catalogue(env, url.origin);
+      if (parts.length === 1) return mediaIndexPage(cat, kind);
+      const slug = parts[1];
+      const list = (kind === 'music' ? cat.songs : cat.videos) ?? [];
+      const entry = MEDIA_SLUG.test(slug) ? list.find((e) => e.slug === slug) : null;
+      if (parts.length === 2) {
+        if (!entry) return notFoundPage(`No ${kind === 'music' ? 'song' : 'video'} called "${slug}" here.`);
+        if (!path.endsWith('/')) return Response.redirect(`${url.origin}/${kind}/${slug}/`, 301);
+        return kind === 'music' ? songPage(cat, entry, url.origin) : videoPage(cat, entry, url.origin);
+      }
+      if (parts.some((p) => p === '..')) return notFoundPage('Nothing here.');
+      const file = await assetWithRange(request, env, url);
+      if (file.status === 404) return notFoundPage('Nothing here.');
+      return file;
     }
     if (path === '/' || path === '/index.html') {
       const cat = await catalogue(env, url.origin);