@pickleball/expo-sdk 0.1.1

package/src/match/voice/scheduler.ts

@@ -0,0 +1,205 @@
+import { planBundledFallback } from "./phrases";
+import type {
+  AnnouncementPlan,
+  AudioPlayback,
+  NeuralVoiceEngine,
+} from "./types";
+
+export interface LatestAnnouncementSchedulerOptions {
+  readonly engine: NeuralVoiceEngine;
+  readonly audio: AudioPlayback;
+  readonly onError?: (error: Error) => void;
+}
+
+export class LatestAnnouncementScheduler {
+  private static readonly MAX_CACHE_ENTRIES = 32;
+  private generation = 0;
+  private activeController: AbortController | null = null;
+  private lastPlan: AnnouncementPlan | null = null;
+  private readonly neuralCache = new Map<string, string>();
+  private readonly operations = new Set<Promise<void>>();
+  private readonly prewarmControllers = new Set<AbortController>();
+  private lifecycle: "active" | "disposing" | "disposed" = "active";
+  private disposePromise: Promise<void> | null = null;
+
+  constructor(private readonly options: LatestAnnouncementSchedulerOptions) {}
+
+  prewarm(commonPhrases: readonly string[] = []): Promise<void> {
+    if (this.lifecycle !== "active") return Promise.resolve();
+    const generation = this.generation;
+    return this.track((async () => {
+      try {
+        await this.options.engine.prewarm(commonPhrases);
+        if (this.lifecycle !== "active" || generation !== this.generation) return;
+        const availability = await this.options.engine.availability();
+        if (this.lifecycle !== "active" || generation !== this.generation) return;
+        if (availability === "available") {
+          for (const phrase of commonPhrases) {
+            if (this.lifecycle !== "active" || generation !== this.generation) return;
+            if (this.neuralCache.has(phrase)) continue;
+            const controller = new AbortController();
+            this.prewarmControllers.add(controller);
+            let file: string;
+            try {
+              file = await this.options.engine.synthesize(phrase, controller.signal);
+            } finally {
+              this.prewarmControllers.delete(controller);
+            }
+            if (this.lifecycle !== "active" || generation !== this.generation || controller.signal.aborted) {
+              await this.options.engine.release?.(file);
+              return;
+            }
+            await this.cacheFile(phrase, file);
+          }
+        }
+      } catch (error) {
+        this.report(error);
+      }
+    })());
+  }
+
+  enqueue(plan: AnnouncementPlan): Promise<void> {
+    if (this.lifecycle !== "active") return Promise.resolve();
+    return this.track(this.performEnqueue(plan));
+  }
+
+  private async performEnqueue(plan: AnnouncementPlan): Promise<void> {
+    this.lastPlan = plan;
+    const generation = ++this.generation;
+    this.activeController?.abort();
+    const controller = new AbortController();
+    this.activeController = controller;
+    await Promise.allSettled([
+      this.options.engine.cancel(),
+      this.options.audio.stop(),
+    ]);
+    if (generation !== this.generation) return;
+
+    try {
+      const avail = await this.options.engine.availability();
+      if (avail === "available") {
+        let file = this.touchCachedFile(plan.text);
+        if (!file) {
+          file = await this.options.engine.synthesize(plan.text, controller.signal);
+          await this.cacheFile(plan.text, file);
+        }
+        if (this.lifecycle !== "active" || generation !== this.generation || controller.signal.aborted) return;
+        await this.options.audio.play(file);
+        return;
+      }
+    } catch (error) {
+      if (controller.signal.aborted || generation !== this.generation) return;
+      this.report(error);
+    }
+
+    for (const source of planBundledFallback(plan)) {
+      if (generation !== this.generation || controller.signal.aborted) return;
+      try {
+        await this.options.audio.play(source);
+      } catch (error) {
+        this.report(error);
+      }
+    }
+  }
+
+  async replayLast(): Promise<void> {
+    if (this.lifecycle !== "active") return;
+    if (this.lastPlan) await this.enqueue(this.lastPlan);
+  }
+
+  testSpeaker(): Promise<void> {
+    if (this.lifecycle !== "active") return Promise.resolve();
+    return this.track(this.performSpeakerTest());
+  }
+
+  private async performSpeakerTest(): Promise<void> {
+    const generation = ++this.generation;
+    this.activeController?.abort();
+    await Promise.allSettled([
+      this.options.engine.cancel(),
+      this.options.audio.stop(),
+    ]);
+    if (generation === this.generation) {
+      try {
+        await this.options.audio.play("asset://voice/test-speaker.wav");
+      } catch (error) {
+        this.report(error);
+      }
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposePromise) return this.disposePromise;
+    this.lifecycle = "disposing";
+    this.generation += 1;
+    this.activeController?.abort();
+    this.activeController = null;
+    for (const controller of this.prewarmControllers) controller.abort();
+    this.prewarmControllers.clear();
+    this.disposePromise = (async () => {
+      await Promise.allSettled([
+        this.options.engine.cancel(),
+        this.options.audio.stop(),
+      ]);
+      await Promise.allSettled([...this.operations]);
+      await this.clearCache();
+      await Promise.allSettled([
+        this.options.engine.dispose(),
+        this.options.audio.dispose(),
+      ]);
+      this.lifecycle = "disposed";
+    })();
+    return this.disposePromise;
+  }
+
+  async clearCache(): Promise<void> {
+    const files = [...new Set(this.neuralCache.values())];
+    this.neuralCache.clear();
+    if (this.options.engine.release) {
+      await Promise.allSettled(files.map((file) => this.options.engine.release!(file)));
+    }
+  }
+
+  private async cacheFile(text: string, file: string): Promise<void> {
+    if (this.lifecycle !== "active") {
+      await this.options.engine.release?.(file);
+      return;
+    }
+    const replaced = this.neuralCache.get(text);
+    if (replaced && replaced !== file) await this.options.engine.release?.(replaced);
+    this.neuralCache.delete(text);
+    this.neuralCache.set(text, file);
+    while (this.neuralCache.size > LatestAnnouncementScheduler.MAX_CACHE_ENTRIES) {
+      const oldest = this.neuralCache.entries().next().value as [string, string] | undefined;
+      if (!oldest) break;
+      this.neuralCache.delete(oldest[0]);
+      await this.options.engine.release?.(oldest[1]);
+    }
+  }
+
+  private touchCachedFile(text: string): string | undefined {
+    const file = this.neuralCache.get(text);
+    if (!file) return undefined;
+    this.neuralCache.delete(text);
+    this.neuralCache.set(text, file);
+    return file;
+  }
+
+  private track(operation: Promise<void>): Promise<void> {
+    this.operations.add(operation);
+    operation.then(
+      () => this.operations.delete(operation),
+      () => this.operations.delete(operation),
+    );
+    return operation;
+  }
+
+  private report(caught: unknown): void {
+    const error = caught instanceof Error ? caught : new Error("Voice operation failed");
+    try {
+      this.options.onError?.(error);
+    } catch {
+      // Voice observers cannot affect match scoring or fallback playback.
+    }
+  }
+}

