@runappsai/sdk 0.0.0-stage → 0.3.0

package/src/activity-tracker.ts

@@ -0,0 +1,251 @@
+/**
+ * In-memory session-scoped activity index — turns the raw event
+ * stream from `SDKEvents` into the snapshot the badge UI reads each
+ * frame: which calls are in flight, what just finished, what the
+ * running session cost is.
+ *
+ * Memory bounded:
+ *   - `active` map shrinks on every end/error (calls don't accumulate
+ *     past their settle event).
+ *   - `recent` is a bounded ring of the last RECENT_MAX completions.
+ *   - tokens/sec windows hold only `RATE_WINDOW_MS` worth of deltas;
+ *     stale samples get dropped on every push.
+ *
+ * Snapshot pattern (vs. emitting another event per change): the
+ * badge re-renders on `requestAnimationFrame` while it's open, so
+ * a pull-snapshot API matches that cadence — pushing on every
+ * delta would over-paint and cost battery on token-heavy streams.
+ */
+
+import type {
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestStartEvent,
+  RequestStreamDeltaEvent,
+  SDKCapability,
+  SDKEvents,
+} from "./events.js";
+
+/** Sliding window for tokens/sec — 1.5s gives a snappy display
+ *  without jittering on every chunk arrival (most providers emit
+ *  ~5-30 deltas/s). */
+const RATE_WINDOW_MS = 1500;
+
+/** Cap on the recent-completion ring buffer. The popover lists the
+ *  last 5 by default but we keep a few extra so a future "show more"
+ *  UI doesn't need a refactor. */
+const RECENT_MAX = 20;
+
+/** One LLM call currently in flight. */
+export interface ActiveCall {
+  id: string;
+  model: string;
+  capability: SDKCapability;
+  startedAt: number;
+  /** True for stream:true. Drives the pulsing-ring animation. */
+  streaming: boolean;
+  /** Cumulative completion tokens (0 until first delta). */
+  tokensSoFar: number;
+  /** Tokens per second over the last RATE_WINDOW_MS. 0 until the
+   *  window has 2+ samples. */
+  tokensPerSec: number;
+  /** Internal sample buffer — exposed for tests; UI ignores. */
+  rateSamples: Array<{ t: number; tokens: number }>;
+}
+
+/** One LLM call that already finished (success OR failure). */
+export interface CompletedCall {
+  id: string;
+  model: string;
+  capability: SDKCapability;
+  latencyMs: number;
+  totalTokens: number;
+  costUSD?: number;
+  finishReason?: string;
+  /** false for RequestErrorEvent settles. */
+  ok: boolean;
+  /** Error message when ok=false. */
+  errorMessage?: string;
+  /** Wall clock at settle — drives the "30s ago" relative display. */
+  endedAt: number;
+}
+
+/** Running session totals — shown in the popover's footer. */
+export interface SessionStats {
+  totalCalls: number;
+  totalCostUSD: number;
+  errorCount: number;
+  /** Wall clock when the tracker first saw an event. Drives the
+   *  "session lasted N minutes" string. */
+  startedAt: number;
+}
+
+/** Pull-snapshot of the tracker — taken once per badge re-render. */
+export interface ActivitySnapshot {
+  active: ActiveCall[];
+  recent: CompletedCall[];
+  session: SessionStats;
+  /** Highest-priority status colour for the LED dot:
+   *    "error"   → recent failure within ERROR_HIGHLIGHT_MS
+   *    "active"  → at least one in-flight call
+   *    "idle"    → nothing happening
+   *  The badge's CSS uses this as a class. */
+  status: "idle" | "active" | "error";
+}
+
+/** Window during which a recent error keeps the LED red. 30s is
+ *  long enough to grab attention but short enough that an old
+ *  failure doesn't dominate when subsequent calls succeed. */
+const ERROR_HIGHLIGHT_MS = 30_000;
+
+export class ActivityTracker {
+  private active = new Map<string, ActiveCall>();
+  private recent: CompletedCall[] = [];
+  private session: SessionStats = {
+    totalCalls: 0,
+    totalCostUSD: 0,
+    errorCount: 0,
+    startedAt: Date.now(),
+  };
+  /** Track most recent error wall-clock so the LED stays red for
+   *  ERROR_HIGHLIGHT_MS even after the error scrolls out of recent. */
+  private lastErrorAt = 0;
+  /** "Snapshot changed" listeners. Fired AFTER every event handler
+   *  runs (start / delta / end / error), letting UIs re-render in
+   *  push-mode instead of polling. Without this hook, the badge's
+   *  ring/LED stayed idle until the user opened the popover —
+   *  events landed in the tracker but nobody told the DOM. */
+  private changeListeners = new Set<() => void>();
+
+  /**
+   * Subscribe the tracker to a bus. Returns a single disposer that
+   * unsubscribes all four handlers — callers (BrowserAuth in our
+   * case) attach this on construction and dispose on teardown.
+   */
+  attach(events: SDKEvents): () => void {
+    const offs = [
+      events.on("request:start", (e) => { this.onStart(e); this.notify(); }),
+      events.on("request:streamDelta", (e) => { this.onDelta(e); this.notify(); }),
+      events.on("request:end", (e) => { this.onEnd(e); this.notify(); }),
+      events.on("request:error", (e) => { this.onError(e); this.notify(); }),
+    ];
+    return () => {
+      for (const o of offs) o();
+    };
+  }
+
+  /**
+   * Subscribe to "snapshot may have changed" notifications. Fires
+   * synchronously after each event handler runs — typical consumer
+   * is the badge's `requestRedraw()` which coalesces multiple
+   * notifications into one rAF paint.
+   *
+   * Returns a disposer; call to unsubscribe.
+   */
+  onChange(handler: () => void): () => void {
+    this.changeListeners.add(handler);
+    return () => this.changeListeners.delete(handler);
+  }
+
+  private notify(): void {
+    for (const h of this.changeListeners) {
+      try {
+        h();
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("[runjobs sdk] ActivityTracker onChange listener threw:", err);
+      }
+    }
+  }
+
+  /** O(active+recent) — small in practice, fine on every frame. */
+  snapshot(): ActivitySnapshot {
+    const now = Date.now();
+    return {
+      active: Array.from(this.active.values()),
+      recent: this.recent.slice(),
+      session: { ...this.session },
+      status:
+        now - this.lastErrorAt < ERROR_HIGHLIGHT_MS
+          ? "error"
+          : this.active.size > 0
+            ? "active"
+            : "idle",
+    };
+  }
+
+  // ─── handlers ─────────────────────────────────────────────────
+
+  private onStart(e: RequestStartEvent): void {
+    this.active.set(e.id, {
+      id: e.id,
+      model: e.model,
+      capability: e.capability,
+      startedAt: e.startedAt,
+      streaming: e.streaming,
+      tokensSoFar: 0,
+      tokensPerSec: 0,
+      rateSamples: [],
+    });
+  }
+
+  private onDelta(e: RequestStreamDeltaEvent): void {
+    const call = this.active.get(e.id);
+    if (!call) return; // delta after end — drop
+    call.tokensSoFar = e.totalTokens;
+    const now = Date.now();
+    call.rateSamples.push({ t: now, tokens: e.deltaTokens });
+    // Drop samples older than the window.
+    const cutoff = now - RATE_WINDOW_MS;
+    while (call.rateSamples.length > 0 && call.rateSamples[0]!.t < cutoff) {
+      call.rateSamples.shift();
+    }
+    if (call.rateSamples.length >= 2) {
+      const sumTokens = call.rateSamples.reduce((s, x) => s + x.tokens, 0);
+      const spanMs = now - call.rateSamples[0]!.t;
+      call.tokensPerSec = spanMs > 0 ? (sumTokens * 1000) / spanMs : 0;
+    }
+  }
+
+  private onEnd(e: RequestEndEvent): void {
+    const call = this.active.get(e.id);
+    this.active.delete(e.id);
+    this.pushRecent({
+      id: e.id,
+      model: e.model,
+      capability: e.capability,
+      latencyMs: e.latencyMs,
+      totalTokens: e.totalTokens || call?.tokensSoFar || 0,
+      ...(e.costUSD !== undefined && { costUSD: e.costUSD }),
+      ...(e.finishReason !== undefined && { finishReason: e.finishReason }),
+      ok: true,
+      endedAt: Date.now(),
+    });
+    this.session.totalCalls += 1;
+    if (e.costUSD !== undefined) this.session.totalCostUSD += e.costUSD;
+  }
+
+  private onError(e: RequestErrorEvent): void {
+    const call = this.active.get(e.id);
+    this.active.delete(e.id);
+    this.pushRecent({
+      id: e.id,
+      model: e.model,
+      capability: e.capability,
+      latencyMs: e.latencyMs,
+      totalTokens: call?.tokensSoFar || 0,
+      ok: false,
+      errorMessage: e.error.message,
+      endedAt: Date.now(),
+    });
+    this.session.totalCalls += 1;
+    this.session.errorCount += 1;
+    this.lastErrorAt = Date.now();
+  }
+
+  private pushRecent(c: CompletedCall): void {
+    // Newest first — popover renders top-to-bottom newest→oldest.
+    this.recent.unshift(c);
+    if (this.recent.length > RECENT_MAX) this.recent.length = RECENT_MAX;
+  }
+}

