@pickleball/expo-sdk 0.1.1

package/src/match/voice/audio.ts

@@ -0,0 +1,231 @@
+import {
+  VoiceError,
+  type AudioPlayback,
+  type VoiceAudioMode,
+  type VoiceRouteState,
+} from "./types";
+
+export interface ExpoAudioPlayer {
+  play(): void;
+  pause(): void;
+  remove(): void;
+  addListener(
+    event: "playbackStatusUpdate",
+    listener: (status: {
+      readonly didJustFinish?: boolean;
+      readonly isLoaded?: boolean;
+      readonly isBuffering?: boolean;
+      readonly error?: unknown;
+      readonly playbackState?: string;
+    }) => void,
+  ): { remove(): void };
+}
+
+export interface ExpoAudioBindings {
+  setAudioModeAsync(options: {
+    readonly allowsRecording: boolean;
+    readonly playsInSilentMode: boolean;
+  }): Promise<void>;
+  createAudioPlayer(source: unknown): ExpoAudioPlayer;
+}
+
+export interface ExpoAudioPlaybackOptions {
+  readonly load?: () => ExpoAudioBindings;
+  readonly loadNativeAudio?: () => NativeAudioSessionBindings;
+  readonly resolveSource?: (source: string) => unknown;
+  readonly playbackTimeoutMs?: number;
+}
+
+export interface NativeAudioSessionBindings {
+  captureAudioSessionState(): Promise<void>;
+  configureAudioSession(mode: VoiceAudioMode): Promise<VoiceRouteState>;
+  getAudioRouteState(): VoiceRouteState | Promise<VoiceRouteState>;
+  addListener(
+    event: "onAudioRouteChanged",
+    listener: (state: VoiceRouteState) => void,
+  ): { remove(): void };
+  disposeAudioSession(): Promise<void>;
+}
+
+declare const require: (name: string) => any;
+
+export function createExpoAudioPlayback(
+  options: ExpoAudioPlaybackOptions = {},
+): AudioPlayback {
+  const load = options.load ?? (() => require("expo-audio") as ExpoAudioBindings);
+  const loadNativeAudio = options.loadNativeAudio ?? (() => {
+    const imported = require("@pickleball/voice-native");
+    return (imported.default ?? imported) as NativeAudioSessionBindings;
+  });
+  let player: ExpoAudioPlayer | null = null;
+  let settleCurrent: ((error?: unknown) => void) | null = null;
+  let nativeAudio: NativeAudioSessionBindings | null | undefined;
+  let nativeSubscription: { remove(): void } | null = null;
+  let disposed = false;
+  let operationGeneration = 0;
+  let configureTail: Promise<void> = Promise.resolve();
+  let disposePromise: Promise<void> | null = null;
+  let routeState: VoiceRouteState = {
+    route: "system",
+    interrupted: false,
+    disconnectedReason: null,
+  };
+  const listeners = new Set<(state: VoiceRouteState) => void>();
+
+  const updateRouteState = (state: VoiceRouteState) => {
+    if (disposed) return;
+    routeState = state;
+    for (const listener of listeners) listener(routeState);
+  };
+
+  const getNativeAudio = () => {
+    if (nativeAudio !== undefined) return nativeAudio;
+    try { nativeAudio = loadNativeAudio(); }
+    catch { nativeAudio = null; }
+    return nativeAudio;
+  };
+
+  const observeNativeAudio = () => {
+    const native = getNativeAudio();
+    if (native && !nativeSubscription) {
+      nativeSubscription = native.addListener("onAudioRouteChanged", updateRouteState);
+    }
+    return native;
+  };
+
+  const stop = async () => {
+    if (!player) return;
+    const current = player;
+    player = null;
+    const settle = settleCurrent;
+    settleCurrent = null;
+    try { current.pause(); } catch { /* Already-unloaded players are stopped. */ }
+    if (settle) settle();
+    else try { current.remove(); } catch { /* Native player teardown is best-effort. */ }
+  };
+
+  const isCurrentAudioOperation = (generation: number) =>
+    !disposed && generation === operationGeneration;
+
+  const releaseNativeAudioSession = async (native: NativeAudioSessionBindings) => {
+    nativeSubscription?.remove();
+    nativeSubscription = null;
+    await native.disposeAudioSession();
+  };
+
+  return {
+    configure(mode: VoiceAudioMode) {
+      if (disposed) return Promise.resolve();
+      const generation = operationGeneration;
+      const operation = configureTail.then(async () => {
+        if (!isCurrentAudioOperation(generation)) return;
+        const native = observeNativeAudio();
+        try { await native?.captureAudioSessionState(); }
+        catch { /* Capture is best-effort when the optional native module is unavailable. */ }
+        if (!isCurrentAudioOperation(generation)) return;
+        try {
+          await load().setAudioModeAsync({
+            allowsRecording: mode === "live",
+            playsInSilentMode: true,
+          });
+        } catch (error) {
+          if (native) {
+            try { await releaseNativeAudioSession(native); }
+            catch { /* Preserve the Expo failure after awaiting best-effort native cleanup. */ }
+          }
+          throw error;
+        }
+        if (native) {
+          try {
+            const nextRouteState = await native.configureAudioSession(mode);
+            if (isCurrentAudioOperation(generation)) updateRouteState(nextRouteState);
+          } catch (error) {
+            try { await releaseNativeAudioSession(native); }
+            catch { /* Preserve the handshake failure after awaiting best-effort restoration. */ }
+            throw error;
+          }
+        }
+      });
+      configureTail = operation.catch(() => undefined);
+      return operation;
+    },
+    async play(source: string) {
+      if (disposed) {
+        throw new VoiceError("playback_failed", "Audio playback is disposed");
+      }
+      await stop();
+      if (disposed) {
+        throw new VoiceError("playback_failed", "Audio playback is disposed");
+      }
+      let current: ExpoAudioPlayer;
+      try {
+        current = load().createAudioPlayer(
+          options.resolveSource ? options.resolveSource(source) : source,
+        );
+      } catch (error) {
+        throw new VoiceError("playback_failed", "Unable to create audio player", { cause: error });
+      }
+      player = current;
+      await new Promise<void>((resolve, reject) => {
+        let settled = false;
+        let subscription: { remove(): void } | null = null;
+        const timeout = setTimeout(() => {
+          settle(new VoiceError("playback_failed", "Audio playback timed out"));
+        }, options.playbackTimeoutMs ?? 30_000);
+        const settle = (error?: unknown) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          try { subscription?.remove(); } catch { /* Listener may already be detached. */ }
+          if (player === current) player = null;
+          if (settleCurrent === settle) settleCurrent = null;
+          try { current.remove(); } catch { /* Terminal native state already released it. */ }
+          if (error) {
+            reject(error instanceof VoiceError
+              ? error
+              : new VoiceError("playback_failed", "Audio playback failed", { cause: error }));
+          } else resolve();
+        };
+        settleCurrent = settle;
+        try {
+          subscription = current.addListener("playbackStatusUpdate", (status) => {
+            if (status.didJustFinish) settle();
+            else if (status.error != null || status.playbackState === "error") {
+              settle(status.error ?? new Error("Audio player entered an error state"));
+            }
+          });
+          current.play();
+        } catch (error) {
+          settle(error);
+        }
+      });
+    },
+    stop,
+    dispose() {
+      if (disposePromise) return disposePromise;
+      disposed = true;
+      operationGeneration += 1;
+      disposePromise = (async () => {
+        await stop();
+        await configureTail;
+        const native = getNativeAudio();
+        if (!native) {
+          nativeSubscription?.remove();
+          nativeSubscription = null;
+        }
+        try { if (native) await releaseNativeAudioSession(native); }
+        catch { /* Native teardown is best-effort. */ }
+        listeners.clear();
+      })();
+      return disposePromise;
+    },
+    getRouteState() {
+      return routeState;
+    },
+    subscribeToRouteChanges(listener) {
+      listeners.add(listener);
+      observeNativeAudio();
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/src/match/voice/bundled-assets.native.ts

@@ -0,0 +1,47 @@
+declare const require: (path: string) => number;
+
+const assets: Readonly<Record<string, number>> = {
+  "number-0": require("./assets/number-0.wav"), "number-1": require("./assets/number-1.wav"),
+  "number-2": require("./assets/number-2.wav"), "number-3": require("./assets/number-3.wav"),
+  "number-4": require("./assets/number-4.wav"), "number-5": require("./assets/number-5.wav"),
+  "number-6": require("./assets/number-6.wav"), "number-7": require("./assets/number-7.wav"),
+  "number-8": require("./assets/number-8.wav"), "number-9": require("./assets/number-9.wav"),
+  "number-mot": require("./assets/number-mot.wav"), "number-lam": require("./assets/number-lam.wav"),
+  "number-10": require("./assets/number-10.wav"), "number-11": require("./assets/number-11.wav"),
+  "number-12": require("./assets/number-12.wav"), "number-13": require("./assets/number-13.wav"),
+  "number-14": require("./assets/number-14.wav"), "number-15": require("./assets/number-15.wav"),
+  "number-16": require("./assets/number-16.wav"), "number-17": require("./assets/number-17.wav"),
+  "number-18": require("./assets/number-18.wav"), "number-19": require("./assets/number-19.wav"),
+  "number-20": require("./assets/number-20.wav"), "number-30": require("./assets/number-30.wav"),
+  "number-40": require("./assets/number-40.wav"), "number-50": require("./assets/number-50.wav"),
+  "number-60": require("./assets/number-60.wav"), "number-70": require("./assets/number-70.wav"),
+  "number-80": require("./assets/number-80.wav"), "number-90": require("./assets/number-90.wav"),
+  "score-deu-0": require("./assets/score-deu-0.wav"), "score-deu-1": require("./assets/score-deu-1.wav"),
+  "score-deu-2": require("./assets/score-deu-2.wav"), "score-deu-3": require("./assets/score-deu-3.wav"),
+  "score-deu-4": require("./assets/score-deu-4.wav"), "score-deu-5": require("./assets/score-deu-5.wav"),
+  "score-deu-6": require("./assets/score-deu-6.wav"), "score-deu-7": require("./assets/score-deu-7.wav"),
+  "score-deu-8": require("./assets/score-deu-8.wav"), "score-deu-9": require("./assets/score-deu-9.wav"),
+  "score-deu-10": require("./assets/score-deu-10.wav"), "score-deu-11": require("./assets/score-deu-11.wav"),
+  "score-deu-12": require("./assets/score-deu-12.wav"), "score-deu-13": require("./assets/score-deu-13.wav"),
+  "score-deu-14": require("./assets/score-deu-14.wav"), "score-deu-15": require("./assets/score-deu-15.wav"),
+  "score-deu-16": require("./assets/score-deu-16.wav"), "score-deu-17": require("./assets/score-deu-17.wav"),
+  "score-deu-18": require("./assets/score-deu-18.wav"), "score-deu-19": require("./assets/score-deu-19.wav"),
+  "score-deu-20": require("./assets/score-deu-20.wav"), "score-deu-30": require("./assets/score-deu-30.wav"),
+  "score-deu-40": require("./assets/score-deu-40.wav"), "score-deu-50": require("./assets/score-deu-50.wav"),
+  "score-deu-60": require("./assets/score-deu-60.wav"), "score-deu-70": require("./assets/score-deu-70.wav"),
+  "score-deu-80": require("./assets/score-deu-80.wav"), "score-deu-90": require("./assets/score-deu-90.wav"),
+  "score-deu-mot": require("./assets/score-deu-mot.wav"), "score-deu-lam": require("./assets/score-deu-lam.wav"),
+  "server-1": require("./assets/server-1.wav"), "server-2": require("./assets/server-2.wav"),
+  "court-left": require("./assets/court-left.wav"), "court-right": require("./assets/court-right.wav"),
+  "service-change": require("./assets/service-change.wav"), "game-point": require("./assets/game-point.wav"),
+  "game-won": require("./assets/game-won.wav"), "court-switch": require("./assets/court-switch.wav"),
+  "match-won": require("./assets/match-won.wav"), "test-speaker": require("./assets/test-speaker.wav"),
+};
+
+export function resolveBundledVoiceAsset(source: string): string | number {
+  const match = /^asset:\/\/voice\/([^/]+)\.wav$/u.exec(source);
+  if (!match) return source;
+  const asset = assets[match[1]];
+  if (asset === undefined) throw new Error(`Unknown bundled voice asset: ${match[1]}`);
+  return asset;
+}

package/src/match/voice/bundled-assets.ts

@@ -0,0 +1,3 @@
+export function resolveBundledVoiceAsset(source: string): string {
+  return source;
+}

package/src/match/voice/gemini-engine.ts

@@ -0,0 +1,167 @@
+import {
+  VoiceError,
+  type NeuralVoiceEngine,
+  type VoiceTtsOptions,
+} from "./types";
+
+/** Minimal file operations the engine needs; defaults to expo-file-system. */
+export interface GeneratedAudioFileSystem {
+  writeFile(path: string, bytes: Uint8Array): Promise<void>;
+  removeFile(path: string): Promise<void>;
+}
+
+export interface GeminiVoiceEngineOptions extends VoiceTtsOptions {
+  /** Directory that receives generated WAV files. */
+  readonly generatedRoot: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly fileSystem?: GeneratedAudioFileSystem;
+}
+
+declare const require: (name: string) => any;
+
+function createExpoGeneratedAudioFileSystem(): GeneratedAudioFileSystem {
+  return {
+    async writeFile(path, bytes) {
+      const fs = require("expo-file-system");
+      const file = new fs.File(path);
+      if (!file.exists) file.create({ intermediates: true, overwrite: true });
+      const handle = file.open(fs.FileMode.ReadWrite);
+      try {
+        handle.writeBytes(bytes);
+      } finally {
+        handle.close();
+      }
+    },
+    async removeFile(path) {
+      const fs = require("expo-file-system");
+      const file = new fs.File(path);
+      if (file.exists) file.delete();
+    },
+  };
+}
+
+/**
+ * Cloud announcement voice: posts the phrase to the partner proxy, which calls
+ * Vertex AI Gemini TTS and returns a WAV body. Failures surface as VoiceError
+ * so the scheduler drops to the bundled WAV fallback.
+ */
+export function createGeminiVoiceEngine(
+  options: GeminiVoiceEngineOptions,
+): NeuralVoiceEngine {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const fileSystem = options.fileSystem ?? createExpoGeneratedAudioFileSystem();
+  const timeoutMs = options.requestTimeoutMs ?? 8_000;
+  const controllers = new Set<AbortController>();
+  let sequence = 0;
+  let disposed = false;
+
+  const abortAll = () => {
+    for (const controller of controllers) controller.abort();
+    controllers.clear();
+  };
+
+  return {
+    async availability() {
+      return !disposed && options.url ? "available" : "unavailable";
+    },
+    async prewarm() {
+      // The scheduler drives prewarming through synthesize + its own cache.
+    },
+    async synthesize(text, signal) {
+      if (disposed) {
+        throw new VoiceError("engine_unavailable", "Gemini voice engine is disposed");
+      }
+      const controller = new AbortController();
+      controllers.add(controller);
+      const onAbort = () => controller.abort();
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) controller.abort();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        let response: Response;
+        try {
+          response = await fetcher(options.url, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              ...(options.headers ? await options.headers() : undefined),
+            },
+            body: JSON.stringify({
+              text,
+              voiceName: options.voiceName,
+              languageCode: options.languageCode,
+            }),
+            signal: controller.signal,
+          });
+        } catch (caught) {
+          throw new VoiceError(
+            controller.signal.aborted ? "synthesis_failed" : "network_unavailable",
+            controller.signal.aborted
+              ? "Voice synthesis was cancelled"
+              : "Voice synthesis request could not reach the TTS endpoint",
+            { cause: caught },
+          );
+        }
+        if (!response.ok) {
+          throw new VoiceError(
+            "synthesis_failed",
+            `TTS endpoint responded with status ${response.status}`,
+          );
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.length === 0) {
+          throw new VoiceError("synthesis_failed", "TTS endpoint returned an empty body");
+        }
+        if (controller.signal.aborted || disposed) {
+          throw new VoiceError("synthesis_failed", "Voice synthesis was cancelled");
+        }
+        const path = `${options.generatedRoot}/tts-${++sequence}-${Date.now()}.wav`;
+        try {
+          await fileSystem.writeFile(path, bytes);
+        } catch (caught) {
+          throw new VoiceError("storage_failure", "Unable to persist generated audio", {
+            cause: caught,
+          });
+        }
+        if (controller.signal.aborted || disposed) {
+          await fileSystem.removeFile(path).catch(() => undefined);
+          throw new VoiceError("synthesis_failed", "Voice synthesis was cancelled");
+        }
+        return path;
+      } finally {
+        clearTimeout(timeout);
+        signal.removeEventListener("abort", onAbort);
+        controllers.delete(controller);
+      }
+    },
+    async cancel() {
+      abortAll();
+    },
+    async release(filePath) {
+      try {
+        await fileSystem.removeFile(filePath);
+      } catch {
+        // Generated-file cleanup is best-effort and must never break scoring.
+      }
+    },
+    async dispose() {
+      disposed = true;
+      abortAll();
+    },
+  };
+}
+
+/** Placeholder engine used when no TTS endpoint is configured: always falls back. */
+export function createUnavailableVoiceEngine(): NeuralVoiceEngine {
+  return {
+    async availability() {
+      return "unavailable";
+    },
+    async prewarm() {},
+    async synthesize(): Promise<string> {
+      throw new VoiceError("engine_unavailable", "No TTS endpoint is configured");
+    },
+    async cancel() {},
+    async dispose() {},
+  };
+}

