live2d-web 문서

MediaPipe 얼굴 트래킹

메인 스레드나 Worker에서 Standard·Perfect Sync 얼굴 트래킹을 연결합니다.

메인 스레드에서 트래킹

MediaPipe는 선택 의존성이며 live2d-web/tracking/mediapipe를 불러올 때만 로드됩니다. WASM, Face Landmarker 모델, 비디오 프레임, 실행 주기는 앱에서 제공합니다. 트래커는 변환된 값만 보관하며 원본 프레임과 랜드마크를 저장하지 않습니다.

import { createMediaPipeFaceTracker } from
  'live2d-web/tracking/mediapipe'
 
const tracker = await createMediaPipeFaceTracker({
  modelAssetPath: '/mediapipe/face_landmarker.task',
  wasmPath: '/mediapipe/wasm',
})
const detach = tracker.attach(character, {
  mapping: 'auto',
  channels: { mouth: false },
})
 
tracker.update(video, performance.now())
 
detach()
tracker.dispose()

선택형 Worker

Worker 모드를 사용하면 얼굴 추론을 렌더링 스레드에서 분리할 수 있습니다. update()는 비동기로 동작하며, 한 번에 한 프레임만 처리하고 추론 중에 들어온 프레임은 skipped로 마무리합니다. Worker 시작이 실패해도 메인 스레드로 자동 전환하지 않습니다. 초기화가 30초, 추론이 10초 안에 끝나지 않으면 tracking-error를 반환하고 해당 트래커를 종료합니다. 이후에는 새 Worker 트래커를 만들거나 메인 스레드 모드로 전환하세요.

const tracker = await createMediaPipeFaceTracker({
  execution: 'worker',
  modelAssetPath: '/mediapipe/face_landmarker.task',
  wasmPath: '/mediapipe/wasm',
  workerFactory: () => new Worker(
    new URL('./face-tracking.worker.ts', import.meta.url),
    { type: 'module' },
  ),
})

시작 단계와 모바일 상태

Playground는 카메라 준비, 트래커 생성, 첫 추론, 1초 보정, 최종 tracked 전환에 걸린 시간을 나눠 보여줍니다. MediaPipe JavaScript, WASM, task 파일의 Resource Timing도 함께 확인할 수 있습니다. 첫 시작이 느릴 때는 추론 속도 문제로 단정하지 말고 어느 단계에서 시간이 걸렸는지 먼저 확인하세요.

자산이 캐시된 로컬 환경에서는 3개 데스크톱 엔진 모두 트래커 생성 시간의 중앙값이 5초 미만이었습니다. 5초는 CI의 차단 기준이 아니라 로컬 확인을 위한 참고치입니다. 트래킹 벤치마크를 자동으로 실행하는 워크플로는 없습니다. iPhone Safari는 아직 실기기 검증이 필요하며 Android Chrome은 미검증 상태입니다. Worker를 시작할 수 없거나 시간 제한을 넘기면 tracking-error를 보여주고, 사용자가 Main thread로 다시 시작할 수 있게 하세요. 무한정 기다리거나 알리지 않고 다른 모드로 전환해서는 안 됩니다.

보정과 매핑 선택하기

처음 1초 동안 정면의 중립 표정을 유지하세요. 카메라 위치나 조명이 바뀌면 calibrate()를 다시 호출합니다. auto는 충분한 Perfect Sync 파라미터가 있을 때만 해당 매핑을 사용합니다. 마이크가 입을 제어한다면 mouth를 끄세요.

캡처와 정리는 앱에서 관리하기

트래커는 카메라 권한을 요청하거나 프레임을 예약하지 않습니다. 앱이 <video>, MediaStream, animation frame, visibility를 관리합니다. 중지할 때는 target 연결, tracker, 프레임 예약, 카메라 track을 모두 정리하세요.