# FUStaSDK接口文档
本 SDK 集成了 FaceUnity 的语音驱动形象引擎(Speeach to Animation) ，能够快速构建并驱动虚拟形象说话，营造更加真实自然的人机交互场景。
## 版本信息
版本号:2.1
更新日期:2022-01-21
更新内容:
- 优化CPU性能以及查询效率
- 新增动画播放速度控制接口
- 更新BS系数57-47
- 修复静音帧问题
- ⽀新增设置旋转角度
- 优化阴影锯齿算法
- 增加详细日志接口
## APIs
SDK接口根据作用逻辑归为五类
- 配置初始化数据
- 初始化
- Avatar切换
- 渲染控制
- 口型查询和驱动
- Avatar动画和表情切换
- 销毁
- 其他
------
> ### 配置初始化数据
###### FUSta SDK配置初始化数据(在线鉴权数据)
FUStaKit.Builder builder = new FUStaKit
.Builder(mContext)
.setAuth(authpack.A())
.setAlignData(bytesAlign)
//.setAsrData(bytesAsr)
.setFUTtsType(FUTtsType.ALIGNMENT)
.setCharacterDecoder(bytesDecoder);
mFUStaKit = builder.build();
###### 接口说明
初始化FUSta，传入上下文（必要），
加载网络鉴权数据（必要），
设置语音自动校准工具包（Align模式需要设置），
设置语音识别工具包（ASR方式需要设置，此处是Align模式故注释该方法），
设置tts查询方式，必要（ASR方式需要设置：FUTtsType.ASR；Align方式需要设置：FUTtsType.ALIGNMENT，此处是Align模式故设置为FUTtsType.ALIGNMENT）
设置文字编码功能数据文件(ALIGN方式和文本时间戳需要设置)。
###### 参数说明
``` context ```：上下文
``` setAuth(byte[]) ```：网络鉴权数据
``` setAlignData(byte[]) ```：语音自动校准工具包数据
``` setAsrData(byte[]) ```：语音识别工具包数据
``` setFUTtsType(TtsTypeEnum type) ```：tts查询方式
``` setCharacterDecoder(byte[]) ```：文字编码功能数据
###### 备注：
App 启动后只需要 SDK配置初始化数据 一次即可，其中 authpack.A() 鉴权数据声明在 authpack.java 中。必须配置好有效的证书，SDK 才能正常工作。
在线鉴权只需要设置authpack.A() 鉴权数据即可。FUSta SDK 配置初始化数据详见"Android FUStaKit 集成文档"。
###### FUSta SDK配置初始化数据(离线鉴权数据)
FUStaKit.Builder builder = new FUStaKit
.Builder(mContext)
.setAuth(authpack.A())
.setAlignData(bytesAlign)
//.setAsrData(bytesAsr)
.setFUTtsType(FUTtsType.ALIGNMENT)
.setCharacterDecoder(bytesDecoder);
.setOffLineData(offLineAuth);
mFUStaKit = builder.build();
###### 接口说明
初始化FUSta，传入上下文（必要），
加载网络鉴权数据（必要），
设置语音自动校准工具包（Align模式需要设置），
设置语音识别工具包（ASR方式需要设置，此处是Align模式故注释该方法），
设置tts查询方式，必要（ASR方式需要设置：FUTtsType.ASR；Align方式需要设置：FUTtsType.ALIGNMENT，此处是Align模式故设置为FUTtsType.ALIGNMENT）
设置文字编码功能数据文件(ALIGN方式和文本时间戳需要设置)。
###### 参数说明
``` context ```：上下文
``` setAuth(byte[]) ```：网络鉴权数据
``` setAlignData(byte[]) ```：语音自动校准工具包数据
``` setAsrData(byte[]) ```：语音识别工具包数据
``` setFUTtsType(TtsTypeEnum type) ```：tts查询方式
``` setCharacterDecoder(byte[]) ```：文字编码功能数据
``` setOffLineData(byte[]) ```：离线鉴权数据
###### 备注：
App 启动后只需要 SDK配置初始化数据 一次即可，其中 authpack.A() 鉴权数据声明在 authpack.java 中。必须配置好有效的证书，SDK 才能正常工作。
离线鉴权除了设置authpack.A() 鉴权数据，还需要设置离线鉴权数据包路径：setOffLineAuth(byte[])。
注意，有key.bundle就使用key.bundle，这样会走离线；使用未鉴权的bundle，会联网鉴权。
根据应用需求，鉴权数据也可以运行时提供（如网络下载），不过要注意证书泄露风险，防止证书被滥用。FUSta SDK 配置初始化数据详见"Android FUStaKit 集成文档"。
---
> ### 初始化
###### FUSta SDK初始化（在线鉴权）
```
void init(FUAuthType.ONLINE, StaKitInitCallback listener);
```
###### 接口说明
调用FUSta SDK初始化方法，必须放在 FUStaKit SDK配置初始化数据之后
###### 参数说明
``` FUAuthType.ONLINE ```：在线鉴权
``` FUStaKit.StaKitInitCallback ```：SDK初始化状态的回调，参数位空即没有初始化完成回调的方式，如果调用该方法之后紧接着调用口型驱动方法，口型驱动任务会等待初始化任务完成才开始。开发者可根据初始化回调进行相关逻辑处理。
###### 备注：
init 初始化方法，务必在后续操作前调用，否则无法驱动口型。
FUSta SDK 初始化详见"Android FUStaKit 集成文档“。
###### FUSta SDK初始化（离线鉴权）
```
void init(FUAuthType.OFFLINE_BUNDLE, StaKitInitCallback listener);
```
###### 接口说明
调用FUSta SDK初始化方法，必须放在 FUStaKit SDK配置初始化数据之后
###### 参数说明
``` FUAuthType.OFFLINE_BUNDLE ```：离线鉴权
``` FUStaKit.StaKitInitCallback ```：SDK初始化状态的回调，参数位空即没有初始化完成回调的方式，如果调用该方法之后紧接着调用口型驱动方法，口型驱动任务会等待初始化任务完成才开始。开发者可根据初始化回调进行相关逻辑处理。
###### 备注：
init 初始化方法，务必在后续操作前调用，否则无法驱动口型。
FUSta SDK 初始化详见"Android FUStaKit 集成文档“。
---
> ### Avatar切换
###### FUSta SDK设置Avatar
```
void setAvatar(FUAvatar avatar, FUAvatarType avatarType);
或
void setAvatar(FUAvatar avatar, FUAvatarType avatarType, OnAvatarStateListener listener);
```
###### 接口说明
切换Avatar方法，设置后在渲染时会切换对应Avatar。
###### 参数说明
``` avatar ```：FUAvatar实例
``` avatarType ```：Avatar类型的枚举，用来表示Avatar类型，用来区别内置表情数据源，默认：`FUAvatarType.CARTOON`
``` listener ```：Avatar执行状态接口，实现接口，Avatar加载完成回调onAvatarComplete()
###### 备注：
###### FUSta SDK设置Avatar位置
```
void setPosition(double positionX, double positionY, double positionZ);
```
###### 接口说明
设置Avatar在坐标系的位置。
###### 参数说明
``` positionX ```：X轴坐标 范围`-200, 200`
``` positionY ```：Y轴坐标 范围`-600, 800`
``` positionZ ```：Z轴坐标 范围`-3000, 600`
###### 备注：
###### FUSta SDK设置Avatar背景
```
void setBackground(String background);
```
###### 接口说明
设置Avatar背景。
###### 参数说明
``` background ```：背景道具路径，background为空则背景透明
###### 备注：
###### FUSta SDK设置Avatar光照
```
void setLight(String light);
```
###### 接口说明
设置Avatar光照。
###### 参数说明
``` light ```：灯光道具路径
###### 备注：
###### FUSta SDK设置Avatar相机位
```
void setCamera(String camera);
```
###### 接口说明
设置Avatar相机位。
###### 参数说明
``` camera ```：相机道具路径
###### 备注：
###### FUSta SDK开启阴影
```
void enableShadow(Boolean enableShadow);
```
###### 接口说明
设置是否开启阴影。
###### 参数说明
``` enableShadow ```：是否开启阴影
###### 备注：
---
> ### 渲染控制
###### FUSta SDK开始渲染
```
void requestRender(GLTextureView glTextureView);
```
###### 接口说明
开始渲染。
###### 参数说明
``` glTextureView ```：GLTextureView，SDK提供的渲染View
###### 备注：
###### FUSta SDK渲染状态同步
```
void onResume();
void onPause();
void onDestroy();
```
###### 接口说明
onResume() 对应Activity onResume(),
onPause() 对应Activity onPause(),
onDestroy() 对应Activity onDestroy()。
###### 参数说明
###### 备注：
onResume()与onPause()成对出现，在Activity的onPause()调用时停止后台渲染减少消耗，并且在Activity的onResume()调用时重新加载。
onResume()与onPause()可不用调用，在Activity的onPause()调用时后台会继续渲染；
onDestroy()必须调用。
###### FUSta SDK设置渲染分辨率
```
void setCustomRenderResolution(int renderWidth, int renderHeight);
```
###### 接口说明
设置渲染分辨率尺寸。
###### 参数说明
``` renderWidth ```：纹理宽度
``` renderHeight ```：纹理宽度
###### 备注：
###### FUSta SDK设置渲染帧率
```
void setRenderFPS(int renderFPS);
```
###### 接口说明
设置渲染帧率，默认30帧/s。
###### 参数说明
``` renderFPS ```：渲染帧率
###### 备注：
如果低端设备最大帧率小于设置的帧率，实际帧率为该设备的最大帧率。
###### FUSta SDK设置抗锯齿
```
void setMultiSamples(int samples);
```
###### 接口说明
3D抗锯齿配置
###### 参数说明
``` samples ```：抗锯齿级别，默认4。
###### 备注：
###### FUSta SDK设置阴影抗锯齿
```
void setShadowPCFLevel(int level);
```
###### 接口说明
设置阴影抗锯齿级别
###### 参数说明
``` level ```：抗锯齿级别，默认2。
###### 备注：
###### FUSta SDK设置渲染信息回调接口
```
void setEnableDebug(boolean enableDebug)
void setStaRenderDebugListener(OnRenderDebugListener renderDebugListener);
```
###### 接口说明
设置渲染debug数据的回调
###### 参数说明
``` enableDebug ```：调试开关为true，相关debug数据才会进行统计。
``` renderDebugListener ```：渲染debug数据接口，onBenchmarkFPSChanged(int width, int height, double fps, double renderTime)。
###### 备注：
###### FUSta SDK日志保存到本地
```
void setLogOutputDir(String dir);
void enableLogOutput(boolean enableDebug)
```
###### 接口说明
SDK日志保存到本地
###### 参数说明
``` dir ```：设置保存到本地的指定目录。
``` enableDebug ```：是否保存日志信息到指定的目录。
###### 备注：
---
> ### 口型查询和驱动
###### FUSta SDK初始化播放器
```
void initStaPlayer(FUPlayerConfig playerConfig);
```
###### 接口说明
初始化播放器
###### 参数说明
``` playerConfig ```：播放器相关配置，主要是采样率、声道和位深，SDK根据播放器的配置内部会初始化对应播放器。
###### 备注：
该播放器用于内部播放，如采用外部播放器播放可不设置。
###### FUSta SDK口型驱动并且播放音频
```
void staProcess(FUStaParams staParams);
```
###### 接口说明
FUSta SDK查询口型系数，播放音频并驱动对应口型。
使用场景：
1、流式音频，有时间戳，只支持pcm
2、流式音频，无时间戳，只支持pcm
3、流式音频，无时间戳，有Align文本，只支持pcm
4、非流式音频，有时间戳，支持pcm与wav
5、非流式音频，无时间戳，支持pcm与wav
6、非流式音频，无时间戳，有Align文本，支持pcm与wav
###### 参数说明
``` params ```：FUStaParams为配置类，参数基本设置： 设置STA操作为非流式、设置音频数据、设置音频数据类型、设置音频数据对应时间戳等，目前支持 pcm 与 wav
###### 备注：
有时间戳，查询口型系数根据时间戳查询，速度会更快。
无时间戳，查询口型系数根据音频数据查询，根据机型配置不同耗时也有差别，查询速度稍耗时。一般无时间戳查询口型系数方式有ASR方式和ALIGN方式，ALIGN方式较快，ASR方式较慢。
FUStaParams参数详情与该口型驱动模式调用见```Android FUStaKit 集成文档```
###### FUSta SDK流式查询状态同步
```
void notifyStaProcessStart();
void notifyStaProcessFinish();
```
###### 接口说明
流式口型驱动模式下，需要给SDK同步查询状态。
notifyStaProcessStart()对应于流式查询开始调用；notifyStaProcessFinish()对应于流式查询结束调用。
###### 参数说明
###### 备注：
流式查询必须要给SDK设置同步状态。详情见```Android FUStaKit 集成文档```
###### FUSta SDK设置内部播放器状态接口
```
void setStaPlayerListener(OnStaPlayerListener staPlayerListener);
```
###### 接口说明
SDK采用内部播放器播放，播放器状态接口。
###### 参数说明
```OnStaPlayerListener```：实现该接口，相关方法定义：
```onPrepared()```：播放开始
```onCompleted()```：播放结束
```onCancel()```：播放取消
```onError(String message)```：播放出错
###### 备注：
###### FUSta SDK口型驱动（外部播放场景）
```
void staProcessNoPlayer(FUStaParams staParams);
```
###### 接口说明
FUSta SDK查询口型系数，外部播放器播放音频，需要两者配合驱动对应口型。
使用场景：
1、流式音频，有时间戳，只支持pcm
2、流式音频，无时间戳，只支持pcm
3、流式音频，无时间戳，有Align文本，只支持pcm
4、非流式音频，有时间戳，支持pcm与wav
5、非流式音频，无时间戳，支持pcm与wav
6、非流式音频，无时间戳，有Align文本，支持pcm与wav
###### 参数说明
``` params ```：FUStaParams为配置类，参数基本设置： 设置STA操作为非流式、设置音频数据、设置音频数据类型、设置音频数据对应时间戳等，目前支持 pcm 与 wav
###### 备注：
有时间戳，查询口型系数根据时间戳查询，速度会更快。
无时间戳，查询口型系数根据音频数据查询，根据机型配置不同耗时也有差别，查询速度稍耗时。一般无时间戳查询口型系数方式有ASR方式和ALIGN方式，ALIGN方式较快，ASR方式较慢。
FUStaParams参数详情与该口型驱动模式调用见```Android FUStaKit 集成文档```
###### FUSta SDK外部播放场景状态同步
```
void onExternalPlayerStart();
void onExternalPlayerStop();
```
###### 接口说明
SDK内部口型系数查询，外部播放器播放，两者配合驱动口型，需要给SDK同步播放器状态，设置口型驱动的开关。
onExternalPlayerStart()对应于外部播放器播放开始；onExternalPlayerStop()对应于外部播放器播放暂停或结束。
###### 参数说明
###### 备注：
外部播放场景必须要给SDK设置同步状态。详情见```Android FUStaKit 集成文档```
###### FUSta SDK设置外部播放器接口
```
void setExternalPlayerListener(OnExternalPlayerListener externalPlayerListener);
```
###### 接口说明
SDK内部口型系数查询，外部播放器播放，两者配合驱动口型，需要给SDK同步播放器进度，sdk拿到播放进度驱动对应的口型。
###### 参数说明
```OnExternalPlayerListener```：实现该接口，相关方法定义：
```updateCurrentPosition()```：获取外部播放器音频播放进度
###### 备注：
###### FUSta SDK设置音频数据查询状态的接口
```
void setStaProcessListener(OnStaProcessListener onStaProcessListener);
```
###### 接口说明
SDK内部口型系数查询，该接口会回调每一段查询音频数据的数据：`FUAudioProgressType`和内部处理过后的音频，该状态接口主要用于外部播放器场景下，为了规避口型系数查询耗时的影响，通知开发者SDK已经有口型查询完成，可以执行外部播放器播放逻辑。
###### 参数说明
```OnStaProcessListener```：实现该接口，相关方法定义：
```onStaProcess(FUAudioProgressType audioProgressType, byte[] data)```：回调每一段查询音频数据的数据
###### 备注：
```FUAudioProgressType```是`开始`、`中间`、`结束`、`整段`的枚举。`date`是每一段的音频，注意该音频不一定等于用户传入的音频格式和大小。
###### FUSta SDK停止口型查询和驱动
```
void stopStaProcess();
```
###### 接口说明
打断SDK内部口型系数查询任务，该接口会清掉已经查询的口型数据的缓存，停止内部播放器的播放。
###### 参数说明
###### 备注：
外部播放场景需要配合外部播放器停止方法和调用SDK外部播放器播放暂停或结束通知方法：`onExternalPlayerStop()`。
###### FUSta SDK设置英语口型张开幅度
```
void setENIntensity(float intensity);
```
###### 接口说明
设置英语口型张开幅度。
###### 参数说明
```intensity```：英语口型张开幅度，取值范围`1.0, 1.5`：
###### 备注：
---
> ### Avatar动画和表情切换
###### 动画循环播放
```
void playAnimation(String anim);
或
void playAnimation(String anim, String[] prop, String[] propAnimation);
```
###### 接口说明
循环播放Avatar动画。
###### 参数说明
```anim```：String，Avatar动画道具路径
```prop```：String[], 道具路径数组
```propAnimation```：String[], 道具动画路径数组
###### 备注：
###### 动画单次播放
```
void playAnimationOnce(String anim);
或
void playAnimationOnce(String anim, String[] prop, String[] propAnimation);
```
###### 接口说明
单次播放Avatar动画。
###### 参数说明
```anim```：String，Avatar动画道具路径
```prop```：String[], 道具路径数组
```propAnimation```：String[], 道具动画路径数组
###### 备注：
###### 继续播放当前动画
```
void startCurrentAnimation();
```
###### 接口说明
继续播放当前动画。
###### 参数说明
###### 备注：
###### 暂停播放当前动画
```
void pauseCurrentAnimation();
```
###### 接口说明
继续播放当前动画。
###### 参数说明
###### 备注：
###### 移除动画
```
void removeAnimation(String anim);
```
###### 接口说明
移除动画。
###### 参数说明
```anim```：String，要移除的Avatar动画道具路径
###### 备注：
###### 设置动画的过渡时间
```
void setAnimationTransitionTime(float time);
```
###### 接口说明
设置动画的过渡时间，单位为秒，默认0.5秒。
###### 参数说明
```time```：float，动画的过渡时间
###### 备注：
###### 设置动画的播放速度
```
void setAnimationSpeed(float speed);
```
###### 接口说明
设置动画的播放速度系数，默认为1，范围`0.2, 5.2`。
###### 参数说明
```speed```：float，播放速度系数
###### 备注：
###### 内置表情切换
```
void updateEmotion(FUEmotionType emotionType);
或
void updateEmotion(FUEmotionType emotionType, int fpsNum);
```
###### 接口说明
SDK内置表情切换，在`fpsNum`帧内过渡到目标表情。
###### 参数说明
```emotionType```：FUEmotionType，内置表情的枚举，目前只支持特定的Avatar类型（`FUAvatarType.CARTOON`和`FUAvatarType.REAL`）。
```fpsNum```：int，在`fpsNum`帧内过渡到目标表情，默认为0。
###### 备注：
###### 自定义表情切换
```
void updateCustomEmotion(String path);
或
void updateCustomEmotion(String path, int fpsNum);
```
###### 接口说明
自定义表情切换，通过传入自定义bs文件，内部解析并且驱动表情，在`fpsNum`帧内过渡到目标表情。
###### 参数说明
```path```：String，自定义表情的文件。
```fpsNum```：int，在`fpsNum`帧内过渡到目标表情，默认为0。
###### 备注：
###### 设置标签配置表
```
void setAlignTagConfig(String tagConfig, String defaultAnimation);
```
###### 接口说明
设置标签配置表，配合Align模式使用可定制动作表情切换的实际。
###### 参数说明
```tagConfig```：String，标签配置表
```defaultAnimation```：String，标签配置表动作执行完成后执行的默认动作道具路径
###### 备注：
标签配置表调用见```Android FUStaKit 集成文档```
---
> ### 销毁
###### 销毁 FUSta SDK
```
void release();
```
###### 接口说明
销毁SDK，释放内存资源。
###### 参数说明
###### 备注：
---
> ### 其他
###### 旋转Avatar
```
setRotDelta(float delta)
```
###### 接口说明
旋转角色。
###### 参数说明
```delta```：表示旋转增量，取值范围`-1.0, 1.0`
###### 备注：
###### 缩放Avatar
```
setScaleDelta(float delta)
```
###### 接口说明
缩放角色。
###### 参数说明
```delta```：表示缩放增量，取值范围`-1.0, 1.0`
###### 备注：
###### 上下移动Avatar
```
setTranslateDelta(float delta)
```
###### 接口说明
上下移动角色。
###### 参数说明
```delta```：表示上下增量，取值范围`-1.0, 1.0`
###### 备注：
###### 设置Avatar旋转角度
```
setRotate(float rotate)
```
###### 接口说明
设置Avatar旋转角度。
###### 参数说明
```rotate```：表示旋转角度
###### 备注：
###### 设置bs表情系数数据
```
setBSConfigData(String configPath)
```
###### 接口说明
设置当前Avatarbs表情系数数据包路径，可不设置，不设置则使用默认数据包
###### 参数说明
```configPath```：String，bs表情系数数据包路径
###### 备注：
---