package/src/match/voice/index.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./phrases";
+export * from "./scheduler";
+export * from "./audio";
+export * from "./gemini-engine";
+export * from "./bundled-assets";
+export * from "./service";

package/src/match/voice/phrases.ts

@@ -0,0 +1,185 @@
+import type { MatchEvent, MatchSnapshot, MatchTeamId } from "../contracts";
+import type {
+  AnnouncementKind,
+  AnnouncementPlan,
+  FallbackVoiceToken,
+} from "./types";
+
+const VIETNAMESE_NUMBERS = [
+  "không",
+  "một",
+  "hai",
+  "ba",
+  "bốn",
+  "năm",
+  "sáu",
+  "bảy",
+  "tám",
+  "chín",
+] as const;
+
+function spokenNumber(value: number): string {
+  if (!Number.isInteger(value) || value < 0 || value > 99) {
+    throw new RangeError("Announcement scores must be integers from 0 to 99");
+  }
+  if (value < 10) return VIETNAMESE_NUMBERS[value];
+  if (value === 10) return "mười";
+  const tens = Math.floor(value / 10);
+  const units = value % 10;
+  const tensWord = tens === 1 ? "mười" : `${VIETNAMESE_NUMBERS[tens]} mươi`;
+  if (units === 0) return tensWord;
+  if (units === 1) return `${tensWord} mốt`;
+  if (units === 5) return `${tensWord} lăm`;
+  return `${tensWord} ${VIETNAMESE_NUMBERS[units]}`;
+}
+
+function teamName(snapshot: MatchSnapshot, teamId: MatchTeamId): string {
+  const team = snapshot.teams[teamId];
+  return team.name ?? team.players.map((player) => player.name).join(" và ");
+}
+
+function numberTokens(value: number): FallbackVoiceToken[] {
+  if (value < 20 || value % 10 === 0) return [`number-${value}`];
+  const units = value % 10;
+  const unitToken: FallbackVoiceToken = units === 1
+    ? "number-mot"
+    : units === 5
+      ? "number-lam"
+      : `number-${units}`;
+  return [`number-${Math.floor(value / 10) * 10}`, unitToken];
+}
+
+function scoreDeuTokens(value: number): FallbackVoiceToken[] {
+  if (value < 20 || value % 10 === 0) return [`score-deu-${value}` as FallbackVoiceToken];
+  const units = value % 10;
+  const unitToken: FallbackVoiceToken = units === 1
+    ? "score-deu-mot"
+    : units === 5
+      ? "score-deu-lam"
+      : (`score-deu-${units}` as FallbackVoiceToken);
+  return [`number-${Math.floor(value / 10) * 10}` as FallbackVoiceToken, unitToken];
+}
+
+function doublesServerNumber(snapshot: MatchSnapshot): number {
+  if (snapshot.scoringMode === "sideOut") {
+    return snapshot.serve.serverNumber;
+  }
+  const servingTeam = snapshot.teams[snapshot.serve.teamId];
+  const playerIndex = servingTeam.players.findIndex(
+    (player) => player.id === snapshot.serve.playerId,
+  );
+  return playerIndex === 1 ? 2 : 1;
+}
+
+function scorePlan(snapshot: MatchSnapshot, prefix: string = ""): AnnouncementPlan {
+  const serving = snapshot.serve.teamId;
+  const receiving = serving === "A" ? "B" : "A";
+  const game = snapshot.games[snapshot.currentGame - 1];
+  if (!game) throw new TypeError("Current game is missing");
+  const servingScore = game.score[serving];
+  const receivingScore = game.score[receiving];
+  const serverNum = snapshot.format === "doubles" ? doublesServerNumber(snapshot) : 1;
+  const server = snapshot.format === "doubles" ? ` ${spokenNumber(serverNum)}` : "";
+
+  const fallbackTokens: FallbackVoiceToken[] = [];
+  if (prefix === "Đổi giao bóng") {
+    fallbackTokens.push("service-change");
+  } else if (prefix === "Điểm thắng ván") {
+    fallbackTokens.push("game-point");
+  }
+
+  if (servingScore === receivingScore) {
+    fallbackTokens.push(...scoreDeuTokens(servingScore));
+  } else {
+    fallbackTokens.push(...numberTokens(servingScore));
+    fallbackTokens.push(...numberTokens(receivingScore));
+  }
+
+  if (snapshot.format === "doubles") {
+    fallbackTokens.push(`server-${serverNum}` as FallbackVoiceToken);
+  }
+
+  const secondPart = servingScore === receivingScore ? "đều" : spokenNumber(receivingScore);
+  const scoreBody = `${spokenNumber(servingScore).replace(/^./u, (letter) => letter.toLocaleUpperCase("vi"))} ${secondPart}${server}.`;
+  return {
+    kind: "score",
+    text: prefix
+      ? `${prefix}, ${scoreBody.replace(/^./u, (letter) => letter.toLocaleLowerCase("vi"))}`
+      : scoreBody,
+    score: [servingScore, receivingScore],
+    fallbackTokens,
+  };
+}
+
+function statusPlan(
+  kind: AnnouncementKind,
+  text: string,
+  token: FallbackVoiceToken,
+): AnnouncementPlan {
+  return { kind, text, fallbackTokens: [token] };
+}
+
+/** Pure phrase selection from the state before and after one committed event. */
+export function buildVietnameseAnnouncement(
+  previous: MatchSnapshot,
+  current: MatchSnapshot,
+  event: MatchEvent,
+): AnnouncementPlan {
+  if (current.status === "completed" && previous.status !== "completed" && current.winner) {
+    return statusPlan(
+      "matchWon",
+      `Đội ${teamName(current, current.winner)} thắng trận.`,
+      "match-won",
+    );
+  }
+  const previousGame = previous.games[previous.currentGame - 1];
+  const currentGame = current.games[current.currentGame - 1];
+  if (currentGame?.winner && !previousGame?.winner) {
+    return statusPlan(
+      "gameWon",
+      `Đội ${teamName(current, currentGame.winner)} thắng ván.`,
+      "game-won",
+    );
+  }
+  if (event.type === "courtSwitchConfirmed") {
+    return statusPlan("courtSwitch", "Đổi sân.", "court-switch");
+  }
+  const serviceChanged = previous.serve.teamId !== current.serve.teamId;
+  if (serviceChanged) {
+    const plan = scorePlan(current, "Đổi giao bóng");
+    return { ...plan, kind: "serviceChange" };
+  }
+  if (
+    currentGame &&
+    !currentGame.winner &&
+    Math.max(currentGame.score.A, currentGame.score.B) === current.targetScore - 1
+  ) {
+    const plan = scorePlan(current, "Điểm thắng ván");
+    return { ...plan, kind: "gamePoint" };
+  }
+  return scorePlan(current);
+}
+
+export function planBundledFallback(
+  plan: AnnouncementPlan,
+): readonly string[] {
+  let tokens = plan.fallbackTokens;
+  if (plan.score) {
+    const prefixTokens = plan.fallbackTokens.filter(
+      (token) => token === "service-change" || token === "game-point",
+    );
+    const suffixTokens = plan.fallbackTokens.filter(
+      (token) => token.startsWith("server-") || token.startsWith("court-"),
+    );
+    const scoreTokens: FallbackVoiceToken[] =
+      plan.score[0] === plan.score[1]
+        ? [...scoreDeuTokens(plan.score[0])]
+        : [...numberTokens(plan.score[0]), ...numberTokens(plan.score[1])];
+    tokens = [
+      ...prefixTokens,
+      ...scoreTokens,
+      ...suffixTokens,
+    ];
+  }
+  return tokens.map((token) => `asset://voice/${token}.wav`);
+}