实时口型同步

将实时面部动画集成到你的 React 应用中。

支持的格式

ARKit（61 个元素）

苹果的 ARKit blendshape 格式，包含 52 个面部 blendshapes + 9 个旋转值：

• 52 个标准面部 blendshape（眼睛、眉毛、下颌、嘴巴、脸颊、鼻子）
• 3 个头部旋转值（俯仰、偏航、翻滚）
• 6 个眼部旋转值（左/右眼注视）

MetaHuman（251 个元素）

Unreal Engine 的 MetaHuman 格式，包含 251 个 CTRL_expressions_* blendshapes：

• 全面的面部控制（眉毛、眼睛、脸颊、鼻子、嘴巴、下颌）
• 高度精细的嘴型，用于精准口型同步
• 高保真角色动画的行业标准

配置选项

ConvaiConfig（useConvaiClient）

interface ConvaiConfig {
  // ... 其他选项
  
  /**
   * 启用 lipsync/面部动画 blendshape（默认：false）。
   * 启用后，以 60fps 流式传输实时 blendshape 数据。
   */
  enableLipsync?: boolean;
  
  /**
   * 从服务器接收的 blendshape 格式（默认：'mha'）。
   * 'arkit' - 61 个元素（52 个 blendshape + 9 个旋转值）
   * 'mha' - 251 个元素（MetaHuman 格式）
   */
  blendshapeFormat?: 'arkit' | 'mha';
}

包含所有选项的示例

const convaiClient = useConvaiClient({
  apiKey: '你的-api-key',
  characterId: '你的-character-id',
  enableVideo: true,
  enableLipsync: true,
  blendshapeFormat: 'arkit',
  startWithVideoOn: false,
});

访问 Blendshape 队列

blendshape 队列可在客户端实例上使用：

import { useConvaiClient } from '@convai/web-sdk';
import { useEffect, useRef } from 'react';
import * as THREE from 'three';
import { useGLTF } from '@react-three/drei';

function CharacterController() {
  const convaiClient = useConvaiClient({<ConvaiConfig>});
  const characterRef = useRef<THREE.SkinnedMesh | null>(null);
  const startTimeRef = useRef<number>(0);
  const { scene } = useGLTF('/character.glb');
  
  useEffect(() => {
    // 在加载的模型中查找面部 SkinnedMesh
    scene.traverse((child) => {
      if (child instanceof THREE.SkinnedMesh && child.morphTargetInfluences) {
        if (child.name.toLowerCase().includes('head') || 
            child.name.toLowerCase().includes('face') ||
            child.morphTargetInfluences.length > 50) {
          characterRef.current = child;
        }
      }
    });
  }, [scene]);
  
  // 跟踪机器人何时开始说话
  useEffect(() => {
    const unsubscribe = convaiClient.on('speakingChange', (isSpeaking: boolean) => {
      if (isSpeaking) {
        startTimeRef.current = performance.now();
      }
    });
    
    return unsubscribe;
  }, [convaiClient]);
  
  useEffect(() => {
    if (!convaiClient.state.isConnected) return;
    
    let animationId: number;
    
    const animate = () => {
      const queue = convaiClient.blendshapeQueue;
      
      if (queue.hasFrames() && queue.isConversationActive()) {
        // 计算机器人开始说话以来经过的时间
        const elapsedTime = (performance.now() - startTimeRef.current) / 1000;
        
        // 根据经过时间获取帧（与音频同步）
        const result = queue.getFrameAtTime(elapsedTime);
        
        if (result && characterRef.current?.morphTargetInfluences) {
          applyBlendshapesToCharacter(result.frame, characterRef.current.morphTargetInfluences);
        }
      }
      
      animationId = requestAnimationFrame(animate);
    };
    
    animate();
    
    return () => cancelAnimationFrame(animationId);
  }, [convaiClient.state.isConnected]);
  
  return <primitive object={scene} />;
}

// 辅助函数：将 blendshape 应用到角色
function applyBlendshapesToCharacter(frame: Float32Array, influences: number[]) {
  const maxIndex = Math.min(frame.length, influences.length);
  for (let i = 0; i < maxIndex; i++) {
    influences[i] = frame[i];
  }
}