live2d-web ドキュメント

MediaPipe フェイストラッキング

メインスレッドまたは Worker で、Standard と Perfect Sync のフェイストラッキングを使います。

メインスレッドでのトラッキング

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 を選ぶと、顔の推論を描画処理とは別のスレッドで実行できます。update() は非同期で、一度に1フレームだけを処理します。処理中に届いたフレームは待ち行列にためず、skipped として扱います。起動に失敗しても Main thread へ自動では切り替わりません。初期化は30秒、推論は10秒で打ち切られ、tracking-error で失敗します。その後は新しい Worker トラッカーを作るか、Main thread で作り直してください。

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 も確認できるため、初回起動が長いときにどの段階で待っているかを判断できます。

キャッシュ済みのファイルを使ったトラッカー作成は、3つのデスクトップブラウザで中央値5秒を十分に下回っています。この5秒は CI の合否基準ではなく、ローカルでの確認目安です。トラッキング性能の測定を自動実行するワークフローはありません。 iPhone Safari は実機での確認が必要で、Android Chrome は明示的に未検証です。 Worker の作成に失敗した場合や制限時間を超えた場合は tracking-error を表示し、 Main thread で作り直せる案内を用意してください。無期限に待たせたり、通知せずに自動で切り替えたりしないでください。

キャリブレーションとマッピング

最初の1秒は正面のニュートラルな表情を保ちます。カメラ位置や照明が変わったら calibrate() を再実行します。auto は必要数の Perfect Sync パラメーターがあるときだけ選択されます。

カメラと後始末はアプリが管理

トラッカーはカメラ権限やフレーム生成を所有しません。アプリが <video>、MediaStream、animation frame、visibility を管理します。停止時は target、tracker、フレーム、カメラ track をすべて解放してください。