面部表情

本节提供在 Web 应用中使用 convai-web-sdk 集成和处理面部表情与口型同步的全面信息。

⛔ 此插件已被弃用，不再受支持。

如果你仍在使用旧插件，我们建议切换到新的 Convai Web SDK： 链接

仅供历史参考——这些文档已不再维护。

初始化

要启动面部表情功能，请初始化 ConvaiClient 并传入必要参数。 enableFacialData 标志必须设置为 true 以启用面部表情数据。

convaiClient.current = new ConvaiClient({
  apiKey: '<apiKey>',
  characterId: '<characterId>',
  enableAudio: true,
  enableFacialData: true,
  faceModel: 3, // OVR 唇形同步
});

faceModel：3 为标准且持续维护的版本。

接收视觉素数据

通过加入提供的回调来获取视觉素数据。示例代码演示了如何处理并更新面部数据。

const [facialData, setFacialData] = useState([]);
const facialRef = useRef([]);

convaiClient.current.setResponseCallback((response) => {
if (response.hasAudioResponse()) {
    let audioResponse = response?.getAudioResponse();
      if (audioResponse?.getVisemesData()?.array[0]) {
      // 视觉素数据
        let faceData = audioResponse?.getVisemesData().array[0];
        // faceData[0] 表示 sil 值。当收到新的音频片段时，它为 -2。
          if (faceData[0] !== -2) {
            facialRef.current.push(faceData);
            setFacialData(facialRef.current);
          }
      }
}

调制形态目标

使用 useFrame 钩子，来自 react-three-fiber 根据接收到的面部数据调制形态目标。

import {OvrToMorph} from 'convai-web-sdk'
const blendShapeRef = useRef([]);
const currentBlendFrame = useRef(0);

useFrame((state, _delta) => {
 // 初始化混合形状
    if(client?.facialData.length > 0){
// 映射 reallusion 变形需要 OvrToMorph
    OvrToMorph(client?.facialData[currentBlendFrame.current],blendShapeRef);
    }
  if (currentBlendFrame.current <= blendShapeRef?.current?.length) {
    // 根据面部数据调整形态目标的逻辑
    currentBlendFrame.current += 1;
  }
});

除了面部表情之外， convai-web-sdk 还允许开发者为特定面部特征调制骨骼调整。接收“Open_Jaw”、“Tongue”和“V_Tongue_Out”的骨骼调整，并如下所示将其应用到你的角色上：

// 如果当前视觉素值是 Open_Jaw
characterRef.current.getObjectByName("CC_Base_JawRoot").setRotationFromEuler(jawRotation);
// 颌部旋转值可以使用 THREE.lerp() 进行调制。
// 示例
const jawRotation = new THREE.Euler(0,0,1.57);
// 这里 1.57 是闭合下颌的基础值。
jawRotation.z = THREE.MathUtils.lerp(jawRotation.z,1.57 + blendShapeRef.current[currentBlendFrame.current-1][blend]*0.2,0.8);

这些代码示例是针对 Reallusion 角色的。

处理 100fps 动画

实现 节流 使用 lodash 以确保在 100fps 下动画平滑。所提供的示例演示了如何保持一致的动画帧率。

const throttledUpdate = _.throttle(updateAnimation, 10);
const [tick, setTick] = useState(true);

const updateAnimation = () => {
  setTick((tick) => {
    if (tick) {
      return tick;
    }
    return true;
  });
  requestAnimationFrame(throttledUpdate);
};

// 在组件挂载时启动动画循环
useEffect(() => {
  requestAnimationFrame(throttledUpdate);
  // 在组件卸载时清理动画循环
  return () => {
    cancelAnimationFrame(throttledUpdate);
  };
}, []);

// 使用帧钩子更新动画
useFrame((state, _delta) => {
  if (tick) {
    // 获取视觉素数据并相应地更改形态目标的逻辑
    setTick(false);
  }
});

注意：节流函数并非 100% 精确

处理 100fps 边缘情况

节流精度可能会导致边缘情况。实现时钟设置，并使用经过时间处理高于和低于 100fps 的场景。

const [startClock, setStartClock] = useState(false);

useFrame((state, _delta) => {
  if (!startClock || !client?.isTalking) {
    state.clock.elapsedTime = 0;
    if (startClock) setStartClock(false);
  }
  if (client?.isTalking) {
    setStartClock(true);
  }
});

// 处理高于和低于 100fps 的场景
if (startClock) {
  if (Math.abs(Math.floor(state.clock.elapsedTime * 100) - currentBlendFrame.current) > 15) {
    if (Math.floor(state.clock.elapsedTime * 100) - currentBlendFrame.current > 0) {
      // 低于 100fps
           for(let i=0;i<15;i++){
              blendShapeRef.current.push(0)
            }
            currentBlendFrame.current += 15;
    } else {
      // 高于 100fps
       if(blendShapeRef.current.length > 15){
            blendShapeRef.current.splice(-15);
            currentBlendFrame.current -= 15;
       }
    }
  }
}