PPI-969 헤드셋 연결/해제 시 오디오 출력 자동 재라우팅

🔍 이슈 배경

발생 현상

게스트(아동) 수업 중 USB 헤드셋을 재연결(뽑았다 꽂기)하거나 블루투스 헤드셋이 자동 재연결되면, 이미 setSinkId()로 바인딩된 오디오 엘리먼트가 이전 deviceId를 그대로 가리키게 됩니다. OS가 재연결 시 동일한 기기에 새로운 deviceId를 부여할 수 있기 때문에 핑퐁이 AI 음성과 활동 영상의 오디오가 무음으로 전환됩니다.

영향 범위

• 핑퐁이 AI 음성 — use-ai-session.ts의 audioElementRef
• 활동 영상 오디오 — meet-video.tsx의 videoRef
• 헤드셋 미사용 환경(기본 스피커)에서는 재현되지 않음

추가 결함 — mediaDevices 미지원 환경 TypeError

navigator.mediaDevices가 존재하지 않거나 addEventListener를 지원하지 않는 환경(일부 모바일 브라우저, 보안 컨텍스트 외 iframe 등)에서 navigator.mediaDevices.addEventListener("devicechange", …) 호출 시 TypeError가 발생했음.

🐛 기술적 원인

setSinkId()와 deviceId 생명주기

setSinkId(deviceId)는 호출 시점의 deviceId를 오디오 엘리먼트에 고정합니다. USB/블루투스 헤드셋이 재연결되면 OS가 새 deviceId를 생성하거나 기존 ID를 무효화할 수 있습니다. 브라우저는 바인딩된 ID가 사라져도 자동으로 setSinkId("")(기본 출력)로 fallback하지 않습니다.

devicechange 이벤트

Web Audio Output Devices API의 navigator.mediaDevices는 오디오/비디오 기기의 추가·제거·변경 시 devicechange 이벤트를 발화합니다. 이 이벤트를 구독하면 재연결을 감지하고 setSinkId()를 재호출해 복구할 수 있습니다.

연결/해제 시나리오별 처리 방침

🛠 수정 내용

1. use-ai-session.ts — AI 음성 오디오 엘리먼트

두 가지 변경이 이루어졌습니다.

① startSession 시 사전 생성 오디오 엘리먼트에도 setSinkId 적용

기존에는 new Audio()로 새 엘리먼트를 생성할 때만 setSinkId를 호출했음. 이미 audioElementRef.current에 엘리먼트가 존재하는 경우(세션 재시작)에는 setSinkId가 호출되지 않았음.

// 변경 전: new Audio() 생성 블록 안에서만 setSinkId 호출
if (!audioEl) {
  audioEl = new Audio();
  audioEl.autoplay = true;
  if (audioOutputDeviceId && typeof audioEl.setSinkId === "function") {
    await audioEl.setSinkId(audioOutputDeviceId);
  }
  audioElementRef.current = audioEl;
}

// 변경 후: 사전 생성 여부와 무관하게 최신 출력 기기 적용
if (!audioEl) {
  audioEl = new Audio();
  audioEl.autoplay = true;
  audioElementRef.current = audioEl;
}
if (audioOutputDeviceId && typeof audioEl.setSinkId === "function") {
  await audioEl.setSinkId(audioOutputDeviceId);
}

② devicechange 리스너 추가

useEffect(() => {
  if (!audioOutputDeviceId) return;
  if (!navigator.mediaDevices?.addEventListener) return; // 미지원 환경 가드

  const handleDeviceChange = async () => {
    const audioEl = audioElementRef.current;
    if (!audioEl || typeof audioEl.setSinkId !== "function") return;
    const devices = await navigator.mediaDevices.enumerateDevices().catch(() => []);
    const isAvailable = devices.some(
      (d) => d.kind === "audiooutput" && d.deviceId === audioOutputDeviceId,
    );
    audioEl.setSinkId(isAvailable ? audioOutputDeviceId : "").catch(() => {});
  };

  navigator.mediaDevices.addEventListener("devicechange", handleDeviceChange);
  return () => navigator.mediaDevices.removeEventListener("devicechange", handleDeviceChange);
}, [audioOutputDeviceId]);

2. meet-video.tsx — 활동 영상 오디오

audioOutputDeviceId prop을 새로 추가하고, 두 가지 effect를 연결했습니다.

① videoUrl 변경 시 setSinkId 적용

활동 스텝이 바뀌어 영상 URL이 교체되면 새 video 엘리먼트에 즉시 출력 기기를 바인딩합니다.

useEffect(() => {
  const video = videoRef.current;
  if (!video || !props.audioOutputDeviceId) return;
  if (typeof video.setSinkId !== "function") return;
  video.setSinkId(props.audioOutputDeviceId).catch((e) => {
    logger.warn("video setSinkId failed", { error: e, deviceId: props.audioOutputDeviceId });
  });
}, [props.audioOutputDeviceId, videoUrl]);

② devicechange 리스너 추가

use-ai-session.ts와 동일한 패턴으로 헤드셋 재연결 시 video 엘리먼트에도 재라우팅합니다.

useEffect(() => {
  const deviceId = props.audioOutputDeviceId;
  if (!deviceId) return;
  if (!navigator.mediaDevices?.addEventListener) return;

  const handleDeviceChange = async () => {
    const video = videoRef.current;
    if (!video || typeof video.setSinkId !== "function") return;
    const devices = await navigator.mediaDevices.enumerateDevices().catch(() => []);
    const isAvailable = devices.some(
      (d) => d.kind === "audiooutput" && d.deviceId === deviceId,
    );
    video.setSinkId(isAvailable ? deviceId : "").catch(() => {});
  };

  navigator.mediaDevices.addEventListener("devicechange", handleDeviceChange);
  return () => navigator.mediaDevices.removeEventListener("devicechange", handleDeviceChange);
}, [props.audioOutputDeviceId]);

📜 개발 히스토리 (커밋 순서)

✅ 최종 상태 요약

📋 변경 파일 요약