아바타 RMS 립싱크(canvas) — 코드 레벨 동작 흐름

마지막 업데이트 2026-07-22

1. 무엇이 바뀌었나 — canvas 합성으로의 전환

선행 구현은 talking <video>의 인라인 opacity를 직접 조작했다. 본 PR은 그 위에 전용 <canvas>를 덮고, 매 프레임 idle → talking 순으로 drawImage한 뒤 하단 페이드 그라데이션까지 그린다. PoC taeyang.html의 렌더 파이프라인을 그대로 옮긴 것이라 동일한 시각 품질을 보장한다.

2. 데이터 배선 — AI 오디오 스트림이 캔버스에 닿기까지

RMS 분석 대상은 핑퐁이(AI)의 출력 오디오 스트림이다. 게스트는 OpenAI Realtime output을, 모니터는 relay된 스트림을 사용하며, 둘 다 공유 컴포넌트 MeetAvatar로 모인다.

// 데이터 흐름 (리렌더 없이 ref + rAF로만 동작)
Guest   aiSession.aiAudioStream  (OpenAI Realtime output) ─┐
Monitor relay aiAudioStream      (mediasoup)              ─┘
                       │
              GuestLayoutContent(audioStream)
                       │
                MeetAvatar(audioStream)   ── rmsEnabled? ──▶ <canvas/> 마운트
                       │
        useAvatarRms({ audioStream, canvasRef, idleVideoRef, talkingVideoRef, enabled, params })
                       │
        AnalyserNode → RMS → requestAnimationFrame(loop) → canvas.drawImage

3. on/off 결정 트리 — 언제 RMS가 켜지나

meet-avatar.tsx:47 에서 rmsEnabled는 4개 조건의 AND다. 하나라도 거짓이면 canvas를 마운트하지 않고, 기존 CSS talkingVideoVisible 토글로 폴백한다(하위 호환).

4. 핵심 루프 — requestAnimationFrame 한 프레임의 일생

모든 실시간 로직은 use-avatar-rms.ts 의 loop() 한 함수에 있다. 매 프레임 아래 6단계를 순서대로 수행한다. 파라미터는 paramsRef로 읽어 튜닝 중에도 루프 재시작 없이 즉시 반영된다.

핵심 코드 (요약 발췌)

const loop = () => {
  if (cancelled) return;
  const p = paramsRef.current;          // 튜닝 즉시 반영 (deps 제외)

  // 1) RMS — 트랙이 살아있고 음소거 아닐 때만 계산
  let rawRMS = 0;
  if (analyser && audioCtx?.state === "running" && audioTrack?.readyState === "live" && !audioTrack.muted) {
    analyser.getByteFrequencyData(freqBuf);
    /* loBin..hiBin 제곱합 → sqrt(mean) */
  }
  // 2) 비대칭 평활화
  const alpha = rawRMS > smoothRMS ? p.attack : p.release;
  smoothRMS += alpha * (rawRMS - smoothRMS);

  // 3) 히스테리시스 재생/정지
  if (smoothRMS >= p.rmsThr && !isTalking) { isTalking = true; talkVid.play(); }
  else if (isTalking && smoothRMS < p.rmsThr * 0.4) { isTalking = false; talkVid.pause(); }
  if (isTalking) talkVid.playbackRate = p.playbackMin + Math.min(smoothRMS / p.rmsFull, 1) * p.playbackRange;

  // 5) 목표 opacity + 이징 (발화 종료 시 빠르게 닫힘)
  const speaking = smoothRMS >= p.rmsThr;
  const targetOpacity = (isTalking && speaking && talkVid.readyState >= 2)
    ? Math.min(smoothRMS / (p.rmsFull * p.opacityFullRatio), 1) : 0;
  const ease = targetOpacity > dispOpacity ? p.opacityRiseEase : p.opacityFallEase;
  dispOpacity += ease * (targetOpacity - dispOpacity);
  if (dispOpacity < 0.004) dispOpacity = 0;

  // 6) canvas 합성: idle → talking(alpha) → 하단 페이드
  ctx.globalAlpha = 1; ctx.drawImage(idleVid, 0, 0, CW, CH);
  if (dispOpacity > 0.015) { ctx.globalAlpha = dispOpacity; ctx.drawImage(talkVid, 0, 0, CW, CH); }
  /* 하단 linear-gradient fill */

  rafId = requestAnimationFrame(loop);   // 다음 프레임
};

5. 전역 파라미터 9종 — 기본값 · clamp · 의미

기본값은 PoC taeyang.html 검증값(language-guard-settings.types.ts AVATAR_RMS_DEFAULTS). 입력 시 use-language-guard-settings-store.ts:201 clampAvatarRms가 범위를 강제한다.

아래 고정 상수는 UI에 노출하지 않고 코드에 박혀 있다(taeyang 동일): FFT_SIZE=2048, ANALYSER_SMOOTHING=0.2, speech band 300–3500Hz, 하단 페이드 FADE_TOP_RATIO=0.78.

6. 저장 흐름 — 두 축, 두 경로

7. 변경 파일 한눈에

8. 함정 / 주의