feat(catalog): emit schemaVersion, thumbnailUrl, and per-item media specs (#71)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tallnato

SCHEMA.md

@@ -47,10 +47,12 @@ content/_<category>/<slug>.md      # front matter — sits BESIDE the folder, no
 
 `npm run build` emits (into the gitignored `public/api/`, copied to `/api/` at deploy):
 
-- **`catalog.json`** — `{ generatedAt, totalItems, lightshows[], locksounds[], boombox[], wraps[], hornsounds[] }`
-- **`<category>.json`** — `{ category, totalItems, items[] }`
+- **`catalog.json`** — `{ schemaVersion, generatedAt, totalItems, lightshows[], locksounds[], boombox[], wraps[], hornsounds[] }`
+- **`<category>.json`** — `{ schemaVersion, category, totalItems, items[] }`
 - **`tags.json`** — `{ totalTags, tags: { <tag>: ["<category>/<slug>", …] } }`
 
+`schemaVersion` (currently **`1`**) is a top-level integer on `catalog.json` and each `<category>.json`. It is bumped whenever the emitted JSON shape changes so the app can gate parsing of newer optional fields. The current contract is version 1 (adds `thumbnailUrl` + `specs` to each item).
+
 Each **item**:
 ```jsonc
 {
@@ -61,14 +63,35 @@ Each **item**:
   "description": "…",
   "tags": ["rock", "synchronized"],
   "thumbnail": null,                 // string filename for wraps, else null
+  "thumbnailUrl": null,              // root-relative URL when thumbnail set, else null
   "files": [                         // derived from declared meta.files ∩ disk
     { "name": "…​.fseq", "downloadUrl": "/Volts/content/lightshows/<slug>/<slug>.fseq" }
   ],
+  "specs": {                         // best-effort media specs, all fields nullable
+    "channels": 0,
+    "sampleRate": null,
+    "durationSeconds": 0.025
+  },
   "meta": { /* full front matter; meta.files[] also gets downloadUrl + keeps label */ }
 }
 ```
 
+### `thumbnailUrl`
+When front matter declares `thumbnail`, `build.ts` emits a root-relative `thumbnailUrl` of `<baseurl>/content/<category>/<slug>/<thumbnail>` — the **same convention and `/Volts` prefix as `files[].downloadUrl`**. When no `thumbnail` is declared it is `null`. The raw `thumbnail` field (bare filename or `null`) is kept as-is alongside it.
+
+### `specs` (best-effort, nullable)
+`specs` is parsed best-effort from an item's binaries. **Every field is nullable and the build never throws on a malformed/stub asset** — today's committed fixtures are tiny placeholder stubs, so expect `null` (or degenerate) values until real assets land. Shape: `{ channels, sampleRate, durationSeconds }`.
+
+| Category | Source binary | `channels` | `sampleRate` | `durationSeconds` |
+|---|---|---|---|---|
+| `lightshows` | `.fseq` (FSEQ v2.x, `PSEQ` magic) | `channelCount` (uint32 @10) | `null` | `frameCount`(@14) × `stepTime`(@18) / 1000 |
+| `locksounds`, `hornsounds`, `boombox`, any `.wav` | first `.wav` (RIFF chunk-walk) | `fmt ` channels | `fmt ` sampleRate | `data` size / (`sampleRate` × `channels` × `bitsPerSample`/8) |
+| mp3-only items (and items with no parseable binary) | — | `null` | `null` | `null` |
+
+MP3 is intentionally **not** parsed (variable bitrate makes header-derived duration/sampleRate unreliable), so an mp3-only item yields all-`null` specs. Any parse failure (bad magic, truncated stub, missing chunk) also yields `null` for the affected field(s).
+
 **Cross-repo invariants (do not break without updating the app):**
 1. The five **category key names** are fixed. A new category is silently ignored by the app until it ships an update (`CatalogApi.kt` has a hardcoded `CATEGORY_KEYS`).
-2. `downloadUrl` is **root-relative and includes the `/Volts` prefix** (driven by `_config.yml`'s `baseurl`). The app resolves it against the host only (`https://natobytes.com`). Changing `baseurl` breaks the app's URL resolution.
+2. `downloadUrl` (and `thumbnailUrl`) is **root-relative and includes the `/Volts` prefix** (driven by `_config.yml`'s `baseurl`). The app resolves it against the host only (`https://natobytes.com`). Changing `baseurl` breaks the app's URL resolution.
 3. `meta.files[].label` is relied on by the app for display.
+4. `schemaVersion`, `thumbnailUrl`, and `specs` are **additive** (version 1). They don't displace any existing field, and `specs` values are best-effort/nullable — the app must tolerate `null` for any spec.

scripts/build.ts

@@ -26,6 +26,10 @@ const CATEGORIES = [
   "hornsounds",
 ];
 
+// Bumped whenever the emitted JSON shape changes in a way the app should know
+// about. The app may read this to gate parsing of newer optional fields.
+const SCHEMA_VERSION = 1;
+
 interface ItemMeta {
   title: string;
   author?: string;
@@ -40,6 +44,15 @@ interface FileEntry {
   downloadUrl: string;
 }
 
+// Best-effort media specs parsed from an item's binaries. Every field is
+// nullable: today's fixtures are placeholder stubs, so most values are null,
+// and any parse failure leaves the relevant field null rather than throwing.
+interface ItemSpecs {
+  channels: number | null;
+  sampleRate: number | null;
+  durationSeconds: number | null;
+}
+
 interface CatalogItem {
   slug: string;
   category: string;
@@ -48,7 +61,9 @@ interface CatalogItem {
   description: string;
   tags: string[];
   thumbnail: string | null;
+  thumbnailUrl: string | null;
   files: FileEntry[];
+  specs: ItemSpecs;
   meta: ItemMeta;
 }
 
@@ -75,6 +90,126 @@ function urlFor(baseUrl: string, category: string, slug: string, name: string):
   return `${baseUrl}/content/${category}/${slug}/${name}`;
 }
 
+// --- Best-effort media-spec parsing ----------------------------------------
+//
+// These helpers crack open an item's binaries to surface display specs
+// (channels / sampleRate / durationSeconds). They mirror the magic-byte
+// approach in scripts/validate.ts, but here every parse is wrapped in a
+// try/catch and returns nulls on ANY failure: the committed fixtures are
+// tiny placeholder stubs (e.g. a 36-byte .fseq), so a header read may be
+// truncated or nonsensical. We must NEVER throw — a malformed asset should
+// just yield null specs, not break the whole catalog build.
+
+const EMPTY_SPECS: ItemSpecs = {
+  channels: null,
+  sampleRate: null,
+  durationSeconds: null,
+};
+
+function matches(buf: Buffer, ascii: string, offset = 0): boolean {
+  if (buf.length < offset + ascii.length) return false;
+  for (let i = 0; i < ascii.length; i++) {
+    if (buf[offset + i] !== ascii.charCodeAt(i)) return false;
+  }
+  return true;
+}
+
+// FSEQ v2.x light-show sequence ("PSEQ" magic). Per the Tesla/xLights layout:
+//   offset 0  : "PSEQ" magic
+//   offset 10 : uint32 LE channelCount
+//   offset 14 : uint32 LE frameCount
+//   offset 18 : uint8     stepTime (ms per frame)
+// durationSeconds = frameCount * stepTime / 1000.
+function parseFseqSpecs(filePath: string): ItemSpecs {
+  try {
+    const buf = fs.readFileSync(filePath);
+    if (!matches(buf, "PSEQ")) return EMPTY_SPECS;
+    if (buf.length < 19) return EMPTY_SPECS;
+    const channelCount = buf.readUInt32LE(10);
+    const frameCount = buf.readUInt32LE(14);
+    const stepTime = buf.readUInt8(18);
+    return {
+      channels: channelCount,
+      sampleRate: null,
+      durationSeconds: (frameCount * stepTime) / 1000,
+    };
+  } catch {
+    return EMPTY_SPECS;
+  }
+}
+
+// WAV (RIFF/WAVE). Walk the chunk list to find `fmt ` (sampleRate, channels,
+// bitsPerSample) and `data` (byte size), then derive duration for PCM:
+//   durationSeconds = dataSize / (sampleRate * channels * bitsPerSample / 8).
+function parseWavSpecs(filePath: string): ItemSpecs {
+  try {
+    const buf = fs.readFileSync(filePath);
+    if (!matches(buf, "RIFF") || !matches(buf, "WAVE", 8)) return EMPTY_SPECS;
+
+    let sampleRate: number | null = null;
+    let channels: number | null = null;
+    let bitsPerSample: number | null = null;
+    let dataSize: number | null = null;
+
+    // Chunks start after "RIFF"(4) + size(4) + "WAVE"(4) = offset 12.
+    let off = 12;
+    while (off + 8 <= buf.length) {
+      const id = buf.toString("ascii", off, off + 4);
+      const size = buf.readUInt32LE(off + 4);
+      const body = off + 8;
+      if (id === "fmt " && body + 16 <= buf.length) {
+        channels = buf.readUInt16LE(body + 2);
+        sampleRate = buf.readUInt32LE(body + 4);
+        bitsPerSample = buf.readUInt16LE(body + 14);
+      } else if (id === "data") {
+        dataSize = size;
+      }
+      // Chunks are word-aligned: an odd size carries a trailing pad byte.
+      off = body + size + (size % 2);
+    }
+
+    let durationSeconds: number | null = null;
+    if (
+      dataSize !== null &&
+      sampleRate &&
+      channels &&
+      bitsPerSample &&
+      sampleRate > 0 &&
+      channels > 0 &&
+      bitsPerSample > 0
+    ) {
+      durationSeconds = dataSize / (sampleRate * channels * (bitsPerSample / 8));
+    }
+
+    return { channels, sampleRate, durationSeconds };
+  } catch {
+    return EMPTY_SPECS;
+  }
+}
+
+// Picks the binary worth probing for an item and returns its specs. Lightshows
+// are described by their .fseq; the audio categories by their .wav. MP3 is
+// intentionally left unparsed (VBR makes duration/sampleRate unreliable from a
+// header read), so an mp3-only item yields all-null specs. Any item with no
+// parseable binary also yields all-null specs.
+function buildSpecs(category: string, itemDir: string, files: FileEntry[]): ItemSpecs {
+  const find = (ext: string): string | null => {
+    const hit = files.find((f) => path.extname(f.name).toLowerCase() === ext);
+    return hit ? path.join(itemDir, hit.name) : null;
+  };
+
+  if (category === "lightshows") {
+    const fseq = find(".fseq");
+    return fseq ? parseFseqSpecs(fseq) : EMPTY_SPECS;
+  }
+
+  // locksounds / hornsounds / boombox (and anything else that ships a .wav).
+  const wav = find(".wav");
+  if (wav) return parseWavSpecs(wav);
+
+  return EMPTY_SPECS;
+}
+
 // Build the catalog's top-level files[] from the DECLARED meta.files (the
 // contract the app consumes), intersected with what's actually on disk. Falls
 // back to a disk glob only when an item declares no files, and warns loudly on
@@ -158,15 +293,22 @@ function buildCatalog(): CatalogItem[] {
         console.warn(`  ! ${category}/${slug}: missing "author" — defaulting to "Unknown"`);
       }
 
+      const thumbnail = typeof meta.thumbnail === "string" ? meta.thumbnail : null;
+      const files = buildFiles(meta, itemDir, baseUrl, category, slug);
+
       items.push({
         slug,
         category,
         title: meta.title || slug,
         author: meta.author || "Unknown",
         description: meta.description || "",
         tags: Array.isArray(meta.tags) ? meta.tags : [],
-        thumbnail: typeof meta.thumbnail === "string" ? meta.thumbnail : null,
-        files: buildFiles(meta, itemDir, baseUrl, category, slug),
+        thumbnail,
+        // Root-relative, same convention as files[].downloadUrl; null when no
+        // thumbnail is declared in front matter.
+        thumbnailUrl: thumbnail ? urlFor(baseUrl, category, slug, thumbnail) : null,
+        files,
+        specs: buildSpecs(category, itemDir, files),
         meta,
       });
     }
@@ -212,6 +354,7 @@ function main(): void {
 
   // Full catalog — grouped by category
   const catalog: Record<string, unknown> = {
+    schemaVersion: SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
     totalItems: items.length,
   };
@@ -224,6 +367,7 @@ function main(): void {
   for (const category of CATEGORIES) {
     const categoryItems = items.filter((i) => i.category === category);
     writeJSON(path.join(OUTPUT_DIR, `${category}.json`), {
+      schemaVersion: SCHEMA_VERSION,
       category,
       totalItems: categoryItems.length,
       items: categoryItems,