模型下发接口说明（V4）

随着离线合成的不断迭代，截止到 2023.04, 分化出来两类模型：V2 和 V4, V4 模型的音色显著优于 V2, 我们推荐所有新接入的业务方使用 V4 模型。但是 V4 的模型较大，不能再将所有音色打包进同一个文件中一次性下载。因此 V4 模型的下载逻辑与 V2 产生了一些差异。下面的接口说明仅用于V4模型下载, V2 模型下载请参考这里。

模型下发能力依赖语音SDK的网络功能, 在调用模型下发功能的初始化接口之前。必须先完成环境依赖的相关配置，详情可参考这里。

模型下发相关接口统一的状态码定义。

V4 模型的下载不再需要指定模型名，改为需指定语种、音色代号和引擎类型。

设置引擎类型

/// 设置语音SDK的引擎名称
/// 应该和 SE_PARAMS_KEY_ENGINE_NAME_STRING 的配置值相同
/// 须在 `setup` 之前调用
/// @param engineName 引擎名称
- (void)setSpeechEngineName:(NSString*)engineName;

指定是否使用线上模型

/// 是否使用线上资源
/// 须在 `setup` 之前调用
/// @param useOnlineModel 无特殊需求设置为 TRUE
- (void)setOnlineModelEnable:(BOOL)useOnlineModel;

指定模型存放路径

/// 指定模型下载路径，这个路径建议不要放其它文件，在模型升级时可能会先清空
/// 须在 `setup` 之前调用
/// @param rootPath 模型下载路径，需要是已经存在的目录
- (void)setRootPath:(NSString*)rootPath;

除了上述与 TTS 相关的信息外，还需要传入一些基础字段，包括 appid, device_id 等。

设置appid

/// 设置从火山申请得到的 appid
/// 须在 `setup` 之前调用
/// @param appId
- (void)setAppId:(NSString*)appId;

设置 device id

建议传真实的设备 ID, 方便在具体用户遇到模型下载相关问题时回溯用户行为。如明确不需要，可设置为 "0".

/// 设置可以唯一区别某台设备的 device id.
/// 须在 `setup` 之前调用
/// @param deviceId
- (void)setDeviceId:(NSString*)deviceId;

设置 APP version

/// 设置 APP 版本号，方便我们定位模型下载的问题
/// 须在 `setup` 之前调用
/// @param appVersion 建议设置为真实可用的版本号
- (void)setAppVersion:(NSString*)appVersion;

初始化

调用完上面的方法之后，最后调用初始化方法。

/// 语音资源管理器初始化
- (void)setup;

设置TTS语种

当前支持的语种如下

/// 设置想用使用的 TTS 语种
/// 须在 `setup` 之前调用
/// @param language 如 @[@"ZH_CN"]
- (void)setTtsLanguage:(NSArray*)language;

设置TTS音色代号

/// 设置想要使用的 TTS 音色
/// 须在 `setup` 之前调用
/// @param voiceTypes 如 @[@"BV001_streaming", @"BV002_streaming"]
- (void)setTtsVoiceType:(NSArray*)voiceType;

检查模型是否存在，不要在初始化执行完成后立刻进行检查。建议将初始化放在 App 启动时，并在需要时再检测模型是否存在。

/// 检查模型是否已经下载，具体用什么模型取决于 `setSpeechEngineName`, `setTtsVoiceType`, `setTtsLanguage` 方法传入的值
/// @return 是否已经下载
- (BOOL)checkModelExist;

云端更新模型需要冷启动才能生效。该接口为异步接口，调用时需提供回调。

/// 检查模型是否有更新，具体资源取决于 `setSpeechEngineName`, `setTtsVoiceType`, `setTtsLanguage` 方法传入的值，冷启动生效
/// @param listener 更新检查监听回调
- (void)checkModelVersion:(void (^)(SEResourceStatus status, BOOL needUpdate, NSData* data))completion;

示例代码

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
[speechResourceManager checkModelVersion:^(SEResourceStatus status, BOOL needUpdate, NSData *data) {
    if (status == kSERSuccess) {
        if (needUpdate) {
            NSLog(@"Model need update");
        } else {
            NSLog(@"Model doesn't need update");
        }
    } else {
        NSLog(@"Model check failed: %@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
    }
}];

回调参数说明

该接口为异步接口，调用时需提供回调。

/// 拉取模型，具体资源取决于 `setSpeechEngineName`, `setTtsVoiceType`, `setTtsLanguage` 方法传入的值
/// @param listener 资源下载监听回调
- (void)fetchModel:(void (^)(SEResourceStatus status, NSData* data))completion;

示例代码

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
[speechResourceManager fetchModel:^(SEResourceStatus status, NSData* data) {
    if (status == kSERSuccess) {
        NSLog(@"Model download succeed");
    } else {
        NSLog(@"Mode download failed");
    }
}];

回调参数说明

正常情况下模型会自动解压到 rootPath 目录，无需集成方解压。但解压后的模型文件可能因为某些难以预知的原因而损坏，这种情况下集成方可以主动调用解压接口来将已经下载到设备上的模型文件解压出来。

/// 解压指定模型，解压操作在调用者线程中执行
/// @param modelName 模型名:
/// 通过 fetchModel 下载的资源，传音色或者语种的名称.
/// @return BOOL: 解压是否成功
- (BOOL)extractModel:(NSString*)modelName;

获取模型路径。该接口只是返回模型路径，并不保证该路径存在或模型是否可用。但如果成功下载了模型，最终模型文件必定会在此路径下。获取路径方法的返回字符串可直接作为 SE_PARAMS_KEY_TTS_OFF_RESOURCE_PATH_STRING 的 value 字段传入 SDK 的 option 设置接口。

/// 获取通过 `fetchModel` 方法下载到的模型的路径
/// @return 资源路径，JSON 格式
- (NSString*)getModelPath;