package/src/match/voice/service.ts

@@ -0,0 +1,147 @@
+import { createExpoAudioPlayback } from "./audio";
+import { resolveBundledVoiceAsset } from "./bundled-assets";
+import { createGeminiVoiceEngine, createUnavailableVoiceEngine } from "./gemini-engine";
+import { buildVietnameseAnnouncement } from "./phrases";
+import { LatestAnnouncementScheduler } from "./scheduler";
+import type {
+  AudioPlayback,
+  MatchVoiceService,
+  NeuralVoiceEngine,
+  VoiceAudioMode,
+  VoiceRouteState,
+  VoiceTtsOptions,
+} from "./types";
+
+export interface DefaultMatchVoiceServiceOptions {
+  /** Cloud TTS endpoint. Without it, announcements always use the bundled WAVs. */
+  readonly tts?: VoiceTtsOptions;
+  readonly audioMode?: VoiceAudioMode;
+  /** Exact cache directory for generated WAVs. Primarily useful for tests. */
+  readonly generatedRoot?: string;
+  /** Primarily useful for tests. Defaults to expo-file-system removal. */
+  readonly removeGeneratedDirectory?: (path: string) => Promise<void>;
+  /** Primarily useful for native integration tests. */
+  readonly audio?: AudioPlayback;
+  /** Primarily useful for native integration tests. */
+  readonly engine?: NeuralVoiceEngine;
+}
+
+declare const require: (name: string) => any;
+
+function removeDirectory(path: string): void {
+  const fs = require("expo-file-system");
+  const info = fs.Paths.info(path);
+  if (!info.exists) return;
+  if (info.isDirectory) new fs.Directory(path).delete();
+  else new fs.File(path).delete();
+}
+
+export function createDefaultMatchVoiceService(
+  options: DefaultMatchVoiceServiceOptions = {},
+): MatchVoiceService {
+  const listeners = new Set<() => void>();
+  let lastError: Error | null = null;
+  let disposed = false;
+  let lifecycle: "active" | "disposing" | "disposed" = "active";
+  let initialized = false;
+  let operationTail: Promise<void> = Promise.resolve();
+  let disposePromise: Promise<void> | null = null;
+  let notificationQueue = Promise.resolve();
+  const audio = options.audio ?? createExpoAudioPlayback({ resolveSource: resolveBundledVoiceAsset });
+  const generatedDirectory = () =>
+    options.generatedRoot ??
+    `${require("expo-file-system").Paths.cache.uri}/pickleball-voice-generated/gemini`;
+  const engine =
+    options.engine ??
+    (options.tts
+      ? createGeminiVoiceEngine({ ...options.tts, generatedRoot: generatedDirectory() })
+      : createUnavailableVoiceEngine());
+  const scheduler = new LatestAnnouncementScheduler({
+    engine,
+    audio,
+    onError(error) {
+      lastError = error;
+      enqueueNotify();
+    },
+  });
+
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+
+  function enqueueNotify() {
+    notificationQueue = notificationQueue.then(() => {
+      if (!disposed) notify();
+    });
+  }
+
+  const unsubscribeAudio = audio.subscribeToRouteChanges?.(() => enqueueNotify());
+
+  async function sweepGeneratedAudio() {
+    await scheduler.clearCache();
+    try {
+      if (options.removeGeneratedDirectory) {
+        await options.removeGeneratedDirectory(generatedDirectory());
+      } else {
+        removeDirectory(generatedDirectory());
+      }
+    } catch {
+      // Best-effort cleanup of stale generated audio.
+    }
+  }
+
+  function runActive(operation: () => Promise<void>): Promise<void> {
+    if (lifecycle !== "active") return Promise.resolve();
+    const result = operationTail.then(async () => {
+      if (lifecycle === "active") await operation();
+    });
+    operationTail = result.catch(() => undefined);
+    return result;
+  }
+
+  const stillActive = () => lifecycle === "active";
+
+  return {
+    get audioState(): VoiceRouteState { return audio.getRouteState(); },
+    get lastError() { return lastError; },
+    initialize: () => runActive(async () => {
+      if (initialized) return;
+      await audio.configure(options.audioMode ?? "offline");
+      if (!stillActive()) return;
+      await sweepGeneratedAudio();
+      if (!stillActive()) return;
+      await scheduler.prewarm(["Đổi giao bóng.", "Điểm thắng ván.", "Đổi sân."]);
+      if (!stillActive()) return;
+      initialized = true;
+      notify();
+    }),
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    announce(previous, current, event) {
+      if (!stillActive()) return;
+      void scheduler.enqueue(buildVietnameseAnnouncement(previous, current, event)).catch((error) => {
+        lastError = error instanceof Error ? error : new Error("Announcement failed");
+        notify();
+      });
+    },
+    replayAnnouncement: () => stillActive() ? scheduler.replayLast() : Promise.resolve(),
+    testSpeaker: () => stillActive() ? scheduler.testSpeaker() : Promise.resolve(),
+    configureAudioMode: (mode) => runActive(async () => {
+      await audio.configure(mode);
+      if (stillActive()) enqueueNotify();
+    }),
+    dispose() {
+      if (disposePromise) return disposePromise;
+      lifecycle = "disposing";
+      disposed = true;
+      unsubscribeAudio?.();
+      disposePromise = (async () => {
+        await operationTail;
+        await scheduler.dispose();
+        await notificationQueue;
+        listeners.clear();
+        lifecycle = "disposed";
+      })();
+      return disposePromise;
+    },
+  };
+}