package/src/audio.ts

@@ -0,0 +1,440 @@
+import type { Transport } from "./transport.js";
+import type { Usage } from "./types.js";
+import type { SDKEvents } from "./events.js";
+import { wrapEvents } from "./event-wrap.js";
+import { decodeMediaUrl } from "./media.js";
+
+/* ------------------------------------------------------------------ */
+/* TTS                                                                 */
+/* ------------------------------------------------------------------ */
+/*                                                                     */
+/* Voice metadata (id / name / gender / preview_url / supported        */
+/* emotions) is no longer fetched through a dedicated endpoint —       */
+/* every text_to_speech row on /v1/models carries its full catalog     */
+/* under `options.voices` and `options.supported_emotions`. Use        */
+/* `client.models.get(name)` (or the entry from `client.models.list`)  */
+/* and read those fields off `model.options`.                          */
+/* ------------------------------------------------------------------ */
+
+export interface SpeechParams {
+  input: string;
+  /** Named voice id (`alloy`, `nova`, …; provider-dependent). Omit
+   *  when supplying `reference_audio_url` for zero-shot voice
+   *  cloning — the cloned timbre overrides any named voice. */
+  voice?: string;
+  response_format?: string;
+  speed?: number;
+  /** Provider-specific. Inspect the chosen TTS model's
+   *  `options.supported_emotions` (via `client.models.get(name)`) for
+   *  the legal enum values. */
+  emotion?: string;
+  /** -12 … 12 semitones (provider-dependent). */
+  pitch?: number;
+  /** 0.1 … 10.0 — 1.0 = normal. */
+  volume?: number;
+  /** -12 … 12 — voice timbre shift (provider-dependent). */
+  timber?: number;
+  /**
+   * Free-form natural-language directive for voiceclone (CosyVoice).
+   * e.g. "用四川话快速地说"
+   */
+  instruct_text?: string;
+  /**
+   * Public URL of a reference clip whose timbre to match (zero-shot
+   * voice cloning). When set, voiceclone-capable models ignore `voice`
+   * and synthesize matching the referenced audio.
+   */
+  reference_audio_url?: string;
+  /** Transcript of the reference clip — improves CosyVoice quality. */
+  reference_text?: string;
+  user?: string;
+  /**
+   * Vendor-specific top-level fields the canonical params don't model.
+   * Used for music-generation models on the TTS bucket — ACE-Step needs
+   * `tags` (genre, required), `duration`, `seed`, `scheduler`, etc.
+   * The SDK spreads these at the request body's TOP LEVEL (not nested
+   * under "extra") to match the gateway's extractSpeechExtra contract.
+   * Canonical fields above always win over extra keys with the same name.
+   */
+  extra?: Record<string, unknown>;
+}
+
+export interface SpeechResponse {
+  /** Decoded audio bytes. */
+  data: Uint8Array;
+  /** MIME type reported by the gateway (e.g. "audio/mpeg"). */
+  contentType: string;
+  usage: Usage;
+}
+
+/* ------------------------------------------------------------------ */
+/* STT                                                                 */
+/* ------------------------------------------------------------------ */
+
+/** Same shape as image.ImageFileInput — kept independent so callers can import either. */
+export interface AudioFileInput {
+  data: Blob | ArrayBuffer | Uint8Array | string;
+  filename: string;
+  contentType?: string;
+}
+
+export interface TranscribeParams {
+  file: AudioFileInput;
+  language?: string;
+  prompt?: string;
+  response_format?: string;
+  timestamp_granularities?: ("segment" | "word")[];
+  user?: string;
+}
+
+export interface TranscribeResponse {
+  text: string;
+  usage: Usage;
+  /** Raw upstream payload — segment timings, etc., when present. */
+  raw?: Record<string, unknown>;
+}
+
+/* ------------------------------------------------------------------ */
+/* Service                                                             */
+/* ------------------------------------------------------------------ */
+
+export class AudioService {
+  constructor(
+    private readonly transport: Transport,
+    private readonly events: SDKEvents,
+  ) {}
+
+  // (Removed: listVoices — fetch voice metadata via client.models.get /
+  //  client.models.list and read model.options.voices /
+  //  model.options.supported_emotions.)
+
+  /**
+   * Generate speech from text. Output bytes are base64-decoded by the SDK
+   * — `response.data` is a `Uint8Array` you can write directly to disk:
+   *
+   * ```ts
+   * await fs.writeFile("out.mp3", await client.audio.speech("OpenAI/TTS", {
+   *   input: "Hello!",
+   *   voice: "nova",
+   * }).then(r => r.data));
+   * ```
+   */
+  async speech(
+    model: string,
+    params: SpeechParams,
+    init?: { signal?: AbortSignal },
+  ): Promise<SpeechResponse> {
+    return wrapEvents(
+      this.events,
+      { model, capability: "text_to_speech" },
+      async () => {
+        // Wire shape: {audio_url: "data:<mime>;base64,...", usage: ...}.
+        const raw = await this.transport.postJSON<{
+          audio_url: string;
+          usage: Usage;
+        }>(
+          "/v1/audio/speech",
+          buildSpeechBody(model, params),
+          init,
+        );
+        const { bytes, contentType } = await decodeMediaUrl(raw.audio_url);
+        return { data: bytes, contentType, usage: raw.usage };
+      },
+      (r) => ({ costUSD: r.usage?.total_cost }),
+    );
+  }
+
+  /**
+   * Async equivalent of `speech()`. Submits the job to the gateway's
+   * async TTS endpoint, polls every ~3s until terminal, then decodes
+   * the result audio_url. Use this when a request may exceed the
+   * ~100s origin timeout — ACE-Step music generation at high quality,
+   * large CosyVoice batches, etc. The sync `speech()` method is the
+   * right choice for short-clip TTS that fits inside Cloudflare's
+   * timeout (skips the submit + poll round-trips).
+   *
+   * Returns the same `SpeechResponse` shape as `speech()` — `data` +
+   * `usage` — so callers can swap the two methods with no other change.
+   *
+   * Caller's `signal` deadline bounds the poll wait. Without one,
+   * an internal 10-minute cap applies.
+   */
+  async speechAsync(
+    model: string,
+    params: SpeechParams,
+    init?: { signal?: AbortSignal; pollIntervalMs?: number },
+  ): Promise<SpeechResponse> {
+    return wrapEvents(
+      this.events,
+      { model, capability: "text_to_speech" },
+      async () => {
+        const submit = await this.transport.postJSON<{ id: string; status: string }>(
+          "/v1/async/audio/speech",
+          buildSpeechBody(model, params),
+          init,
+        );
+        if (!submit.id) {
+          throw new Error("runapps: speech submit response missing job id");
+        }
+        return waitSpeechJob(this.transport, submit.id, init);
+      },
+      (r) => ({ costUSD: r.usage?.total_cost }),
+    );
+  }
+
+  /** Transcribe audio to text via multipart upload. */
+  async transcribe(
+    model: string,
+    params: TranscribeParams,
+    init?: { signal?: AbortSignal },
+  ): Promise<TranscribeResponse> {
+    const form = buildTranscribeForm(model, params);
+    return wrapEvents(
+      this.events,
+      { model, capability: "speech_to_text" },
+      () =>
+        this.transport.postMultipart<TranscribeResponse>(
+          "/v1/audio/transcriptions",
+          form,
+          init,
+        ),
+      (r) => ({ costUSD: r.usage?.total_cost }),
+    );
+  }
+
+  /**
+   * Async equivalent of `transcribe()`. Submits the upload, polls
+   * every ~3s until terminal, returns the same `TranscribeResponse`.
+   * Use this for long audio (lectures, podcasts, multi-hour
+   * recordings) where Whisper can take minutes — well past
+   * Cloudflare's ~100s sync ceiling.
+   *
+   * Caller's `signal` deadline bounds the poll wait. Without one,
+   * an internal 10-minute cap applies.
+   */
+  async transcribeAsync(
+    model: string,
+    params: TranscribeParams,
+    init?: { signal?: AbortSignal; pollIntervalMs?: number },
+  ): Promise<TranscribeResponse> {
+    return wrapEvents(
+      this.events,
+      { model, capability: "speech_to_text" },
+      async () => {
+        const form = buildTranscribeForm(model, params);
+        const submit = await this.transport.postMultipart<{ id: string; status: string }>(
+          "/v1/async/audio/transcriptions",
+          form,
+          init,
+        );
+        if (!submit.id) {
+          throw new Error("runapps: transcribe submit response missing job id");
+        }
+        return waitTranscribeJob(this.transport, submit.id, init);
+      },
+      (r) => ({ costUSD: r.usage?.total_cost }),
+    );
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Polls the gateway's async speech-status endpoint until the job
+ * reaches a terminal state, then decodes the result `audio_url`
+ * data: URI into raw bytes + mime. Used by `AudioService.speechAsync`.
+ *
+ * Default poll cadence: first poll 2s after submit, then every 3s.
+ * Caller can override via `init.pollIntervalMs`. `init.signal`
+ * cancels the poll loop.
+ */
+async function waitSpeechJob(
+  transport: Transport,
+  jobId: string,
+  init?: { signal?: AbortSignal; pollIntervalMs?: number },
+): Promise<SpeechResponse> {
+  const path = `/v1/async/audio/speech/${encodeURIComponent(jobId)}`;
+  const interval = init?.pollIntervalMs ?? 3000;
+  // First poll happens fast — typical TTS already done in 2-5s.
+  await sleep(2000, init?.signal);
+  // 10-minute hard cap if caller didn't supply a signal with a
+  // narrower deadline. Long enough for the slowest ACE-Step jobs.
+  const startedAt = Date.now();
+  const internalDeadline = startedAt + 10 * 60 * 1000;
+
+  for (;;) {
+    if (init?.signal?.aborted) {
+      throw new DOMException("speech poll aborted", "AbortError");
+    }
+    if (!init?.signal && Date.now() > internalDeadline) {
+      throw new Error("runapps: speech job timed out (10 min internal cap)");
+    }
+    const status = await transport.getJSON<{
+      id: string;
+      status: string;
+      audio_url?: string;
+      usage?: Usage;
+      error?: string;
+    }>(path, init);
+    if (status.status === "succeeded") {
+      if (!status.audio_url) {
+        throw new Error("runapps: speech job succeeded but no audio_url returned");
+      }
+      const { bytes, contentType } = await decodeMediaUrl(status.audio_url);
+      return {
+        data: bytes,
+        contentType,
+        usage: status.usage ?? { total_cost: 0 },
+      };
+    }
+    if (status.status === "failed") {
+      throw new Error(status.error || "runapps: speech job failed");
+    }
+    // queued | running → wait + retry.
+    await sleep(interval, init?.signal);
+  }
+}
+
+/**
+ * Polls the gateway's async transcribe-status endpoint until terminal,
+ * then assembles a TranscribeResponse from the final payload. Used by
+ * `AudioService.transcribeAsync`.
+ */
+async function waitTranscribeJob(
+  transport: Transport,
+  jobId: string,
+  init?: { signal?: AbortSignal; pollIntervalMs?: number },
+): Promise<TranscribeResponse> {
+  const path = `/v1/async/audio/transcriptions/${encodeURIComponent(jobId)}`;
+  const interval = init?.pollIntervalMs ?? 3000;
+  await sleep(2000, init?.signal);
+  const internalDeadline = Date.now() + 10 * 60 * 1000;
+  for (;;) {
+    if (init?.signal?.aborted) {
+      throw new DOMException("transcribe poll aborted", "AbortError");
+    }
+    if (!init?.signal && Date.now() > internalDeadline) {
+      throw new Error("runapps: transcribe job timed out (10 min internal cap)");
+    }
+    const status = await transport.getJSON<Record<string, unknown>>(path, init);
+    switch (status.status) {
+      case "succeeded":
+        return assembleTranscribeResponse(status);
+      case "failed":
+        throw new Error((status.error as string) || "runapps: transcribe job failed");
+      case "queued":
+      case "running":
+        await sleep(interval, init?.signal);
+        break;
+      default:
+        throw new Error(`runapps: unknown transcribe job status ${JSON.stringify(status.status)}`);
+    }
+  }
+}
+
+/**
+ * Pulls canonical text + usage out of a succeeded transcribe-status
+ * payload, leaves the rest under .raw — matches the sync response
+ * shape produced by `transcribe()`.
+ */
+function assembleTranscribeResponse(payload: Record<string, unknown>): TranscribeResponse {
+  const out: TranscribeResponse = {
+    text: (payload.text as string) ?? "",
+    usage: (payload.usage as Usage) ?? { total_cost: 0 },
+  };
+  const raw: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (k === "text" || k === "usage" || k === "id" || k === "status") continue;
+    raw[k] = v;
+  }
+  if (Object.keys(raw).length > 0) {
+    out.raw = raw;
+  }
+  return out;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new DOMException("aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * buildSpeechBody assembles the wire body for /v1/audio/speech (and
+ * its async sibling): `{model, ...canonical, ...extra}` flattened at
+ * the top level. The gateway's extractSpeechExtra peels non-canonical
+ * keys back into req.Extra, so the round-trip is symmetric. Canonical
+ * fields always win over `extra` keys of the same name — never let
+ * Extra silently override a typed field.
+ */
+function buildSpeechBody(model: string, params: SpeechParams): Record<string, unknown> {
+  const { extra, ...canonical } = params;
+  const body: Record<string, unknown> = { model, ...canonical };
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      if (k in body) continue;
+      body[k] = v;
+    }
+  }
+  return body;
+}
+
+function buildTranscribeForm(model: string, params: TranscribeParams): FormData {
+  const form = new FormData();
+  form.set("model", model);
+  if (params.language) form.set("language", params.language);
+  if (params.prompt) form.set("prompt", params.prompt);
+  if (params.response_format) form.set("response_format", params.response_format);
+  if (params.timestamp_granularities) {
+    for (const g of params.timestamp_granularities) {
+      form.append("timestamp_granularities[]", g);
+    }
+  }
+  if (params.user) form.set("user", params.user);
+
+  const ct = params.file.contentType ?? guessAudioMime(params.file.filename);
+  const blob =
+    params.file.data instanceof Blob
+      ? params.file.data
+      : new Blob([params.file.data as BlobPart], { type: ct });
+  form.set("file", blob, params.file.filename);
+  return form;
+}
+
+function guessAudioMime(filename: string): string {
+  const ext = filename.toLowerCase().split(".").pop() ?? "";
+  switch (ext) {
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "m4a":
+      return "audio/mp4";
+    case "flac":
+      return "audio/flac";
+    case "ogg":
+      return "audio/ogg";
+    case "webm":
+      return "audio/webm";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// (base64ToBytes was here — promoted to media.ts as part of
+// decodeMediaUrl. The audio path now goes through that single helper
+// so image and audio decode through one implementation.)