本文介绍如何使用阿里云智能语音服务提供的C++ SDK,包括SDK的安装方法及SDK代码示例。
前提条件
下载安装
SDK下载
您可通过以下两种方法获取SDK。
方法一:从GitHub获取最新源码,详细编译和运行方式可见下文,或查看源码中的
readme.md
。git clone --depth 1 https://github.com/aliyun/alibabacloud-nls-cpp-sdk
方法二:直接从下文表中选取需要的SDK包进行下载。其中SDK源码包为SDK原始代码,需要通过下文编译方法生成集成所需的库文件。其他对应平台的SDK包内含相关库文件、头文件,无需编译。
最新SDK包
平台
MD5
SDK源码
e1d4f71f3db2e24fccd43f103573bea0
Linux x86_64
31f118233bd5b0fa2908989746aad284
说明以上Linux-x86_64版本使用gcc8.4.0 _GLIBCXX_USE_CXX11_ABI=0编译。可用源码包根据readme.md说明重新编译。
其中:
alibabacloud-nls-cpp-sdk<version>-master_<github commit id>.zip
为SDK源码包。NlsCppSdk_<平台>_<版本号>_<github commit id>.tar.gz
为对应平台下开发需要的SDK包,详见内部readme.md。
SDK包文件说明
scripts/build_linux.sh
:SDK源码中,以Linux平台为例的示例编译脚本。CMakeLists.txt
:SDK源码中,以Linux/Android平台为例的示例代码工程CMakeList
文件。demo目录:SDK包中,集成示例代码,以Linux平台为例,如下表所示。
文件名
描述
speechRecognizerDemo.cpp
一句话识别示例。
speechSynthesizerDemo.cpp
语音合成示例。
speechTranscriberDemo.cpp
实时语音识别示例。
flowingSynthesizerDemo.cpp
流式文本语音合成示例。
fileTransferDemo.cpp
录音文件识别示例。
resource目录:SDK源码中,语音服务范例音频,可用于功能测试,如下表所示。
文件名
描述
test0.wav
test1.wav
test2.wav
test3.wav
测试音频(16k采样频率、16bit采样位数的音频文件)。
include
:SDK源码中,SDK头文件,如下表所示。文件名
描述
nlsClient.h
SDK实例。
nlsEvent.h
回调事件说明。
nlsGlobal.h
SDK全局头文件。
nlsToken.h
SDK Access Token实例。
iNlsRequest.h
NLS请求基础头文件。
speechRecognizerRequest.h
一句话识别。
speechSynthesizerRequest.h
语音合成、长文本语音合成。
speechTranscriberRequest.h
实时音频流识别。
flowingSynthesizerRequest.h
流式文本语音合成。
FileTrans.h
录音文件识别。
lib
:SDK库文件。readme.md
:SDK说明。release.log
:版本更新说明。version
:版本号。
编译运行(Linux平台编译)
安装工具的最低版本要求如下:
CMake 3.0
Glibc 2.5
Gcc 4.8.5
在Linux终端运行如下脚本。
进入SDK源码的根目录。
生成SDK库文件和可执行程序:srDemo(一句话识别)、stDemo(实时语音识别)、syDemo(语音合成)、daDemo(语音对话)、fsDemo(流式文本语音合成)。
./scripts/build_linux.sh
查看范例使用方式。
cd build/demo ./fsDemo
关键接口
基础接口
NlsClient:语音处理客户端,利用该客户端可以进行一句话识别、实时语音识别和语音合成的语音处理任务。该客户端为线程安全,建议全局仅创建一个实例。
接口名
启用版本
功能描述
getInstance
2.x
获取(创建)
NlsClient
实例。setLogConfig
2.x
设置日志文件与存储路径。
setDirectHost
3.x
跳过
DNS
域名解析直接设置服务器IPV4
地址,若调用则需要在startWorkThread
之前。setAddrInFamily
3.1.12
设置套接口地址结构的类型,默认为
AF_INET
仅返回IPV4
相关的地址信息,需要在startWorkThread
之前调用。setUseSysGetAddrInfo
3.1.13
若
libevent
的DNS
无法满足,无法完成DNS
,可调用此接口切换成系统的接口,需要在startWorkThread
之前调用。calculateUtf8Chars
3.1.14
统计文本内容字符数,需要传入
UTF-8
编码的文本内容,其中1个汉字、1个英文字母或1个标点均算作1个字符。setSyncCallTimeout
3.1.17
设置同步调用模式的超时时间(ms), 0则为关闭同步模式,默认0。此模式
start()
后收到服务端结果再return出去,stop()
后收到close()
回调再return
出去。startWorkThread
3.x
启动工作线程数,默认1即启动一个线程,若-1则启动CPU核数的线程数。在高并发的情况下建议选择-1。可以理解NlsClient实例初始化,必须调用。
getVersion
3.x
获取SDK版本号。
releaseInstance
2.x
销毁
NlsClient
对象实例。createFlowingSynthesizerRequest
3.2
创建流式文本语音合成对象,线程安全,支持高并发请求。
releaseFlowingSynthesizerRequest
3.2
销毁流式文本语音合成对象,需要在当前请求的closed事件后调用。
NlsToken:创建Token对象,用于申请获取Token ID。申请新Token时需要先获取有效时间戳,若超过有效时间则再申请。若在有效时间内多次申请Token会导致Token ID错误而无法使用。
接口名
功能描述
setAccessKeyId
设置阿里云账号AccessKey ID。
setKeySecret
设置阿里云账号AccessKey Secret。
setDomain
设置域名,非必填。
setServerVersion
设置API版本,非必填。
setServerResourcePath
设置服务路径,非必填。
setRegionId
设置服务的确ID,非必填。
setAction
设置功能,非必填。
applyNlsToken
申请获取Token ID。
getToken
获取Token ID。
getExpireTime
获取Token有效期时间戳(秒)。
getErrorMsg
获得错误信息
NlsEvent:事件对象,您可以从中获取Request状态码、云端返回结果、失败信息等。
接口名
功能描述
getStatusCode
获取状态码,正常情况为0或者20000000,失败时对应失败的错误码。
getErrorMessage
在
TaskFailed
回调中,获取NlsRequest
操作过程中出现失败时的错误信息。getTaskId
获取任务的
TaskId
。getBinaryData
获取云端返回的二进制数据。
getAllResponse
获取云端返回的结果。
流式文本合成接口
接口说明以flowingSynthesizerRequest.h
内容为准。
接口名 | 启用版本 | 功能描述 |
setOnSynthesisStarted | 3.2 | 设置流式文本语音合成启动回调函数。 |
setOnSynthesisCompleted | 3.2 | 设置语音合成结束回调函数。 |
setOnChannelClosed | 2.x | 设置通道关闭回调函数。 |
setOnTaskFailed | 2.x | 设置错误回调函数。 |
setOnSentenceBegin | 3.2 | 服务端检测到了一句话的开始的回调函数。 |
setOnSentenceEnd | 3.2 | 服务端检测到了一句话的结束,返回该句的全量时间戳的回调函数。 |
setOnBinaryDataReceived | 2.x | 设置语音合成二进制音频数据接收回调函数。 |
setOnSentenceSynthesis | 3.2 | 增量返回语音合成的结果,包含最新的音频和时间戳、句内全量、句间增量的回调函数。 |
setOnMessage | 3.1.16 | 设置服务端 |
setAppKey | 2.x | 设置AppKey。 |
setToken | 2.x | 口令认证。所有的请求都必须通过 |
setUrl | 2.x | 设置服务URL地址。非必填。 |
sendText | 3.2 | 在同一个流式TTS会话中,单次合成不超过5000字,总计不超过10万字,其中1个汉字、1个英文字母、1个标点或1个句子中间空格均算作1个字符。 |
setVoice | 2.x | 发音人voice设置。 |
setVolume | 2.x | 音量volume设置。 |
setFormat | 2.x | 设置音频数据编码格式(默认是PCM,支持的格式:PCM、WAV、MP3)。 |
setSampleRate | 2.x | 音频采样率设置。 |
setSpeechRate | 2.x | 语速设置。 |
setPitchRate | 2.x | 语调设置。 |
setEnableSubtitle | 2.x | 是否开启字幕功能。 |
setPayloadParam | 2.x | 参数设置,入参为JSON格式字符串。 |
setTimeout | 2.x | 设置链接超时时间,默认5000ms。 |
setContextParam | 2.x | 设置用户自定义参数,入参为JSON格式字符串。 |
AppendHttpHeaderParam | 2.x | 设置用户自定义ws阶段 |
setSendTimeout | 3.1.14 | 设置发送超时时间,默认5000ms。 |
setEnableOnMessage | 3.1.16 | 设置开启服务器返回消息回调。 |
getTaskId | 3.1.17 | 获得当前请求的 |
start | 2.x | 启动 |
stop | 3.2 | 结束合成任务,后续需要等待合成完毕。 |
cancel | 2.x | 不会与服务端确认关闭,直接关闭语音合成过程。 |
代码示例
示例中将合成的音频保存在文件中,如果您需要播放音频且对实时性要求较高,建议使用流式播放,即边接收语音数据边播放,减少延时,而无需等待合成结束后再处理语音流。
完整示例,参见SDK压缩包中demo目录的flowingSynthesizerRequest.cpp文件。
调用接口前,需配置环境变量,通过环境变量读取访问凭证。智能语音交互的
AccessKey ID
、AccessKey Secret
和AppKey
的环境变量名:NLS_AK_ENV
、NLS_SK_ENV
、NLS_APPKEY_ENV
。
状态码
C++ SDK状态码
状态码 | 状态消息 | 原因 | 解决方案 |
0 | Success | 成功 | 无 |
-10 | DefaultError | 默认错误。 | 暂未使用。 |
-11 | JsonParseFailed | 错误的JSON格式。 | 请检查传入的 JSON 字符串是否符合 JSON 格式。 |
-12 | JsonObjectError | 错误的JSON对象。 | 建议重新尝试。 |
-13 | MallocFailed | Malloc失败。 | 请检查内存是否充足。 |
-14 | ReallocFailed | Realloc失败。 | 请检查内存是否充足。 |
-15 | InvalidInputParam | 传入无效的参数。 | 暂未使用。 |
-50 | InvalidLogLevel | 无效日志级别。 | 请检查设置的Log级别。 |
-51 | InvalidLogFileSize | 无效日志文件大小。 | 请检查设置的Log文件大小参数。 |
-52 | InvalidLogFileNum | 无效日志文件数量。 | 请检查设置的Log文件数量参数。 |
-100 | EncoderExistent | NLS的编码器已存在。 | 建议重新尝试。 |
-101 | EncoderInexistent | NLS的编码器不存在。 | 建议重新初始化。 |
-102 | OpusEncoderCreateFailed | Opus编码器创建失败。 | 建议重新初始化。 |
-103 | OggOpusEncoderCreateFailed | OggOpus编码器创建失败。 | 建议重新初始化。 |
-104 | InvalidEncoderType | encoder类型无效。 | 编译时可能关闭OPUS但是又使用,或请检查 |
-150 | EventClientEmpty | 主工作线程空指针, 已释放。 | 建议重新初始化,即 |
-151 | SelectThreadFailed | 工作线程选择失败, 未初始化。 | 建议重新初始化,即 |
-160 | StartCommandFailed | 发送start命令失败。 | 建议重新尝试 |
-161 | InvokeStartFailed | 请求状态机不对, 导致start失败。 | 请检查当前请求是否未创建或者已经完成。 |
-162 | InvokeSendAudioFailed | 请求状态机不对, 导致sendAudio失败。 | 请检查当前请求是否已经启动(即收到started事件回调)或者已经完成。 |
-163 | InvalidOpusFrameSize | opus帧长无效, 默认为640字节。 | OPU编码模式下, |
-164 | InvokeStopFailed | 请求状态机不对, 导致stop失败。 | 请检查当前请求是否未启动(即收到started事件回调)或者已经完成。 |
-165 | InvokeCancelFailed | 请求状态机不对, 导致stop失败。 | 请检查当前请求是否未启动(即收到started事件回调)或者已经完成。 |
-166 | InvokeStControlFailed | 请求状态机不对, 导致stControl失败。 | 请检查当前请求是否未启动(即收到started事件回调)或者已经完成。 |
-200 | NlsEventEmpty | NLS事件为空。 | SDK内部使用, NlsEvent帧丢失。 |
-201 | NewNlsEventFailed | 创建NlsEvent失败。 | SDK内部使用, NlsEvent帧创建失败。 |
-202 | NlsEventMsgEmpty | NLS事件中消息为空。 |
|
-203 | InvalidNlsEventMsgType | 无效的NLS事件中消息类型。 | SDK内部使用, NlsEvent帧的事件类型不合法。 |
-204 | InvalidNlsEventMsgStatusCode | 无效的NLS事件中消息状态码。 | SDK内部使用, NlsEvent帧的事件消息状态不合法。 |
-205 | InvalidNlsEventMsgHeader | 无效的NLS事件中消息头。 | SDK内部使用, NlsEvent帧的事件消息头不合法。 |
-250 | CancelledExitStatus | 已调用Cancel。 | 暂未使用。 |
-251 | InvalidWorkStatus | 无效的工作状态。 | SDK内部使用, 当前请求内部状态不合法。 |
-252 | InvalidNodeQueue | WorkThread中NodeQueue无效。 | SDK内部使用, 当前待运行的请求不合法,建议释放当前请求重新尝试。 |
-300 | InvalidRequestParams | 请求的入参无效。 | SendAudio传入的数据为空。 |
-301 | RequestEmpty | 请求是空指针。 | SDK内部使用, 当前请求已经释放,建议释放当前请求重新尝试。 |
-302 | InvalidRequest | 无效的请求。 | SDK内部使用, 当前请求已经释放,建议释放当前请求重新尝试。 |
-303 | SetParamsEmpty | 设置传入的参数为空。 | 请检查传入的参数是否为空。 |
-350 | GetHttpHeaderFailed | 获得http头失败。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-351 | HttpGotBadStatus | http错误的状态。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-352 | WsResponsePackageFailed | 解析WebSocket返回包失败。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-353 | WsResponsePackageEmpty | 解析WebSocket返回包为空。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-354 | WsRequestPackageEmpty | WebSocket请求包为空。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-355 | UnknownWsFrameHeadType | 未知WebSocket帧头类型。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-356 | InvalidWsFrameHeaderSize | 无效的WebSocket帧头大小。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-357 | InvalidWsFrameHeaderBody | 无效的WebSocket帧头本体。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-358 | InvalidWsFrameBody | 无效的WebSocket帧本体。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-359 | WsFrameBodyEmpty | 帧数据为空, 常见为收到了脏数据。 | SDK内部使用, 根据日志中反馈信息详细定位。 |
-400 | NodeEmpty | Node为空指针。 | 建议释放当前请求重新尝试。 |
-401 | InvaildNodeStatus | Node所处状态无效。 | SDK内部使用, 建议释放当前请求重新尝试。 |
-402 | GetAddrinfoFailed | 通过DNS解析地址识别。 | SDK内部使用, 请检查当前环境的DNS是否可用。 |
-403 | ConnectFailed | 联网失败。 | 请检查当前网络环境是否可用。 |
-404 | InvalidDnsSource | 当前设备无DNS。 | SDK内部使用, 请检查当前环境的DNS是否可用。 |
-405 | ParseUrlFailed | 无效URl。 | 请检查设置的URL是否有效。 |
-406 | SslHandshakeFailed | SSL握手失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-407 | SslCtxEmpty | SSL_CTX未空。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-408 | SslNewFailed | SSL_new失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-409 | SslSetFailed | SSL设置参数失败. | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-410 | SslConnectFailed | SSL_connect失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-411 | SslWriteFailed | SSL发送数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-412 | SslReadSysError | SSL接收数据收到SYSCALL错误。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-413 | SslReadFailed | SSL接收数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-414 | SocketFailed | 创建Socket失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-415 | SetSocketoptFailed | 设置Socket参数失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-416 | SocketConnectFailed | 进行Socket链接失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-417 | SocketWriteFailed | Socket发送数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-418 | SocketReadFailed | Socket接收数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-430 | NlsReceiveFailed | NLS接收帧数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-431 | NlsReceiveEmpty | NLS接收帧数据为空。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-432 | ReadFailed | 接收数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-433 | NlsSendFailed | NLS发送数据失败。 | SDK内部使用, 请检查当前网络环境是否可用,并再次尝试。 |
-434 | NewOutputBufferFailed | 创建buffer失败。 | SDK内部使用, 请检查内存是否充足。 |
-435 | NlsEncodingFailed | 音频编码失败。 | SDK内部使用, 建议释放当前请求重新尝试。 |
-436 | EventEmpty | event为空。 | SDK内部使用, 建议释放当前请求重新尝试。 |
-437 | EvbufferTooMuch | evbuffer中数据太多。 | SDK内部使用, 发送数据缓存已满(16K音频最大缓存320000,8K音频最大缓存160000),请检查是否发送音频数据过频或一次发送过多数据。 |
-438 | EvutilSocketFalied | evutil设置参数失败。 | SDK内部使用, 建议释放当前请求重新尝试。 |
-439 | InvalidExitStatus | 无效的退出状态。 | 请检查是否已经cancel了当前请求。 |
-450 | InvalidAkId | 阿里云账号AK ID无效。 | 请检查阿里云账号AK ID是否为空。 |
-451 | InvalidAkSecret | 阿里云账号AK Secret无效。 | 请检查阿里云账号AK Secret是否为空。 |
-452 | InvalidAppKey | 项目appKey无效。 | 请检查阿里云项目appKey是否为空。 |
-453 | InvalidDomain | domain无效。 | 请检查输入的domain是否为空。 |
-454 | InvalidAction | action无效。 | 请检查输入的action是否为空。 |
-455 | InvalidServerVersion | ServerVersion无效 | 请检查输入的ServerVersion是否为空。 |
-456 | InvalidServerResource | ServerResource无效。 | 请检查输入的ServerResource是否为空。 |
-457 | InvalidRegionId | RegionId无效。 | 请检查输入的Region Id是否为空。 |
-500 | InvalidFileLink | 无效的录音文件链接 | 录音文件转写文件链接为空。 |
-501 | ErrorStatusCode | 错误的状态码。 | 录音文件转写返回错误,详见错误码。 |
-502 | IconvOpenFailed | 申请转换描述失败。 | UTF8与GBK转换失败。 |
-503 | IconvFailed | 编码转换失败。 | UTF8与GBK转换失败。 |
-504 | ClientRequestFaild | 账号客户端请求失败。 | 录音文件转写返回失败。 |
-999 | NlsMaxErrorCode | 无 | 无 |
其他状态码
状态码 | 状态消息 | 原因 | 解决方案 |
10000001 |
|
| 建议重新初始化。 |
10000002 |
|
| 建议重新尝试。 |
| |||
10000003 |
| 系统错误 | 根据系统反馈的错误信息进行处理。 |
10000004 |
|
| 传入的URL为空, 请重新填写正确URL。 |
10000005 |
|
| 传入的URL格式错误, 请重新填写正确URL。 |
10000007 |
|
| JSON格式异常, 请通过日志查看具体的错误点。 |
10000008 |
|
| 联网失败,请检查本机DNS解析和URL是否有效。 |
10000009 |
|
| 与云端连接失败,请检查网络后,重试。 |
10000010 |
| 内存不足 | 请检查内存是否充足。 |
10000015 |
|
| 联网失败,请检查本机DNS解析和URL是否有效。 |
10000100 |
|
| 链接被拒,请检查账号特别是token是否过期。 |
10000101 |
|
| libevent发送event超时,请检查回调中是否有耗时任务,或并发过大导致无法及>时处理事件。 |
10000102 |
|
| libevent接收event超时,请检查回调中是否有耗时任务,或并发过大导致无法及>时处理事件。 |
10000103 |
|
| 未知的libevent事件,建议重新尝试。 |
10000104 |
|
| 链接正在进行中,建议重新尝试。 |
10000105 |
|
| pipe处理不过来,建议重新尝试。 |
10000110 |
|
| 请更新Token。 |
10000111 |
|
| 请检查Token的有效性。 |
10000112 |
|
| 此发音人无权使用。 |
10000113 |
|
| 请检查账号是否有权限,或并发是否在限度内。 |
10000120 |
|
| UTF-8转码失败,常为系统问题,建议重新尝试。 |
20000000 |
| 成功 |
服务端响应状态码
关于服务状态码,请参见服务状态码。