@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/library/StockSounds.tsx

@@ -0,0 +1,390 @@
+// The Library's Stock sounds: free sounds from Openverse (Freesound effects,
+// Jamendo music), searched from this browser, auditioned, then added to the
+// open Shot or pinned to the board. It fills the catalog column AND the
+// preview column, so the search, the list and the picked sound share one
+// piece of state and nothing about them reaches the store until an add.
+//
+// ONLY SOUNDS A VIDEO MAY USE are listed: CC0, the public domain and CC BY
+// (`OPENVERSE_LICENSES`). The search asks for those, the list drops anything
+// else, and the host refuses anything else again at the add, so the credit a
+// CC BY sound owes is always recorded where every export reads it.
+//
+// ONE AUDITION AT A TIME through one `Audio` element, following the tab's
+// monitor settings, as the pack panel does (`LibrarySoundPanel`).
+import { useEffect, useRef, useState } from "react";
+import type { FormEvent } from "react";
+import { SegmentedControl } from "@dailies-studio/ui";
+import {
+  openverseSiteOf,
+  creditLineOf,
+  creditRequired,
+  licenseLabel,
+  openverseSourceOf,
+} from "@dailies-studio/shot/doc";
+import type { OpenverseRow, OpenverseSoundKind } from "@dailies-studio/shot/doc";
+import { openverseStatus } from "../../api.js";
+import { ADD_ICON, PLAY_ICON, SEARCH_ICON, STOP_ICON } from "../../icons.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { openBoardForPin, placeInShotRefusal } from "../../state/store.js";
+import { formatDuration } from "../timeline/model.js";
+import { SoundWave } from "./LibrarySoundPanel.js";
+import { STOCK_LENGTHS, StockSearchError, lengthLabel, searchStock, withinLength } from "./stockSearch.js";
+
+type Status = { kind: "idle" } | { kind: "loading" } | { kind: "error"; message: string } | { kind: "done" };
+
+const KIND_WORDS: Record<OpenverseSoundKind, string> = { sfx: "Effects", music: "Music" };
+
+/** Why this host cannot add a stock sound: a hosted deployment with no
+ *  registered Openverse app. Searching and listening still work. */
+const NOT_SET_UP = "Adding stock sounds is not set up on this server yet. You can still search and listen.";
+
+export function StockSounds({ canAdd }: { canAdd: boolean }) {
+  const store = useStore();
+  const muted = useShotEditor((s) => s.previewMuted);
+  const volume = useShotEditor((s) => s.previewVolume);
+  const placeRefusal = useShotEditor((s) => placeInShotRefusal(s, "sound"));
+  const boardOpen = useShotEditor((s) => s.storyboardOpen);
+  const [draft, setDraft] = useState("");
+  const [kind, setKind] = useState<OpenverseSoundKind>("sfx");
+  const [maxSeconds, setMaxSeconds] = useState<number | null>(null);
+  const [searched, setSearched] = useState<{ query: string; kind: OpenverseSoundKind } | null>(null);
+  const [rows, setRows] = useState<OpenverseRow[]>([]);
+  const [page, setPage] = useState({ page: 0, pageCount: 0 });
+  const [status, setStatus] = useState<Status>({ kind: "idle" });
+  const [picked, setPicked] = useState<string | null>(null);
+  const [playing, setPlaying] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const audio = useRef<HTMLAudioElement | null>(null);
+  // The newest search wins: an older answer that lands late is dropped.
+  const ticket = useRef(0);
+  // Whether this host can add one. Unknown until asked, and a failed ask
+  // leaves the buttons on: the add itself then says what went wrong.
+  const [settable, setSettable] = useState(true);
+  useEffect(() => {
+    let alive = true;
+    void openverseStatus().then(
+      (status) => {
+        if (alive) setSettable(status.imports);
+      },
+      () => {},
+    );
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  useEffect(
+    () => () => {
+      audio.current?.pause();
+      audio.current = null;
+    },
+    [],
+  );
+  useEffect(() => {
+    if (audio.current === null) return;
+    audio.current.muted = muted;
+    audio.current.volume = volume;
+  }, [muted, volume]);
+
+  const run = (query: string, forKind: OpenverseSoundKind, nextPage: number): void => {
+    const mine = ++ticket.current;
+    setStatus({ kind: "loading" });
+    void searchStock(query, forKind, nextPage)
+      .then((answer) => {
+        if (mine !== ticket.current) return;
+        setRows((held) => (nextPage === 1 ? answer.rows : [...held, ...answer.rows.filter((r) => !held.some((h) => h.id === r.id))]));
+        setPage({ page: answer.page, pageCount: answer.pageCount });
+        setStatus({ kind: "done" });
+      })
+      .catch((e: unknown) => {
+        if (mine !== ticket.current) return;
+        setStatus({ kind: "error", message: e instanceof StockSearchError ? e.message : "The search failed. Try again." });
+      });
+  };
+
+  const submit = (event?: FormEvent): void => {
+    event?.preventDefault();
+    const query = draft.trim();
+    if (query === "") return;
+    setSearched({ query, kind });
+    setPicked(null);
+    run(query, kind, 1);
+  };
+
+  const pickKind = (next: OpenverseSoundKind): void => {
+    setKind(next);
+    setMaxSeconds(null);
+    // A kind is a different site, so a standing search is asked again there.
+    if (searched !== null) {
+      setSearched({ query: searched.query, kind: next });
+      setPicked(null);
+      run(searched.query, next, 1);
+    }
+  };
+
+  const shown = withinLength(rows, maxSeconds);
+  const selected = shown.find((row) => row.id === picked) ?? shown[0] ?? null;
+
+  const stop = (): void => {
+    audio.current?.pause();
+    audio.current = null;
+    setPlaying(null);
+  };
+  const audition = (row: OpenverseRow): void => {
+    setPicked(row.id);
+    if (playing === row.id) {
+      stop();
+      return;
+    }
+    audio.current?.pause();
+    const el = new Audio(row.url);
+    el.muted = muted;
+    el.volume = volume;
+    const done = (): void => {
+      if (audio.current !== el) return;
+      audio.current = null;
+      setPlaying(null);
+    };
+    el.addEventListener("ended", done);
+    el.addEventListener("error", done);
+    audio.current = el;
+    setPlaying(row.id);
+    void el.play().catch(done);
+  };
+
+  const act = (row: OpenverseRow, mode: "place" | "pin"): void => {
+    if (mode === "pin" && !openBoardForPin(store)) return;
+    setBusy(true);
+    setError(null);
+    store.dismissError();
+    void store
+      .addStockSound(row.id, mode)
+      .then(() => {
+        const message = store.getState().error;
+        if (message !== null) setError(message);
+        else if (mode === "place" && store.getState().libraryBrowserOpen) store.setLibraryBrowserOpen(false);
+      })
+      .finally(() => setBusy(false));
+  };
+
+  // Further pages, whenever there are any: a page whose rows all fall
+  // outside the length, or the policy, is not the end of the search.
+  const more =
+    searched !== null && page.page < page.pageCount ? (
+      <button
+        type="button"
+        className="btn is-outline"
+        data-testid="stock-more"
+        disabled={status.kind === "loading"}
+        onClick={() => run(searched.query, searched.kind, page.page + 1)}
+      >
+        {status.kind === "loading" ? "Loading…" : "Load more"}
+      </button>
+    ) : null;
+  let body;
+  if (status.kind === "idle") {
+    body = (
+      <p className="library-preview-note" role="status">
+        Search Freesound effects or Jamendo music. Only sounds you may use in a video are listed: CC0, public domain and CC BY.
+      </p>
+    );
+  } else if (status.kind === "loading" && rows.length === 0) {
+    body = <p className="library-preview-note" role="status">Searching Openverse…</p>;
+  } else if (status.kind === "error" && rows.length === 0) {
+    body = (
+      <p className="library-preview-error" role="alert" data-testid="stock-error">
+        {status.message}
+      </p>
+    );
+  } else if (shown.length === 0) {
+    body = (
+      <>
+        <p className="library-preview-note" role="status">
+          {rows.length === 0
+            ? more === null
+              ? `No free ${KIND_WORDS[kind].toLowerCase()} match ${JSON.stringify(searched?.query ?? "")}. Try other words.`
+              : "Nothing on this page may be used in a video. Load more to look further."
+            : `None of these is ${lengthLabel(maxSeconds).toLowerCase()}.`}
+        </p>
+        {more}
+      </>
+    );
+  } else {
+    body = (
+      <>
+        <ul className="library-sound-list" aria-label="Stock sounds" data-testid="stock-list">
+          {shown.map((row) => {
+            const live = playing === row.id;
+            const on = row === selected;
+            return (
+              <li key={row.id} className={on ? "library-sound-row is-selected" : "library-sound-row"} data-id={row.id}>
+                <button type="button" className="library-sound-play" aria-label={live ? `Stop ${row.title}` : `Play ${row.title}`} onClick={() => audition(row)}>
+                  {live ? STOP_ICON : PLAY_ICON}
+                </button>
+                <button type="button" className="library-sound-pick" aria-pressed={on} onClick={() => setPicked(row.id)}>
+                  <span className="library-sound-name">
+                    {row.title}
+                    {row.creator === null ? null : <span className="stock-sound-creator"> · {row.creator}</span>}
+                  </span>
+                  <span className="stock-sound-license">{licenseLabel(row.license, "")}</span>
+                  <span className="library-sound-length">{formatDuration((row.durationMs ?? 0) / 1000)}</span>
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+        {status.kind === "error" ? (
+          <p className="library-preview-error" role="alert">
+            {status.message}
+          </p>
+        ) : null}
+        {more}
+      </>
+    );
+  }
+
+  const source = selected === null ? null : openverseSourceOf(selected);
+  const site = selected === null ? null : openverseSiteOf(selected.source);
+
+  return (
+    <>
+      <section className="library-catalog" aria-label="Stock sounds" data-testid="stock-sounds">
+        <header className="library-catalog-head">
+          <div>
+            <h2>Stock sounds</h2>
+            <p>Free sounds from Openverse, safe to use in a video.</p>
+          </div>
+        </header>
+        <form className="library-search-row" role="search" onSubmit={submit}>
+          {/* Searched on Enter, never per key: each search spends the
+              person's own Openverse allowance. */}
+          <label className="search-field">
+            {SEARCH_ICON}
+            <input
+              type="search"
+              value={draft}
+              placeholder={kind === "sfx" ? "Search effects, then press Enter" : "Search music, then press Enter"}
+              aria-label="Search stock sounds"
+              data-testid="stock-search"
+              onChange={(event) => setDraft(event.target.value)}
+            />
+          </label>
+          <select
+            className="select is-quiet"
+            aria-label="Length"
+            data-testid="stock-length"
+            value={maxSeconds === null ? "" : String(maxSeconds)}
+            onChange={(event) => setMaxSeconds(event.target.value === "" ? null : Number(event.target.value))}
+          >
+            {STOCK_LENGTHS[kind].map((s) => (
+              <option key={s ?? "any"} value={s === null ? "" : String(s)}>
+                {lengthLabel(s)}
+              </option>
+            ))}
+          </select>
+        </form>
+        <SegmentedControl
+          ariaLabel="Kind of sound"
+          className="stock-kind"
+          value={kind}
+          options={[
+            { value: "sfx", label: "Effects", testId: "stock-kind-sfx" },
+            { value: "music", label: "Music", testId: "stock-kind-music" },
+          ]}
+          onChange={(next) => pickKind(next as OpenverseSoundKind)}
+        />
+        {body}
+      </section>
+      <aside className="library-preview is-sounds" aria-label="Preview: stock sound" data-testid="stock-preview">
+        {selected === null || source === null ? (
+          <p className="library-preview-empty">Pick a sound to preview it here.</p>
+        ) : (
+          <>
+            <div className="library-preview-purpose">
+              <h2 className="library-preview-name">{selected.title}</h2>
+              <p className="library-preview-note">
+                {selected.creator === null ? "" : `by ${selected.creator} · `}
+                {site?.name ?? selected.source} · {formatDuration((selected.durationMs ?? 0) / 1000)}
+              </p>
+            </div>
+            <div className="library-sound-selected" data-testid="stock-selected">
+              {/* Jamendo's files carry no CORS header, so their envelope
+                  cannot be read here: the well stays empty, the audition
+                  still plays. */}
+              {/* Drawn once the person picks or plays the row, never for the
+                  one shown first: drawing it fetches the file from Freesound. */}
+              {selected.source === "freesound" && (picked === selected.id || playing === selected.id) ? (
+                <SoundWave url={selected.url} />
+              ) : null}
+              <p className="stock-sound-terms" data-testid="stock-license">
+                <strong>{licenseLabel(source.license, source.licenseVersion)}</strong>
+                {creditRequired(source.license)
+                  ? " · Credit required. Dailies keeps the line and puts it in your export."
+                  : " · No credit needed."}
+              </p>
+              <p className="stock-sound-credit" data-testid="stock-credit">
+                {creditLineOf(source)}
+              </p>
+              <a className="stock-sound-link" href={selected.landingUrl} target="_blank" rel="noopener noreferrer">
+                Open on {site?.name ?? selected.source}
+              </a>
+              <button
+                type="button"
+                className="btn is-primary is-lg"
+                data-testid="stock-add"
+                disabled={!canAdd || busy || !settable}
+                aria-disabled={placeRefusal !== null || undefined}
+                title={
+                  !settable
+                    ? NOT_SET_UP
+                    : !canAdd
+                      ? "Open a Project to add sounds."
+                      : (placeRefusal ?? "Add this sound at the playhead of the open Shot.")
+                }
+                onClick={() => {
+                  if (placeRefusal === null) act(selected, "place");
+                }}
+              >
+                {ADD_ICON}
+                {busy ? "Adding…" : "Add to shot"}
+              </button>
+              <button
+                type="button"
+                className="btn is-outline is-lg"
+                data-testid="stock-pin"
+                disabled={!canAdd || busy || !settable}
+                title={
+                  !settable
+                    ? NOT_SET_UP
+                    : canAdd
+                      ? `Add this sound and pin it as a card the agent reads.${boardOpen ? "" : " Opens the storyboard."}`
+                      : "Open a Project to add sounds."
+                }
+                onClick={() => act(selected, "pin")}
+              >
+                Pin to board
+              </button>
+              {error === null ? null : (
+                <p className="library-preview-error" role="alert" data-testid="stock-add-error">
+                  {error}
+                </p>
+              )}
+              <p className="library-preview-hint" data-testid="stock-hint">
+                {!settable
+                  ? NOT_SET_UP
+                  : selected.source === "freesound"
+                  ? "Freesound shares a preview-quality MP3, which is what is added."
+                  : "Add places it in the open Shot. Pin saves it for later."}
+              </p>
+            </div>
+          </>
+        )}
+        <footer className="library-preview-meta">
+          <span>Openverse</span>
+          <span>{KIND_WORDS[kind]}</span>
+        </footer>
+      </aside>
+    </>
+  );
+}

package/src/panels/library/libraryModel.ts

@@ -0,0 +1,147 @@
+// What the Library browse surface shows, as pure functions over catalog rows:
+// which rows, in which order, under which heading, and the words around them.
+// No React and no store, so every rule here is one unit test away.
+import { libraryDisplayName } from "@dailies-studio/shot/doc";
+import type { ReferenceItem3D } from "@dailies-studio/shot/doc";
+import type { LibraryItem, LibraryItemKind } from "../../api.js";
+import { matchesLibraryItem } from "../../state/storyboardModel.js";
+
+/** A rail row: one catalog kind, every kind at once, or Stock sounds, which
+ *  is no catalog kind: Openverse's free sounds, searched from the browser
+ *  (`StockSounds`). */
+export type LibraryCategory = "all" | LibraryItemKind | "stock" | "generated";
+
+/** The rail, top to bottom. Components lead because a row with no `kind` is
+ *  one (the registry's own default) and it is the kind an author reaches for
+ *  first; the rest follow the order the library skill introduces them. */
+export const LIBRARY_KINDS: readonly LibraryItemKind[] = ["component", "blueprint", "material", "shot", "images", "sounds"];
+export const LIBRARY_CATEGORIES: readonly LibraryCategory[] = ["all", ...LIBRARY_KINDS, "stock", "generated"];
+
+export const CATEGORY_LABEL: Record<LibraryCategory, string> = {
+  all: "All items",
+  component: "Components",
+  blueprint: "Blueprints",
+  material: "Materials",
+  shot: "Shots",
+  images: "Images",
+  sounds: "Sounds",
+  stock: "Stock sounds",
+  generated: "Generated sounds",
+};
+
+/** The sentence under each catalog heading. Components and Sounds are Paper's
+ *  own words; the rest are written to the same pattern: what the kind is for,
+ *  in one line, with no product jargon. */
+export const CATEGORY_SUBTITLE: Record<LibraryCategory, string> = {
+  all: "Everything this build ships, one kind at a time.",
+  component: "Ready-made pieces of motion. Preview one, then make it yours.",
+  blueprint: "Step-by-step builds to follow inside a shot.",
+  material: "Surfaces that give a model its look.",
+  shot: "Finished shots to learn from or build on.",
+  images: "Picture packs to bring into this Project.",
+  sounds: "Find the sound that makes a moment land.",
+  stock: "Free sounds from Openverse, safe to use in a video.",
+  generated: "Generated sounds you can open: every one added to a Project, and the rest for a day.",
+};
+
+/** A sound pack is counted as a pack, not an item: what the author picks
+ *  there is one sound out of it, so "12 items" would promise twelve sounds. */
+export const countNoun = (category: LibraryCategory): "item" | "pack" => (category === "sounds" ? "pack" : "item");
+
+/** "1 item", "2 items", "0 items". */
+export function plural(n: number, noun: string): string {
+  return `${n} ${n === 1 ? noun : `${noun}s`}`;
+}
+
+export const kindOf = (row: LibraryItem): LibraryItemKind => row.kind ?? "component";
+
+/** Whether Add places this row as a layer: a component, and only a three
+ *  host can be an instance layer (`instanceHostRefusal`). The rest pin. */
+export const placesAsLayer = (row: LibraryItem): boolean => kindOf(row) === "component" && row.host === "three";
+
+/** The name a card prints. ONE helper for the whole surface, shared with the
+ *  CLI (`libraryDisplayName` in @dailies-studio/shot/doc): the manifest's
+ *  `displayName` when the server sends one, else the code name in sentence
+ *  case (`SelectionLoop` -> "Selection loop"). */
+export const displayNameOf = (row: LibraryItem): string => libraryDisplayName(row);
+
+export type LibrarySort = "curated" | "name";
+
+export const SORT_LABEL: Record<LibrarySort, string> = { curated: "Curated", name: "Name" };
+
+/** The search box's rule: every field the old cards printed and the id
+ *  (`matchesLibraryItem`), plus the printed name, which is no longer `name`. */
+export function matchesQuery(row: LibraryItem, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  return q === "" || matchesLibraryItem(row, q) || displayNameOf(row).toLowerCase().includes(q);
+}
+
+/**
+ * The rows one category shows, searched and sorted. "Curated" is the
+ * catalog's own order, which is the order the build ships them in and the
+ * only order anyone chose; "Name" sorts by the PRINTED name, so the list
+ * reads alphabetically on screen rather than by code name.
+ */
+export function visibleRows(
+  rows: readonly LibraryItem[],
+  category: LibraryCategory,
+  query: string,
+  sort: LibrarySort,
+): LibraryItem[] {
+  const out = rows.filter((row) => (category === "all" || kindOf(row) === category) && matchesQuery(row, query));
+  if (sort === "name") {
+    out.sort((a, b) => displayNameOf(a).localeCompare(displayNameOf(b), undefined, { sensitivity: "base" }));
+  }
+  return out;
+}
+
+/** "All items" as sections, one per kind in rail order, empty kinds left
+ *  out so a search does not print a column of empty headings. */
+export function groupByKind(rows: readonly LibraryItem[]): Array<{ kind: LibraryItemKind; rows: LibraryItem[] }> {
+  return LIBRARY_KINDS.map((kind) => ({ kind, rows: rows.filter((row) => kindOf(row) === kind) })).filter(
+    (section) => section.rows.length > 0,
+  );
+}
+
+/** Rows per rail category, "all" included. Stock sounds has no count: its
+ *  rows are a search away, never a list this build holds. */
+export function categoryCounts(rows: readonly LibraryItem[]): Map<LibraryCategory, number> {
+  const out = new Map<LibraryCategory, number>(["all" as const, ...LIBRARY_KINDS].map((c) => [c, 0]));
+  for (const row of rows) {
+    const k = kindOf(row);
+    out.set(k, (out.get(k) ?? 0) + 1);
+  }
+  out.set("all", rows.length);
+  return out;
+}
+
+/**
+ * The rows the Library shows: `source === "shipped"` and NOT `!== "builtin"`.
+ * The catalog concatenates three lists and the third is `shared`: a component
+ * vendored from a library this build does not ship, which carries no kind, no
+ * tags, no thumb and no docs. A shared row has nothing to draw on a card and
+ * nothing to pick, and the loose filter would have put every one of them in
+ * front of the author. ONE filter for the browser and the shot board's
+ * component picker (its Dailies Library section).
+ */
+export function shippedRows(catalog: readonly LibraryItem[]): LibraryItem[] {
+  return catalog.filter((row) => row.source === "shipped");
+}
+
+/**
+ * HOW MANY CARDS ON THE BOARD CITE EACH ROW, by item id. A component card
+ * names the registry id the install made (`installedAs`), every other kind
+ * names the item itself.
+ */
+export function onBoardCounts(
+  shipped: readonly LibraryItem[],
+  references: readonly ReferenceItem3D[],
+): Map<string, number> {
+  const byComponent = new Map(shipped.flatMap((row) => (row.installedAs === undefined ? [] : [[row.installedAs, row.id]])));
+  const out = new Map<string, number>();
+  for (const ref of references) {
+    const id = ref.type === "library" ? ref.library : ref.type === "component" && ref.component !== undefined ? byComponent.get(ref.component) : undefined;
+    if (id !== undefined) out.set(id, (out.get(id) ?? 0) + 1);
+  }
+  return out;
+}

package/src/panels/library/stockSearch.ts

@@ -0,0 +1,77 @@
+// The Library's Stock sounds search, run from this browser straight to
+// Openverse, the way openverse.org itself runs: each person spends their own
+// anonymous allowance (20 searches a minute, 200 a day), so one busy
+// workspace never uses up another's. The editor sends nothing but the words
+// typed: no cookie (`credentials: "omit"`) and no page address
+// (`referrerPolicy: "no-referrer"`).
+//
+// Adding a sound never trusts this answer. The add names the row's id, and
+// the host reads the row again itself before it stores a byte or records a
+// license (`/api/openverse/add`).
+import { fitsSeconds, openverseRowRefusal, openverseSearchUrl, parseOpenverseRow } from "@dailies-studio/shot/doc";
+import type { OpenverseRow, OpenverseSoundKind } from "@dailies-studio/shot/doc";
+
+export interface StockPage {
+  rows: OpenverseRow[];
+  page: number;
+  pageCount: number;
+}
+
+/** A search that did not answer, in words for the person. */
+export class StockSearchError extends Error {}
+
+/** One page of a search: only rows the license policy takes. Searching costs
+ *  the person's allowance, so the view calls this on Enter, never per key. */
+export async function searchStock(
+  query: string,
+  kind: OpenverseSoundKind,
+  page: number,
+  fetchImpl: typeof fetch = (input, init) => fetch(input, init),
+): Promise<StockPage> {
+  let res: Response;
+  try {
+    res = await fetchImpl(openverseSearchUrl({ query, kind, page }), {
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      headers: { accept: "application/json" },
+    });
+  } catch {
+    throw new StockSearchError("Openverse could not be reached. Check your connection and try again.");
+  }
+  if (res.status === 429) {
+    const wait = Number(res.headers.get("retry-after"));
+    throw new StockSearchError(
+      `Openverse's search limit was reached. Try again in ${Number.isFinite(wait) && wait > 0 ? `${Math.ceil(wait)} seconds` : "a minute"}.`,
+    );
+  }
+  if (!res.ok) throw new StockSearchError(`Openverse answered ${res.status}. Try again in a minute.`);
+  const body = (await res.json().catch(() => null)) as { results?: unknown; page_count?: unknown } | null;
+  if (body === null || !Array.isArray(body.results)) throw new StockSearchError("Openverse's answer could not be read.");
+  return {
+    rows: body.results.flatMap((raw) => {
+      const row = parseOpenverseRow(raw);
+      return row !== null && openverseRowRefusal(row) === null ? [row] : [];
+    }),
+    page,
+    pageCount: typeof body.page_count === "number" ? body.page_count : page,
+  };
+}
+
+/** The length limits offered per kind, in seconds; null is no limit. A short
+ *  effect and a long bed want different steps. */
+export const STOCK_LENGTHS: Record<OpenverseSoundKind, readonly (number | null)[]> = {
+  sfx: [null, 1, 3, 10, 30],
+  music: [null, 30, 60, 180],
+};
+
+/** The rows within the length limit. Filtered here, not asked of Openverse,
+ *  whose own length filter answers rows far outside its bands. */
+export function withinLength(rows: readonly OpenverseRow[], maxSeconds: number | null): OpenverseRow[] {
+  return rows.filter((row) => fitsSeconds(row, maxSeconds ?? undefined));
+}
+
+/** "Up to 3s", "Any length". */
+export function lengthLabel(seconds: number | null): string {
+  if (seconds === null) return "Any length";
+  return seconds < 60 ? `Up to ${seconds}s` : `Up to ${seconds / 60} min`;
+}