package/src/match/voice/types.ts

@@ -0,0 +1,118 @@
+import type { MatchEvent, MatchSnapshot } from "../contracts";
+
+export type AnnouncementKind =
+  | "score"
+  | "serviceChange"
+  | "gamePoint"
+  | "gameWon"
+  | "courtSwitch"
+  | "matchWon";
+
+export type FallbackVoiceToken =
+  | `number-${number}`
+  | "number-mot"
+  | "number-lam"
+  | `score-deu-${number}`
+  | "score-deu-mot"
+  | "score-deu-lam"
+  | "server-1"
+  | "server-2"
+  | "court-left"
+  | "court-right"
+  | "service-change"
+  | "game-point"
+  | "game-won"
+  | "court-switch"
+  | "match-won"
+  | "test-speaker";
+
+export interface AnnouncementPlan {
+  readonly kind: AnnouncementKind;
+  readonly text: string;
+  readonly score?: readonly [number, number];
+  readonly fallbackTokens: readonly FallbackVoiceToken[];
+}
+
+export type VoiceAudioRoute =
+  | "system"
+  | "bluetoothA2DP"
+  | "bluetoothHFP"
+  | "speaker"
+  | "headphones"
+  | "unknown";
+
+export type VoiceDisconnectReason =
+  | "oldDeviceUnavailable"
+  | "becomingNoisy"
+  | "unknown";
+
+export interface VoiceRouteState {
+  readonly route: VoiceAudioRoute;
+  readonly interrupted: boolean;
+  readonly disconnectedReason: VoiceDisconnectReason | null;
+}
+
+export type VoiceAudioMode = "offline" | "live";
+
+export interface AudioPlayback {
+  configure(mode: VoiceAudioMode): Promise<void>;
+  play(source: string): Promise<void>;
+  stop(): Promise<void>;
+  dispose(): Promise<void>;
+  getRouteState(): VoiceRouteState;
+  subscribeToRouteChanges?(listener: (state: VoiceRouteState) => void): () => void;
+}
+
+export type NeuralVoiceAvailability = "available" | "unavailable";
+
+export interface NeuralVoiceEngine {
+  availability(): Promise<NeuralVoiceAvailability>;
+  prewarm(commonPhrases: readonly string[]): Promise<void>;
+  synthesize(text: string, signal: AbortSignal): Promise<string>;
+  cancel(): Promise<void>;
+  release?(filePath: string): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+/** Cloud TTS endpoint the SDK posts announcement text to (see apps/proxy /voice/tts). */
+export interface VoiceTtsOptions {
+  readonly url: string;
+  /** Extra request headers, e.g. partner bearer tokens. Re-evaluated per request. */
+  readonly headers?: () =>
+    | Readonly<Record<string, string>>
+    | Promise<Readonly<Record<string, string>>>;
+  readonly voiceName?: string;
+  readonly languageCode?: string;
+  readonly requestTimeoutMs?: number;
+}
+
+export type VoiceErrorCode =
+  | "engine_unavailable"
+  | "network_unavailable"
+  | "synthesis_failed"
+  | "storage_failure"
+  | "playback_failed";
+
+export class VoiceError extends Error {
+  readonly name = "VoiceError";
+
+  constructor(
+    readonly code: VoiceErrorCode,
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+  }
+}
+
+export interface MatchVoiceService {
+  readonly audioState: VoiceRouteState;
+  readonly lastError?: Error | null;
+  initialize(): Promise<void>;
+  subscribe(listener: () => void): () => void;
+  announce(previous: MatchSnapshot, current: MatchSnapshot, event: MatchEvent): void;
+  replayAnnouncement(): Promise<void>;
+  testSpeaker(): Promise<void>;
+  configureAudioMode?(mode: VoiceAudioMode): Promise<void>;
+  dispose(): Promise<void>;
+}