하루 — AI VTuber 비서

**관련 시리즈** - [AI VTuber 에이전트 구축기 1편: 개요](https://hrletsgo.me/documents/vtuber-ai-assistant-series-1-introduction) - [AI VTuber 에이전트 구축기 2편: LLM과 페르소나](https://hrletsgo.me/documents/vtuber-ai-assistant-series-2-llm-persona) - [AI VTuber 에이전트 구축기 3편: 메모리](https://hrletsgo.me/documents/vtuber-ai-assistant-series-3-memory-system) - [AI VTuber 에이전트 구축기 4편: STT](https://hrletsgo.me/documents/vtuber-ai-assistant-series-4-stt) - [AI VTuber 에이전트 구축기 5편: TTS](https://hrletsgo.me/documents/vtuber-ai-assistant-series-5-tts) - AI VTuber 에이전트 구축기 6편: Live2D **(현재글)** - [AI VTuber 에이전트 구축기 7편: 방송 연동](https://hrletsgo.me/documents/vtuber-ai-assistant-series-7-streaming) - [AI VTuber 에이전트 구축기 8편: 운영](https://hrletsgo.me/documents/vtuber-ai-assistant-series-8-production) --- ## 들어가며 5편에서 하루는 말할 수 있게 됐다. XTTS-v2로 목소리를 만들고, 문장 단위 파이프라인으로 레이턴시를 줄이고, 감정에 따라 속도와 피치가 달라지는 TTS 시스템이 완성됐다. 그런데 화면이 비어 있다. 목소리는 스피커에서 나오는데 화면에 아무것도 없으면 VTuber가 아니라 라디오다. VTuber의 정체성은 **시각적 존재**에서 온다. Neuro-sama가 말할 때 입이 움직이고, 웃을 때 눈이 휘고, 가만히 있을 때도 숨을 쉰다. 그게 캐릭터다. 6편에서는 화면에 하루를 띄운다. Live2D 아바타를 브라우저에 렌더링하고, 말할 때 입이 움직이고, 감정에 따라 표정이 바뀌고, 침묵 중에도 눈을 깜빡이는 시스템을 만든다. 다룰 내용: 1. **Live2D Cubism Web SDK** — WebGL 기반 모델 렌더링 설정 2. **립싱크** — TTS 오디오 파형 분석으로 입 파라미터 실시간 제어 3. **감정 → 표정 매핑** — 2편의 EmotionState → Live2D Expression 자동 전환 4. **자동 모션 시스템** — 눈 깜빡임, 호흡, 시선 추적 5. **WebSocket 동기화** — 오디오 재생 타이밍과 애니메이션의 정밀한 동기화 --- ## Live2D Cubism Web SDK 개요 Live2D는 2D 일러스트를 3D처럼 움직이게 하는 기술이다. 모델은 `.moc3` 바이너리 파일로 배포되고, SDK가 이를 WebGL로 렌더링한다. 공식 SDK는 [Live2D 공식 사이트](https://www.live2d.com/sdk/download/web/)에서 직접 다운로드해야 한다. npm에 공개되어 있지 않다. 다운로드한 압축 파일 안에 `Core/`와 `Framework/` 디렉터리가 있다. 대안으로 **pixi-live2d-display** 라이브러리가 있다. PixiJS 위에 올라가는 래퍼로, npm 설치가 가능하고 API가 훨씬 간단하다. 단, SDK 버전 대응이 느리고 세밀한 파라미터 제어가 제한적이다. 이 시리즈에서는 립싱크와 표정 파라미터를 직접 건드려야 하므로 **공식 SDK** 기반으로 설명한다. ### 모델 파일 구조 Live2D 모델은 여러 파일로 구성된다. ``` assets/haru/ ├── haru.model3.json # 메인 설정 — 모든 리소스 경로 정의 ├── haru.moc3 # 모델 바이너리 (메시, 본, 변형 데이터) ├── haru.physics3.json # 물리 시뮬레이션 (머리카락, 리본 등) ├── haru.userdata3.json # 충돌 판정 등 사용자 정의 데이터 ├── textures/ │ ├── texture_00.png # 기본 텍스처 │ └── texture_01.png # 추가 텍스처 (의상 레이어 등) ├── motions/ │ ├── idle_01.motion3.json # 대기 모션 1 │ ├── idle_02.motion3.json # 대기 모션 2 │ └── ... └── expressions/ ├── happy.exp3.json # 기쁨 표정 ├── sad.exp3.json # 슬픔 표정 ├── surprised.exp3.json # 놀람 표정 └── ... ``` `haru.model3.json`이 진입점이다. 이 파일을 파싱해서 나머지 리소스 경로를 얻는다. ### SDK 설치 ``` live2d-sdk/ ├── Core/ │ ├── live2dcubismcore.js # Cubism Core (WebAssembly 래퍼) │ └── live2dcubismcore.d.ts └── Framework/ └── src/ # TypeScript 소스 ├── cubismframework.ts ├── model/ ├── motion/ ├── rendering/ └── ... ``` `Framework/src/`를 프로젝트에 복사하거나 심볼릭 링크로 연결한다. Core는 ` ``` --- ## CubismApp — 초기화와 WebGL 컨텍스트 SDK를 쓰려면 WebGL 컨텍스트와 CubismFramework를 순서대로 초기화해야 한다. ```typescript // src/frontend/live2d/cubism_app.ts import { CubismFramework, Option, LogLevel } from '../framework/src/live2dcubismframework'; import { HaruModel } from './haru_model'; export class CubismApp { private _canvas: HTMLCanvasElement; private _gl: WebGLRenderingContext; private _model: HaruModel | null = null; private _rafId: number = 0; constructor(canvas: HTMLCanvasElement) { this._canvas = canvas; const gl = canvas.getContext('webgl', { alpha: true, // 투명 배경 stencil: true, // 마스킹 필요 antialias: true, }); if (!gl) throw new Error('WebGL을 지원하지 않는 브라우저.'); this._gl = gl; } initialize(): boolean { // 뷰포트 설정 this._gl.viewport(0, 0, this._canvas.width, this._canvas.height); this._gl.clearColor(0.0, 0.0, 0.0, 0.0); // 투명 // CubismFramework 초기화 const option = new Option(); option.logFunction = (msg: string) => console.log('[Live2D]', msg); option.loggingLevel = LogLevel.LogLevel_Verbose; CubismFramework.startUp(option); CubismFramework.initialize(); return true; } async loadModel(modelDir: string, modelFileName: string): Promise { this._model = new HaruModel(this._gl); await this._model.load(modelDir, modelFileName); } startRenderLoop(): void { const loop = (timestamp: number) => { this._gl.clear(this._gl.COLOR_BUFFER_BIT); if (this._model) { this._model.update(timestamp); this._model.draw(); } this._rafId = requestAnimationFrame(loop); }; this._rafId = requestAnimationFrame(loop); } dispose(): void { cancelAnimationFrame(this._rafId); if (this._model) this._model.release(); CubismFramework.dispose(); } } ``` `alpha: true`가 중요하다. 배경을 투명으로 만들어야 하루 뒤에 다른 UI 요소(채팅창, 상태 표시 등)를 배치할 수 있다. --- ## HaruModel — 모델 로딩과 파라미터 제어 `CubismUserModel`을 상속해서 하루 전용 모델 클래스를 만든다. 이 클래스가 파라미터 제어의 중심이다. ```typescript // src/frontend/live2d/haru_model.ts import { CubismUserModel, CubismModelSettingJson, CubismIdManager, CubismMotionManager, CubismExpressionMotionManager, CubismPhysics, } from '../framework/src/...'; // 실제 경로는 SDK 구조에 따라 export class HaruModel extends CubismUserModel { private _gl: WebGLRenderingContext; private _modelSetting: CubismModelSettingJson | null = null; private _modelDir: string = ''; // 파라미터 ID 캐시 — 매 프레임 문자열 조회를 피하기 위함 private _idParamMouthOpenY: CubismId | null = null; private _idParamEyeLOpen: CubismId | null = null; private _idParamEyeROpen: CubismId | null = null; private _idParamBreath: CubismId | null = null; private _idParamAngleX: CubismId | null = null; private _idParamAngleY: CubismId | null = null; private _idParamEyeBallX: CubismId | null = null; private _idParamEyeBallY: CubismId | null = null; // 제어 값 private _mouthOpenY: number = 0.0; private _breathPhase: number = 0.0; private _blinkTimer: number = 0.0; private _blinkValue: number = 1.0; private _gazeX: number = 0.0; private _gazeY: number = 0.0; constructor(gl: WebGLRenderingContext) { super(); this._gl = gl; } async load(modelDir: string, modelFileName: string): Promise { this._modelDir = modelDir; // model3.json 로드 const settingJson = await this._fetchText(`${modelDir}/${modelFileName}`); this._modelSetting = new CubismModelSettingJson( new ArrayBuffer(0) // 실제로는 ArrayBuffer로 파싱 ); // moc3 로드 const mocPath = this._modelSetting.getModelFileName(); const mocBuffer = await this._fetchBuffer(`${modelDir}/${mocPath}`); this.loadModel(mocBuffer); // 텍스처 로드 const textureCount = this._modelSetting.getTextureCount(); for (let i = 0; i < textureCount; i++) { const texturePath = `${modelDir}/${this._modelSetting.getTextureFileName(i)}`; const texture = await this._loadTexture(texturePath); this.getRenderer().bindTexture(i, texture); } // 물리 시뮬레이션 const physicsPath = this._modelSetting.getPhysicsFileName(); if (physicsPath) { const physicsBuffer = await this._fetchBuffer(`${modelDir}/${physicsPath}`); this.loadPhysics(physicsBuffer, physicsBuffer.byteLength); } // 표정 로드 await this._loadExpressions(); // 모션 로드 await this._loadMotions(); // 파라미터 ID 캐싱 this._cacheParameterIds(); // 기본 대기 모션 시작 this.startIdleMotion(); } private _cacheParameterIds(): void { const idManager = CubismFramework.getIdManager(); this._idParamMouthOpenY = idManager.getId('ParamMouthOpenY'); this._idParamEyeLOpen = idManager.getId('ParamEyeLOpen'); this._idParamEyeROpen = idManager.getId('ParamEyeROpen'); this._idParamBreath = idManager.getId('ParamBreath'); this._idParamAngleX = idManager.getId('ParamAngleX'); this._idParamAngleY = idManager.getId('ParamAngleY'); this._idParamEyeBallX = idManager.getId('ParamEyeBallX'); this._idParamEyeBallY = idManager.getId('ParamEyeBallY'); } /** 외부에서 입 개폐 값을 주입 (0.0 ~ 1.0) */ setMouthOpenY(value: number): void { this._mouthOpenY = Math.max(0, Math.min(1, value)); } /** 시선 방향 주입 (-1.0 ~ 1.0) */ setGaze(x: number, y: number): void { this._gazeX = Math.max(-1, Math.min(1, x)); this._gazeY = Math.max(-1, Math.min(1, y)); } update(timestamp: number): void { const deltaTime = this._getDeltaTime(timestamp); // 모션 업데이트 (Live2D 내부 모션 시스템) this._model.saveParameters(); this._motionManager.updateMotion(this._model, deltaTime); this._model.restoreParameters(); // 호흡 애니메이션 this._updateBreath(deltaTime); // 눈 깜빡임 this._updateBlink(deltaTime); // 시선 — 마우스/설정값 반영 if (this._idParamAngleX) { this._model.addParameterValueById(this._idParamAngleX, this._gazeX * 30); } if (this._idParamAngleY) { this._model.addParameterValueById(this._idParamAngleY, this._gazeY * 30); } if (this._idParamEyeBallX) { this._model.addParameterValueById(this._idParamEyeBallX, this._gazeX); } if (this._idParamEyeBallY) { this._model.addParameterValueById(this._idParamEyeBallY, this._gazeY); } // 립싱크 — 외부 주입값 반영 if (this._idParamMouthOpenY) { this._model.addParameterValueById(this._idParamMouthOpenY, this._mouthOpenY); } // 물리 업데이트 this._physics?.evaluate(this._model, deltaTime); // 버텍스 업데이트 this._model.update(); } draw(): void { const gl = this._gl; const renderer = this.getRenderer(); renderer.setRenderState(gl.getParameter(gl.FRAMEBUFFER_BINDING), [0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight]); renderer.drawModel(); } // ... (리소스 해제, 텍스처 로드 등 헬퍼 메서드) } ``` `saveParameters()` / `restoreParameters()` 패턴이 중요하다. 모션 시스템이 파라미터를 덮어쓰기 전에 값을 저장하고, 모션 업데이트 후 우리가 추가한 값(립싱크, 시선 등)을 그 위에 얹는 구조다. --- ## 립싱크 — 입을 움직이는 법 립싱크의 원리는 단순하다. 오디오 파형의 **볼륨(RMS)** 을 계산해서 `ParamMouthOpenY`에 매핑한다. 완전한 입모양 매핑(viseme)은 훨씬 복잡하지만, RMS 기반만으로도 체감 자연스러움은 충분히 나온다. ```typescript // src/frontend/audio/lipsync.ts export class LipSyncAnalyzer { private _analyser: AnalyserNode; private _dataArray: Float32Array; private _smoothed: number = 0.0; // 스무딩 계수 — 클수록 움직임이 부드럽고 반응이 느림 private readonly SMOOTH_UP = 0.6; // 올라가는 속도 private readonly SMOOTH_DOWN = 0.85; // 내려가는 속도 (더 천천히) constructor(audioContext: AudioContext, source: AudioBufferSourceNode) { this._analyser = audioContext.createAnalyser(); this._analyser.fftSize = 2048; this._dataArray = new Float32Array(this._analyser.fftSize); source.connect(this._analyser); this._analyser.connect(audioContext.destination); } /** 현재 프레임의 입 개폐 값 계산 (0.0 ~ 1.0) */ getMouthOpenValue(): number { this._analyser.getFloatTimeDomainData(this._dataArray); // RMS 계산 let sumSquares = 0; for (const v of this._dataArray) { sumSquares += v * v; } const rms = Math.sqrt(sumSquares / this._dataArray.length); // 0~1 범위로 정규화 (경험적 스케일링) const normalized = Math.min(1.0, rms * 8.0); // 지수 스무딩 — 올라갈 때와 내려갈 때 다른 계수 적용 const smooth = normalized > this._smoothed ? this.SMOOTH_UP : this.SMOOTH_DOWN; this._smoothed = this._smoothed * smooth + normalized * (1 - smooth); return this._smoothed; } } ``` 스무딩에서 올라가는 속도(`SMOOTH_UP`)와 내려가는 속도(`SMOOTH_DOWN`)를 다르게 설정하는 이유가 있다. 입이 열릴 때는 빠르게 반응해야 발음이 인식되고, 닫힐 때는 천천히 내려가야 뚝뚝 끊기는 느낌이 없다. ### 오디오 청크 재생과 립싱크 연동 5편에서 Base64 WAV 청크를 받아 `AudioBufferSourceNode`로 재생했다. 이 노드를 `LipSyncAnalyzer`에 연결해야 한다. ```typescript // src/frontend/audio/player.ts (5편에서 확장) import { LipSyncAnalyzer } from './lipsync'; import { HaruModel } from '../live2d/haru_model'; export class AudioPlayer { private _context: AudioContext; private _nextStart: number = 0; private _lipSync: LipSyncAnalyzer | null = null; private _model: HaruModel | null = null; private _rafId: number = 0; constructor() { this._context = new AudioContext(); } setModel(model: HaruModel): void { this._model = model; } async playChunk(base64wav: string): Promise { const bytes = Uint8Array.from(atob(base64wav), c => c.charCodeAt(0)); const decoded = await this._context.decodeAudioData(bytes.buffer); const source = this._context.createBufferSource(); source.buffer = decoded; // LipSyncAnalyzer 연결 this._lipSync = new LipSyncAnalyzer(this._context, source); const now = this._context.currentTime; const startAt = Math.max(now, this._nextStart); source.start(startAt); this._nextStart = startAt + decoded.duration; // 재생이 시작되면 립싱크 루프 시작 const delay = Math.max(0, (startAt - now) * 1000); setTimeout(() => this._startLipSyncLoop(), delay); source.onended = () => { this._stopLipSyncLoop(); }; } private _startLipSyncLoop(): void { const loop = () => { if (!this._lipSync || !this._model) return; const value = this._lipSync.getMouthOpenValue(); this._model.setMouthOpenY(value); this._rafId = requestAnimationFrame(loop); }; this._rafId = requestAnimationFrame(loop); } private _stopLipSyncLoop(): void { cancelAnimationFrame(this._rafId); // 입을 서서히 닫기 if (this._model) this._model.setMouthOpenY(0); this._lipSync = null; } stop(): void { this._stopLipSyncLoop(); this._context.close(); this._context = new AudioContext(); this._nextStart = 0; } } ``` `AudioBufferSourceNode`를 AnalyserNode를 거쳐 destination에 연결하면 재생과 분석이 동시에 일어난다. 별도 스레드나 Worker 없이 메인 스레드에서 처리한다. --- ## 감정 → 표정 매핑 2편에서 LLM 응답에 `[EMOTION:happy]` 태그를 붙이도록 설계했다. 이 태그가 Live2D Expression과 연결되는 순간이다. Expression 파일(`.exp3.json`)은 파라미터 오프셋의 집합이다. `ParamEyeLSmile`, `ParamMouthForm` 같은 파라미터를 특정 값으로 이동시켜서 표정을 만든다. 어떤 파라미터가 있는지는 모델마다 다르기 때문에, 실제 `.exp3.json`을 열어서 확인해야 한다. ```typescript // src/frontend/live2d/emotion_mapper.ts import { EmotionState } from '../../shared/emotion'; // 감정 → Expression 파일명 매핑 // 실제 파일명은 모델 model3.json의 Expressions 배열에서 확인 export const EMOTION_EXPRESSION_MAP: Record = { [EmotionState.CALM]: null, // 기본 표정 (Expression 없음) [EmotionState.HAPPY]: 'happy', [EmotionState.CURIOUS]: 'curious', [EmotionState.EXCITED]: 'excited', [EmotionState.NERVOUS]: 'nervous', [EmotionState.PLAYFUL]: 'happy', // playful은 happy 표정 재활용 [EmotionState.TIRED]: 'tired', [EmotionState.CONCERNED]: 'sad', }; // 표정 전환 지속 시간 (ms) export const EXPRESSION_FADE_DURATION_MS = 500; ``` ```typescript // HaruModel에 표정 제어 메서드 추가 // src/frontend/live2d/haru_model.ts private _expressions: Map = new Map(); private async _loadExpressions(): Promise { const count = this._modelSetting!.getExpressionCount(); for (let i = 0; i < count; i++) { const name = this._modelSetting!.getExpressionName(i); const path = this._modelSetting!.getExpressionFileName(i); const buf = await this._fetchBuffer(`${this._modelDir}/${path}`); const exp = CubismExpressionMotion.create(buf, buf.byteLength); this._expressions.set(name, exp); } } /** 표정 전환. name이 null이면 기본 표정으로 복귀 */ setExpression(name: string | null): void { if (name === null) { this._expressionManager.stopAllMotions(); return; } const exp = this._expressions.get(name); if (!exp) { console.warn(`[HaruModel] 표정 없음: ${name}`); return; } this._expressionManager.startMotionPriority(exp, false, 2); } ``` WebSocket 메시지에서 감정 태그를 파싱하고 표정을 전환하는 흐름: ```typescript // src/frontend/voice_client.ts (WebSocket 핸들러 확장) import { EMOTION_EXPRESSION_MAP } from './live2d/emotion_mapper'; import { EmotionState } from '../shared/emotion'; import { HaruModel } from './live2d/haru_model'; export class VoiceClient { private _ws: WebSocket; private _model: HaruModel; private _audio: AudioPlayer; handleMessage(event: MessageEvent): void { const msg = JSON.parse(event.data); switch (msg.type) { case 'audio_chunk': // 5편 구현 그대로 — 오디오 재생 this._audio.playChunk(msg.audio_b64); break; case 'emotion': // 감정 태그 → 표정 전환 const emotion = msg.value as EmotionState; const expressionName = EMOTION_EXPRESSION_MAP[emotion] ?? null; this._model.setExpression(expressionName); break; case 'tts_end': // 발화 종료 → 기본 표정으로 서서히 복귀 setTimeout(() => this._model.setExpression(null), 1000); break; case 'interrupted': this._audio.stop(); this._model.setExpression(null); break; } } } ``` 서버에서 `emotion` 타입 메시지를 언제 보낼지도 정해야 한다. LLM 응답을 파싱할 때 `[EMOTION:xxx]` 태그를 감지하는 즉시 클라이언트로 전송한다. ```python # src/vtuber/api/voice.py — LLM 스트리밍 중 감정 태그 감지 import re EMOTION_TAG_PATTERN = re.compile(r'\[EMOTION:(\w+)\]') async def stream_with_emotion(ws: WebSocket, token_stream, ...): accumulated = '' async for token in token_stream: accumulated += token match = EMOTION_TAG_PATTERN.search(accumulated) if match: emotion = match.group(1).lower() # 클라이언트에 즉시 전송 await ws.send_text(json.dumps({ 'type': 'emotion', 'value': emotion, }, ensure_ascii=False)) # 태그는 텍스트에서 제거 후 TTS로 accumulated = EMOTION_TAG_PATTERN.sub('', accumulated) ``` --- ## 자동 모션 시스템 하루가 아무 말도 안 할 때 화면이 멈춰 있으면 어색하다. 눈이 깜빡이고, 숨을 쉬고, 시선이 약간 움직여야 살아있는 느낌이 난다. ### 눈 깜빡임 ```typescript // HaruModel._updateBlink() — 매 프레임 호출 private _blinkTimer: number = 0.0; private _blinkValue: number = 1.0; private _blinkState: 'open' | 'closing' | 'closed' | 'opening' = 'open'; private _blinkIntervalSec: number = this._nextBlinkInterval(); private _nextBlinkInterval(): number { // 2.5~6초 사이 랜덤 — 너무 규칙적이면 로봇처럼 보임 return 2.5 + Math.random() * 3.5; } private _updateBlink(deltaTime: number): void { this._blinkTimer += deltaTime; const CLOSE_SPEED = 0.1; // 눈 감는 데 걸리는 시간 (초) const OPEN_SPEED = 0.15; // 눈 뜨는 데 걸리는 시간 switch (this._blinkState) { case 'open': if (this._blinkTimer >= this._blinkIntervalSec) { this._blinkTimer = 0; this._blinkState = 'closing'; } this._blinkValue = 1.0; break; case 'closing': this._blinkValue = Math.max(0, this._blinkValue - deltaTime / CLOSE_SPEED); if (this._blinkValue <= 0) { this._blinkState = 'closed'; this._blinkTimer = 0; } break; case 'closed': this._blinkValue = 0.0; if (this._blinkTimer >= 0.05) { // 50ms 동안 감고 있음 this._blinkState = 'opening'; } break; case 'opening': this._blinkValue = Math.min(1, this._blinkValue + deltaTime / OPEN_SPEED); if (this._blinkValue >= 1.0) { this._blinkState = 'open'; this._blinkTimer = 0; this._blinkIntervalSec = this._nextBlinkInterval(); } break; } if (this._idParamEyeLOpen) { this._model.setParameterValueById(this._idParamEyeLOpen, this._blinkValue); } if (this._idParamEyeROpen) { this._model.setParameterValueById(this._idParamEyeROpen, this._blinkValue); } } ``` `setParameterValueById` vs `addParameterValueById`의 차이를 주의해야 한다. `set`은 값을 덮어쓰고, `add`는 현재 값에 더한다. 눈 깜빡임은 `set`을 써야 한다 — 모션 시스템의 눈 파라미터 위에 덮어씌우는 것이 의도다. ### 호흡 ```typescript private _breathPhase: number = 0.0; private _updateBreath(deltaTime: number): void { // 1회 호흡 주기: ~4초 const BREATH_CYCLE = 4.0; this._breathPhase = (this._breathPhase + deltaTime / BREATH_CYCLE) % 1.0; // 사인 곡선 — 0~1 범위 const breathValue = (Math.sin(this._breathPhase * Math.PI * 2) + 1.0) * 0.5; if (this._idParamBreath) { this._model.setParameterValueById(this._idParamBreath, breathValue); } } ``` ### 마우스 기반 시선 추적 마우스 커서가 어디 있느냐에 따라 하루의 시선이 따라온다. 시청자와 눈을 맞추는 느낌을 준다. ```typescript // src/frontend/live2d/gaze_tracker.ts export class GazeTracker { private _targetX: number = 0.0; private _targetY: number = 0.0; private _currentX: number = 0.0; private _currentY: number = 0.0; private readonly LERP = 0.05; // 시선 이동 속도 (클수록 빠름) constructor(canvas: HTMLCanvasElement) { canvas.addEventListener('mousemove', (e: MouseEvent) => { const rect = canvas.getBoundingClientRect(); // -1 ~ 1 정규화 this._targetX = ((e.clientX - rect.left) / rect.width - 0.5) * 2; this._targetY = ((e.clientY - rect.top) / rect.height - 0.5) * -2; }); } /** 매 프레임 호출 — 현재 시선 값 반환 */ update(): { x: number; y: number } { // 선형 보간으로 부드럽게 따라가기 this._currentX += (this._targetX - this._currentX) * this.LERP; this._currentY += (this._targetY - this._currentY) * this.LERP; return { x: this._currentX, y: this._currentY }; } /** 마우스가 캔버스 밖으로 나가면 정면으로 */ reset(): void { this._targetX = 0; this._targetY = 0; } } ``` ```typescript // CubismApp.startRenderLoop() 수정 const gazeTracker = new GazeTracker(this._canvas); const loop = (timestamp: number) => { this._gl.clear(this._gl.COLOR_BUFFER_BIT); if (this._model) { const gaze = gazeTracker.update(); this._model.setGaze(gaze.x, gaze.y); this._model.update(timestamp); this._model.draw(); } this._rafId = requestAnimationFrame(loop); }; ``` --- ## WebSocket 동기화 — 오디오와 애니메이션 오디오와 립싱크는 같은 AudioContext 안에서 처리하니 자동으로 동기화된다. 문제는 **감정 표정 전환 타이밍**이다. 서버에서 `emotion` 메시지가 오는 시점과 실제 그 감정이 담긴 오디오 청크가 재생되는 시점 사이에 딜레이가 있다. 오디오 청크는 큐에 쌓여서 순서대로 재생되기 때문에, 감정 태그를 감지한 즉시 표정을 바꾸면 동기가 어긋난다. 이를 맞추려면 감정 메시지를 오디오 청크와 함께 인덱스로 묶어서 전송해야 한다. ### 서버: 감정과 오디오 청크를 인덱스로 묶기 ```python # src/vtuber/api/voice.py async def stream_tts_to_client(ws: WebSocket, orchestrator, llm_stream, emotion): queue = OrderedAudioQueue() # 감정 메시지도 인덱스 기반으로 전송 async def on_sentence(sentence: str, index: int) -> None: # 해당 문장의 감정 태그 파싱 match = EMOTION_TAG_PATTERN.search(sentence) emotion_val = match.group(1).lower() if match else None if emotion_val: # audio_chunk 보다 먼저 emotion_hint 전송 # 클라이언트가 해당 chunk_index를 재생할 때 적용 await ws.send_text(json.dumps({ 'type': 'emotion_hint', 'chunk_index': index, 'emotion': emotion_val, }, ensure_ascii=False)) # ... (나머지 TTS 파이프라인) ``` ```typescript // src/frontend/voice_client.ts — 인덱스 기반 감정 적용 private _emotionHints: Map = new Map(); handleMessage(event: MessageEvent): void { const msg = JSON.parse(event.data); switch (msg.type) { case 'emotion_hint': // 해당 인덱스의 청크가 재생될 때 적용 this._emotionHints.set(msg.chunk_index, msg.emotion); break; case 'audio_chunk': // 이 청크에 연결된 감정이 있으면 먼저 표정 전환 const emotion = this._emotionHints.get(msg.index); if (emotion) { const expName = EMOTION_EXPRESSION_MAP[emotion as EmotionState] ?? null; this._model.setExpression(expName); this._emotionHints.delete(msg.index); } this._audio.playChunk(msg.audio_b64); break; } } ``` 완벽한 동기화는 AudioContext의 scheduled playback time을 써야 하지만, 문장 단위에서는 청크 재생 직전에 표정을 전환하는 것만으로도 실용적으로 충분하다. 사람 눈이 오디오-표정 사이 200~300ms 딜레이를 구분하지 못하기 때문이다. --- ## AnimationController — 전체 통합 모든 컴포넌트를 하나로 묶는 통합 클래스다. ```typescript // src/frontend/animation_controller.ts import { CubismApp } from './live2d/cubism_app'; import { HaruModel } from './live2d/haru_model'; import { GazeTracker } from './live2d/gaze_tracker'; import { AudioPlayer } from './audio/player'; import { VoiceClient } from './voice_client'; import { EmotionState } from '../shared/emotion'; import { EMOTION_EXPRESSION_MAP } from './live2d/emotion_mapper'; export class AnimationController { private _app: CubismApp; private _model: HaruModel | null = null; private _gaze: GazeTracker | null = null; private _audio: AudioPlayer; private _client: VoiceClient; constructor(canvas: HTMLCanvasElement, wsUrl: string) { this._app = new CubismApp(canvas); this._audio = new AudioPlayer(); this._client = new VoiceClient(wsUrl); // WebSocket 이벤트 → AnimationController로 라우팅 this._client.onAudioChunk = (b64wav, index) => this._onAudioChunk(b64wav, index); this._client.onEmotion = (emotion, idx) => this._onEmotion(emotion, idx); this._client.onTtsEnd = () => this._onTtsEnd(); this._client.onInterrupted = () => this._onInterrupted(); } async initialize(modelDir: string): Promise { this._app.initialize(); await this._app.loadModel(modelDir, 'haru.model3.json'); this._model = this._app.getModel(); this._audio.setModel(this._model); this._gaze = new GazeTracker(this._app.getCanvas()); this._app.setGazeTracker(this._gaze); this._app.startRenderLoop(); this._client.connect(); } private _onAudioChunk(b64wav: string, index: number): void { this._audio.playChunk(b64wav); } private _onEmotion(emotion: string, chunkIndex: number): void { if (!this._model) return; const expName = EMOTION_EXPRESSION_MAP[emotion as EmotionState] ?? null; this._model.setExpression(expName); } private _onTtsEnd(): void { // 1초 후 기본 표정으로 복귀 setTimeout(() => this._model?.setExpression(null), 1000); } private _onInterrupted(): void { this._audio.stop(); this._model?.setExpression(null); } dispose(): void { this._client.disconnect(); this._audio.stop(); this._app.dispose(); } } ``` 진입점은 단순하다. ```typescript // src/frontend/main.ts import { AnimationController } from './animation_controller'; const canvas = document.getElementById('live2d-canvas') as HTMLCanvasElement; canvas.width = 800; canvas.height = 600; const controller = new AnimationController( canvas, 'ws://localhost:8000/voice/ws' ); controller.initialize('/assets/haru').catch(console.error); // 페이지 언로드 시 정리 window.addEventListener('beforeunload', () => controller.dispose()); ``` --- ## HTML 레이아웃 ```html 하루 — AI VTuber 비서

``` 캔버스를 우측 하단에 고정해서 채팅창과 겹치게 배치하는 것이 일반적인 VTuber 방송 레이아웃이다. `alpha: true` WebGL 컨텍스트 덕분에 캔버스 배경이 투명하게 유지된다. --- ## 성능 최적화 ### 파라미터 ID 조회 캐싱 앞서 `_cacheParameterIds()`에서 처리했다. `CubismFramework.getIdManager().getId('ParamMouthOpenY')`를 매 프레임 호출하면 문자열 해시 탐색이 60fps * 여러 파라미터 = 초당 수백 번 발생한다. 로드 시점에 한 번만 조회해서 멤버 변수에 저장하는 것이 필수다. ### 렌더링 해상도 ```typescript // 디바이스 픽셀 비율 대응 const dpr = window.devicePixelRatio || 1; canvas.width = Math.floor(480 * dpr); canvas.height = Math.floor(640 * dpr); canvas.style.width = '480px'; canvas.style.height = '640px'; ``` Retina 디스플레이에서 캔버스를 CSS 크기 그대로 두면 흐리게 보인다. `devicePixelRatio`로 실제 픽셀 해상도를 올리고 CSS 크기는 논리 픽셀로 유지한다. ### AnalyserNode fftSize 립싱크 용도라면 `fftSize: 256`으로 낮춰도 충분하다. `fftSize: 2048`은 주파수 분석이 필요할 때 쓴다. RMS 계산에는 타임도메인 데이터만 필요하므로 낮은 fftSize가 더 효율적이다. ```typescript this._analyser.fftSize = 256; // 타임도메인 RMS만 쓸 경우 ``` --- ## 업데이트된 프로젝트 구조 6편까지 완성된 구조다. ``` vtuber-assistant/ ├── src/ │ ├── vtuber/ ← 백엔드 (Python/FastAPI) │ │ ├── api/ │ │ │ └── voice.py ← 감정 힌트 메시지 추가 │ │ ├── character/ ← 2편 │ │ ├── llm/ ← 2편 │ │ ├── memory/ ← 3편 │ │ ├── stt/ ← 4편 │ │ └── tts/ ← 5편 │ ├── frontend/ ← 프론트엔드 (TypeScript) │ │ ├── live2d/ ← 6편에서 추가 │ │ │ ├── cubism_app.ts # WebGL + CubismFramework 초기화 │ │ │ ├── haru_model.ts # 모델 로딩 + 파라미터 제어 │ │ │ ├── gaze_tracker.ts # 마우스 시선 추적 │ │ │ └── emotion_mapper.ts # 감정 → Expression 매핑 │ │ ├── audio/ │ │ │ ├── player.ts ← 립싱크 연동 추가 (5편 확장) │ │ │ ├── lipsync.ts ← 6편에서 추가 │ │ │ └── capture.ts ← 4편 │ │ ├── animation_controller.ts ← 6편에서 추가 (통합) │ │ ├── voice_client.ts ← 감정 힌트 처리 추가 │ │ └── main.ts │ └── shared/ │ └── emotion.ts ← EmotionState (프론트/백엔드 공유) ├── assets/ │ └── haru/ │ ├── haru.model3.json │ ├── haru.moc3 │ ├── haru.physics3.json │ ├── textures/ │ ├── motions/ │ └── expressions/ ├── public/ │ └── live2dcubismcore.js ← Live2D Core (직접 배치) └── live2d-sdk/ ← SDK 소스 (직접 다운로드) ├── Core/ └── Framework/ ``` --- ## 마무리 6편에서 구현한 것을 정리하면: 1. **CubismApp**: WebGL 컨텍스트 + CubismFramework 초기화, 렌더링 루프 관리 2. **HaruModel**: 모델 로딩, 파라미터 ID 캐싱, 파라미터 제어 인터페이스 3. **LipSyncAnalyzer**: Web Audio API AnalyserNode로 RMS 계산, 지수 스무딩으로 자연스러운 입 움직임 4. **눈 깜빡임**: 상태 머신 기반, 랜덤 주기로 로봇 같은 규칙성 제거 5. **호흡**: 사인 곡선, 4초 주기 6. **GazeTracker**: 마우스 위치 → 시선 파라미터, 선형 보간으로 부드럽게 7. **감정 표정**: `emotion_hint` 인덱스 기반 동기화로 오디오-표정 타이밍 일치 8. **AnimationController**: 전체 컴포넌트 통합, WebSocket 이벤트 라우팅 이제 하루는 **몸**을 가졌다. 말하면 입이 움직이고, 기쁘면 표정이 바뀌고, 침묵 속에도 숨을 쉰다. 1편에서 정의한 목표를 돌아보면 — 음성 대화가 가능하고, 기억이 있고, 캐릭터가 있고, 화면에서 살아있는 AI VTuber 비서. 6편까지 오면서 그 목표에 실질적으로 도달했다. 7편에서는 이것을 **실제로 방송에 쓸 수 있는 수준**으로 끌어올린다. OBS 연동, 다중 시청자 대화, 채팅 창 파싱, 그리고 하루가 24시간 무인으로 방송을 진행하는 자율 운영 시스템까지. --- ## 다음 편 예고 **[7편: 방송 연동 — 하루, 스트리머가 되다](https://hrletsgo.me/documents/vtuber-ai-assistant-series-7-streaming)** > _새벽 2시, 아무도 건드리지 않았는데 하루의 방송이 시작됐다._ 다루는 내용: - **OBS WebSocket 연동**: 씬 전환, 소스 제어를 서버에서 자동화 - **Twitch/YouTube 채팅 파싱**: 채팅창 메시지를 실시간으로 읽고 반응 - **다중 시청자 대화 관리**: 동시에 여러 시청자와 자연스럽게 대화하는 우선순위 큐 시스템 - **자율 방송 스케줄러**: 방송 시작, 코너 전환, 종료까지 무인 운영 - **운영 모니터링**: SSE 대시보드, 에러 감지, 자동 재시작