Merge pull request 'codex/bundled-audio-announcements' (#1) from codex/bundled-audio-announcements into main

Reviewed-on: #1

web/src/components/AudioControl.tsx

@@ -0,0 +1,37 @@
+import type { RefObject } from "react";
+import type { AudioAnnouncementStatus } from "../hooks/useAudioAnnouncements";
+
+interface AudioControlProps {
+  audioRef: RefObject<HTMLAudioElement | null>;
+  status: AudioAnnouncementStatus;
+  onEnable: () => void;
+}
+
+export function AudioControl({ audioRef, status, onEnable }: AudioControlProps) {
+  return (
+    <>
+      <audio ref={audioRef} preload="auto" aria-hidden="true" />
+      {status === "ready" ? (
+        <aside className="speech-control speech-control--ready" role="status">
+          <strong>叫号声音已开启</strong>
+          <span>后续叫号将自动播报三次</span>
+        </aside>
+      ) : (
+        <aside className={`speech-control${status === "error" ? " speech-control--error" : ""}`} role="status">
+          <div>
+            <strong>{status === "error" ? "叫号声音开启失败" : "叫号声音尚未开启"}</strong>
+            <span>{status === "error" ? "请检查设备媒体音量后重试" : "请点击一次，之后将自动播报"}</span>
+          </div>
+          <button
+            className="button button--primary"
+            type="button"
+            disabled={status === "enabling"}
+            onClick={onEnable}
+          >
+            {status === "enabling" ? "正在开启叫号声音" : status === "error" ? "重新开启叫号声音" : "开启叫号声音"}
+          </button>
+        </aside>
+      )}
+    </>
+  );
+}

web/src/hooks/useAudioAnnouncements.test.ts

@@ -1,32 +1,37 @@
 import { describe, expect, it } from "vitest";
 import { announcementAudioQueue } from "./useAudioAnnouncements";
 
-const inlineAudio = (source: string) => source.startsWith("data:audio/wav;base64,");
-
 describe("announcementAudioQueue", () => {
   it("忽略项目名并把单号码播报素材重复三遍", () => {
-    const queue = announcementAudioQueue(["东门观光车，请零零零一六号，前往入口。"]);
-    const once = queue.slice(0, 9);
+    const once = [
+      "/audio/queue-voice/please.wav",
+      "/audio/queue-voice/digit-0.wav",
+      "/audio/queue-voice/digit-0.wav",
+      "/audio/queue-voice/digit-0.wav",
+      "/audio/queue-voice/digit-1.wav",
+      "/audio/queue-voice/digit-6.wav",
+      "/audio/queue-voice/number.wav",
+      "/audio/queue-voice/entrance.wav",
+      "/audio/queue-voice/gap.wav",
+    ];
 
-    expect(once).toHaveLength(9);
-    expect(once.every(inlineAudio)).toBe(true);
-    expect(once[1]).toBe(once[2]);
-    expect(once[2]).toBe(once[3]);
-    expect(queue).toEqual([...once, ...once, ...once]);
+    expect(announcementAudioQueue(["东门观光车，请零零零一六号，前往入口。"]))
+      .toEqual([...once, ...once, ...once]);
   });
 
   it("支持连续号码范围", () => {
     const queue = announcementAudioQueue(["请一七号至一九号，前往入口。"]);
 
-    expect(queue.slice(0, 9).every(inlineAudio)).toBe(true);
-    expect(queue[1]).not.toBe(queue[2]);
-    expect(queue[3]).not.toBe(queue[4]);
-  });
-
-  it("音频素材不使用独立 HTTP 路径", () => {
-    const queue = announcementAudioQueue(["请一号，前往入口。"]);
-
-    expect(queue).not.toContain("/audio/queue-voice/please.wav");
-    expect(queue.every(inlineAudio)).toBe(true);
+    expect(queue.slice(0, 9)).toEqual([
+      "/audio/queue-voice/please.wav",
+      "/audio/queue-voice/digit-1.wav",
+      "/audio/queue-voice/digit-7.wav",
+      "/audio/queue-voice/number.wav",
+      "/audio/queue-voice/through.wav",
+      "/audio/queue-voice/digit-1.wav",
+      "/audio/queue-voice/digit-9.wav",
+      "/audio/queue-voice/number.wav",
+      "/audio/queue-voice/entrance.wav",
+    ]);
   });
 });

web/src/hooks/useAudioAnnouncements.ts

@@ -1,41 +1,29 @@
-import { useCallback, useEffect, useRef } from "react";
-import digit0Audio from "../assets/queue-voice/digit-0.wav?inline";
-import digit1Audio from "../assets/queue-voice/digit-1.wav?inline";
-import digit2Audio from "../assets/queue-voice/digit-2.wav?inline";
-import digit3Audio from "../assets/queue-voice/digit-3.wav?inline";
-import digit4Audio from "../assets/queue-voice/digit-4.wav?inline";
-import digit5Audio from "../assets/queue-voice/digit-5.wav?inline";
-import digit6Audio from "../assets/queue-voice/digit-6.wav?inline";
-import digit7Audio from "../assets/queue-voice/digit-7.wav?inline";
-import digit8Audio from "../assets/queue-voice/digit-8.wav?inline";
-import digit9Audio from "../assets/queue-voice/digit-9.wav?inline";
-import entranceAudio from "../assets/queue-voice/entrance.wav?inline";
-import gapAudio from "../assets/queue-voice/gap.wav?inline";
-import numberAudio from "../assets/queue-voice/number.wav?inline";
-import pleaseAudio from "../assets/queue-voice/please.wav?inline";
-import throughAudio from "../assets/queue-voice/through.wav?inline";
+import { useCallback, useEffect, useRef, useState } from "react";
 
+export type AudioAnnouncementStatus = "locked" | "enabling" | "ready" | "error";
+
+const AUDIO_BASE_PATH = "/audio/queue-voice";
 const ANNOUNCEMENT_REPEAT_COUNT = 3;
-const GAP_AUDIO = gapAudio;
+const GAP_AUDIO = `${AUDIO_BASE_PATH}/gap.wav`;
 
 const DIGIT_AUDIO: Record<string, string> = {
-  零: digit0Audio,
-  一: digit1Audio,
-  二: digit2Audio,
-  三: digit3Audio,
-  四: digit4Audio,
-  五: digit5Audio,
-  六: digit6Audio,
-  七: digit7Audio,
-  八: digit8Audio,
-  九: digit9Audio,
+  零: `${AUDIO_BASE_PATH}/digit-0.wav`,
+  一: `${AUDIO_BASE_PATH}/digit-1.wav`,
+  二: `${AUDIO_BASE_PATH}/digit-2.wav`,
+  三: `${AUDIO_BASE_PATH}/digit-3.wav`,
+  四: `${AUDIO_BASE_PATH}/digit-4.wav`,
+  五: `${AUDIO_BASE_PATH}/digit-5.wav`,
+  六: `${AUDIO_BASE_PATH}/digit-6.wav`,
+  七: `${AUDIO_BASE_PATH}/digit-7.wav`,
+  八: `${AUDIO_BASE_PATH}/digit-8.wav`,
+  九: `${AUDIO_BASE_PATH}/digit-9.wav`,
 };
 
 const PHRASE_AUDIO = [
-  ["前往入口", entranceAudio],
-  ["请", pleaseAudio],
-  ["号", numberAudio],
-  ["至", throughAudio],
+  ["前往入口", `${AUDIO_BASE_PATH}/entrance.wav`],
+  ["请", `${AUDIO_BASE_PATH}/please.wav`],
+  ["号", `${AUDIO_BASE_PATH}/number.wav`],
+  ["至", `${AUDIO_BASE_PATH}/through.wav`],
 ] as const;
 
 function clipsForAnnouncement(announcement: string): string[] {
@@ -74,10 +62,14 @@ export function announcementAudioQueue(announcements: string[]): string[] {
 export function useAudioAnnouncements() {
   const audioRef = useRef<HTMLAudioElement | null>(null);
   const playbackIdRef = useRef(0);
+  const [status, setStatus] = useState<AudioAnnouncementStatus>("locked");
 
-  const playQueue = useCallback((sources: string[]) => {
+  const playQueue = useCallback((sources: string[], onStarted?: () => void) => {
     const audio = audioRef.current;
-    if (!audio || !sources.length) return;
+    if (!audio || !sources.length) {
+      setStatus("error");
+      return;
+    }
 
     const playbackId = ++playbackIdRef.current;
     audio.pause();
@@ -85,10 +77,18 @@ export function useAudioAnnouncements() {
     audio.onerror = null;
 
     let cursor = 0;
-    const fail = () => {
+    let started = false;
+    const markStarted = () => {
+      if (started || playbackIdRef.current !== playbackId) return;
+      started = true;
+      onStarted?.();
+    };
+    const fail = (error?: unknown) => {
       if (playbackIdRef.current !== playbackId) return;
+      if (error instanceof DOMException && error.name === "AbortError") return;
       audio.onended = null;
       audio.onerror = null;
+      setStatus("error");
     };
     const playNext = () => {
       if (playbackIdRef.current !== playbackId) return;
@@ -107,21 +107,28 @@ export function useAudioAnnouncements() {
       try {
         const result = audio.play();
         if (result && typeof result.then === "function") {
-          void result.catch(fail);
+          void result.then(markStarted).catch(fail);
+        } else {
+          markStarted();
         }
-      } catch {
-        fail();
+      } catch (error) {
+        fail(error);
       }
     };
 
     playNext();
   }, []);
 
+  const enable = useCallback(() => {
+    setStatus("enabling");
+    playQueue([`${AUDIO_BASE_PATH}/ready.wav`], () => setStatus("ready"));
+  }, [playQueue]);
+
   const announce = useCallback((announcements: string[]) => {
-    if (!announcements.length) return;
+    if (status !== "ready" || !announcements.length) return;
     const queue = announcementAudioQueue(announcements);
     if (queue.length) playQueue(queue);
-  }, [playQueue]);
+  }, [playQueue, status]);
 
   useEffect(() => () => {
     playbackIdRef.current += 1;
@@ -132,5 +139,5 @@ export function useAudioAnnouncements() {
     audio.onerror = null;
   }, []);
 
-  return { announce, audioRef };
+  return { announce, audioRef, enable, status };
 }

web/src/pages/DisplayPage.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { pollingResource } = vi.hoisted(() => ({
@@ -95,7 +95,7 @@ describe("DisplayPage", () => {
     ]);
   });
 
-  it("新批次出现时无需人工开启即可连续播报三次叫号内容", () => {
+  it("新批次出现时用内置音频连续播报三次叫号内容", async () => {
     const playedSources: string[] = [];
     vi.spyOn(HTMLMediaElement.prototype, "pause").mockImplementation(() => undefined);
     vi.spyOn(HTMLMediaElement.prototype, "play").mockImplementation(function (this: HTMLMediaElement) {
@@ -104,8 +104,13 @@ describe("DisplayPage", () => {
     });
     const { container, rerender } = render(<DisplayPage />);
 
-    expect(screen.queryByRole("button", { name: "开启叫号声音" })).not.toBeInTheDocument();
-    expect(screen.queryByText("叫号声音已开启")).not.toBeInTheDocument();
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: "开启叫号声音" }));
+      await Promise.resolve();
+    });
+    expect(screen.getByText("叫号声音已开启")).toBeVisible();
+    expect(playedSources).toEqual(["/audio/queue-voice/ready.wav"]);
+    playedSources.length = 0;
 
     pollingResource.data.current_batch = {
       batch_number: 3,

web/src/pages/DisplayPage.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from "react";
 import { useParams } from "react-router-dom";
 import { api } from "../api";
+import { AudioControl } from "../components/AudioControl";
 import { ProjectScreenTile } from "../components/ProjectScreenTile";
 import { useAudioAnnouncements } from "../hooks/useAudioAnnouncements";
 import { usePollingResource } from "../hooks/usePollingResource";
@@ -11,7 +12,7 @@ export { forecastRows } from "../lib/display";
 
 export function DisplayPage() {
   const { token = "" } = useParams();
-  const { announce, audioRef } = useAudioAnnouncements();
+  const { announce, audioRef, enable: enableAudio, status: audioStatus } = useAudioAnnouncements();
   const resource = usePollingResource((signal) => api.display(token, signal), {
     enabled: Boolean(token),
     intervalMs: 3_000,
@@ -69,7 +70,7 @@ export function DisplayPage() {
 
   return (
     <main className="single-display-screen">
-      <audio ref={audioRef} preload="auto" aria-hidden="true" />
+      <AudioControl audioRef={audioRef} status={audioStatus} onEnable={enableAudio} />
       {(resource.offline || stale || resource.error) ? (
         <div className="display-alert" role="status">
           <strong>{resource.offline ? "连接已中断" : "数据更新延迟"}</strong>

web/src/pages/PublicDisplayCenterPage.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { displayOverview, pollingResource } = vi.hoisted(() => ({
@@ -63,7 +63,7 @@ describe("PublicDisplayCenterPage", () => {
     expect(screen.queryByRole("navigation", { name: "管理任务" })).not.toBeInTheDocument();
   });
 
-  it("新叫号批次出现时无需人工开启即可连续三次播报号码", () => {
+  it("新叫号批次出现时只用内置音频连续三次播报号码", async () => {
     const playedSources: string[] = [];
     vi.spyOn(HTMLMediaElement.prototype, "pause").mockImplementation(() => undefined);
     vi.spyOn(HTMLMediaElement.prototype, "play").mockImplementation(function (this: HTMLMediaElement) {
@@ -72,8 +72,13 @@ describe("PublicDisplayCenterPage", () => {
     });
     const { container, rerender } = render(<PublicDisplayCenterPage />);
 
-    expect(screen.queryByRole("button", { name: "开启叫号声音" })).not.toBeInTheDocument();
-    expect(screen.queryByText("叫号声音已开启")).not.toBeInTheDocument();
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: "开启叫号声音" }));
+      await Promise.resolve();
+    });
+    expect(screen.getByText("叫号声音已开启")).toBeVisible();
+    expect(playedSources).toEqual(["/audio/queue-voice/ready.wav"]);
+    playedSources.length = 0;
 
     pollingResource.data = {
       ...pollingResource.data,

web/src/pages/PublicDisplayCenterPage.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 import { api } from "../api";
+import { AudioControl } from "../components/AudioControl";
 import { FeedbackBanner, FreshnessBanner, LoadingState } from "../components/Feedback";
 import { useAudioAnnouncements } from "../hooks/useAudioAnnouncements";
 import { usePollingResource } from "../hooks/usePollingResource";
@@ -12,7 +13,7 @@ function projectCurrentBatch(value: unknown): CallBatchDto | null {
 }
 
 export function PublicDisplayCenterPage() {
-  const { announce, audioRef } = useAudioAnnouncements();
+  const { announce, audioRef, enable: enableAudio, status: audioStatus } = useAudioAnnouncements();
   const resource = usePollingResource((signal) => api.displayOverview(signal), { intervalMs: 5_000 });
   const data = resource.data;
   const stale = Boolean(data) && isTimestampStale(resource.lastClientSuccessAt, 30_000);
@@ -37,7 +38,7 @@ export function PublicDisplayCenterPage() {
   return (
     <div className="app-shell app-shell--admin app-shell--no-primary-action">
       <a className="skip-link" href="#main-content">跳到主要内容</a>
-      <audio ref={audioRef} preload="auto" aria-hidden="true" />
+      <AudioControl audioRef={audioRef} status={audioStatus} onEnable={enableAudio} />
       <header className="app-header">
         <div className="brand-lockup" aria-label="景区排队叫号系统">
           <span className="brand-logo-frame" aria-hidden="true"><img className="brand-logo" src="/xiaoqikong-logo.jpg" alt="" /></span>