# 语音转写 Java SDK 文档

# 1、简介

语音转写(Long Form Automatic Speech Recognition):基于科大讯飞独立研究的深度全序列卷积神经网络语音识别框架(Deep Fully Convolutional Neural Network, DFCNN),针对语音的长时相关性进行语言建模,将音频数据转换成文本数据,为后续的信息处理和数据挖掘提供基础。 具体表现形式为,将多种格式的长段音频文件(5小时以内)转换成包含时间戳、词句置信度、词属性以及句子标志的文字信息。文字信息提供分词形式以及整段文字形式以及发音人分离功能。

转写的是已录制音频(非实时),音频文件上传成功后进入等待队列,待转写成功后用户即可获取结果,返回结果时间受音频时长以及排队任务量的影响。如遇转写耗时比平时延长,大概率表示当前时间段出现转写高峰,即有任务积压排队,属正常现象,请耐心等待
为使转写服务更加通畅,请尽量转写5分钟以上的音频文件,上传大量的短音频易引起网络和服务器资源紧张,从而导致任务排队积压。
另外,语音转写是SLA协议对象服务之一,我们对付费用户承诺有效任务耗时最大不超过12小时,赔偿标准等详情请参考SLA协议

SDK下载请点击 语音转写JAVA SDK下载,开发文档详见下方。

# 2、SDK集成指南

# 2.1 Demo运行步骤

# 2.1.1 创建账号&应用

进入讯飞开放平台主页http://www.xfyun.cn/或者对应的产品页,点击右上角登陆或者注册按钮,完成登陆操作。

进入控制台“我的应用”列表页,点击左上角“创建新应用”,并填写相关应用信息,个人实名认证用户可创建5个应用,企业实名认证用户可创建20个应用,若创建更多应用用户可选择企业实名认证。

# 2.1.2 开通&购买服务

创建完应用之后,在当前应用下,选择“语音转写”,然后在控制台下方点击领取试用时长或者购买正式时长。

# 2.1.3 获取APPid和secret_key以及SDK下载

购买完成后,在“控制台”的对应的应用上,进入语音转写一栏,选择Java sdk下载。若为WEBAPI,可以直接点开技术文档查看接口文档,另外在服务的产品页“语音转写”服务管理中,可以查看密钥,请牢记应用唯一标识appid和转写服务访问秘钥secret_key!

# 2.1.4 demo运行方式

对于Java版SDK,通过如下配置,可以将SDK中的内容导入至工程。下载开发包组件完成后,将开发包组件中的jar文件放置于“<工程路径>/lib”中。进入Eclipse,在选项栏中进入Project -> Properties,在左边选择“Java Build Path”,右边的tab中选择“Libraries”,可见如下界面:移除报错的旧版jar包,点击右边的“Add JARs”,并将刚刚添加到工程里的开发包组件添加,点击“OK”,即完成了开发包组件的添加,之后需配置好config.properties文件,项目无报错即可运行转写服务demo。

# 2.2 项目集成步骤

# 2.2.1 sdk包说明

《SDK目录结构一览》

  • src:
    • 转写demo文件
  • resource:
    • audio/(待转写音频文件)
    • config.properties(转写配置文件)
    • log4j.properties(日志文件)
  • lib:
    • 转写服务相关jar包

# 2.2.2 sdk导入

  1. 在Eclipse中建立你的Java工程。

  2. 将开发工具包中lib目录下的Msc.jar复制到新建工程的lib目录中(如下图所示)。

  3. 在Eclipse中选中工程,通过工具栏Project->Properties->Java Build Path->Libraries->Add JARS或ADD External JARS引入Msc.jar(如下图所示)。

  1. 将SDK.\lib目录下库文件拷贝到工程根目录(如下图所示)。

  1. 上述配置完成之后可直接运行LfasrSDKDemo。

# 2.3 参数与说明

# 2.3.1 JAVA开发接口说明

SDK入口程序类:LfasrClientImp。通过 LfasrClientImp lc = LfasrClientImp.initLfasrClient(); 创建客户端实例。

# 1、SDK接口列表
接口名称 功能简介
initLfasrClient 初始化音频转写客户端
lfasrUpload 音频上传,转写任务创建
lfasrResume 断点续传
lfasrGetProgress 获取转写任务进度状态
lfasrGetResult 获取转写任务结果
# 2、接口参数列表
接口名称 参数列表
initLfasrClient
lfasrUpload String local_file, //本地音频路径及文件名
LfasrType lfasr_type, //本地音频对应类型
HashMap<String, String> params, //用户可配置参数,详见下表
lfasrResume
lfasrGetProgress String task_id // 任务ID
lfasrGetResult String task_id // 任务ID
# 3、可配置参数
参数 类型 必须 说明 示例
lfasr_type string 转写类型,可选值: 0(标准版-已录制音频,格式包括 wav,flac,opus,mp3,m4a), 2(电话专用版,已取消电话专用版套餐),默认0 0
has_participle string 转写结果是否包含分词信息 false或true, 默认false
has_seperate string 转写结果中是否包含发音人分离信息 false或true, 标准版默认:false,电话版默认:true
max_alternatives string 转写结果中最大的候选词个数 默认:0,最大不超过5
speaker_number string 发音人个数,可选值:0-10,0表示盲分
:发音人分离目前还是测试效果达不到商用标准,如测试无法满足您的需求,请慎用该功能。
默认:2(适用通话时两个人对话的场景)
has_sensitive string 是否需要对转写结果进行敏感词检测 false或true, 默认:false
sensitive_type string 敏感词检测类型 需要进行敏感词检测(has_sensitive为true)时必传,0(默认词库)或1(自定义敏感词)
keywords string 自定义的敏感词 敏感词检测类型为1时必传,格式:科大讯飞,语音转写(每个词用英文逗号分割,整个字符串长度不超过256)
language string 语种
cn:中文(默认)
en:英文(英文不支持热词)
cn
pd string 垂直领域个性化参数:
法院: court
教育: edu
金融: finance
医疗: medical
科技: tech
设置示例: params.put("pd", "edu")
pd为非必须设置参数,不设置参数默认为通用
# 4、接口返回值列表
接口名称 返回值
initLfasrClient LfasrClientImp // 转写客户端对象
lfasrUpload Message // 返回消息对象
lfasrResume Void // 抛出异常
lfasrGetProgress Message // 返回消息对象
lfasrGetResult Message // 返回消息对象
# 5、枚举/类型说明

枚举类LfasrType

// 16K标准版\-已录制音频,支持格式wav,flac,opus,mp3,m4a
LfasrType.LFASR_STANDARD_RECORDED_AUDIO

消息类Message

// int类型:-1表示失败、 0表示成功
getOk();
// 字符串类型,错误码
getErr_no();
// 字符串类型,错误码描述
getFailed();
// 成功时携带返回值(上传接口返回任务id字符串,获取进度接口返回进度状态JSON,获取结果接口返回转写结果JSON)
getData(); 

异常类LfasrException

// 获取异常信息JSON,可转化为Message对象
e.getMessage();

状态类ProgressStatus

// 状态ID
getStatus();
// 状态描述
getDesc();

# 2.3.2 JAVA开发接口调用

# 1、initLfasrClient
项目 初始化音频转写客户端
功能 初始化音频转写客户端
声明 LfasrClientImp initLfasrClient() throws LfasrException
参数
返回值 LfasrClientImp 客户端对象
异常 初始化错误信息

# 用法示例

// 初始化LFASRClient实例
LfasrClientImp lc = null;
try {
  lc = LfasrClientImp.initLfasrClient();
} catch (LfasrException e) {
  // 初始化异常,解析异常描述信息
  Message initMsg = JSON.parseObject(e.getMessage(), Message.class);
  System.out.println("ecode=" + initMsg.getErr_no());
  System.out.println("failed=" + initMsg.getFailed());
  return;
}
# 2、lfasrUpload
项目 说明
功能 上传待转写音频文件,并创建转写任务
声明 Message lfasrUpload(String local_file, LfasrType lfasr_type, HashMap<String, String> params) throws LfasrException
参数 local_file: 本地音频路径及音频文件名
lfasr_type: 音频类型,参考:LfasrType枚举类型定义
params:可选参数,参考可配置参数定义
返回值 Message对象
异常 上传音频文件错误信息

# 用法示例

// 获取上传任务ID
String task_id = "";
String local_file = "/audio/lfasr.wav";
HashMap<String, String> params = new HashMap<String, String>();
params.put("has_participle", "true");
try {
  // 上传音频文件
  Message uploadMsg = 
    lc.lfasrUpload(local_file, LfasrType.LFASR_STANDARD_RECORDED_AUDIO, params);

  // 判断返回值
  int ok = uploadMsg.getOk();
  if (ok == 0) {
    // 创建任务成功
    task_id = uploadMsg.getData();
    System.out.println("task_id=" + task_id);
  } else {
    // 创建任务失败-服务端异常
    System.out.println("ecode=" + uploadMsg.getErr_no());
    System.out.println("failed=" + uploadMsg.getFailed());
    return;
  }
} catch (LfasrException e) {
  // 上传异常,解析异常描述信息
  Message uploadMsg = JSON.parseObject(e.getMessage(), Message.class);
  System.out.println("ecode=" + uploadMsg.getErr_no());
  System.out.println("failed=" + uploadMsg.getFailed());
  return;
}
# 3、lfasrResume
项目 说明
功能 恢复lfasrUpload接口上传异常文件,断点续传功能
声明 public void lfasrResume() throws LfasrException
参数
返回值
异常 断点续传错误信息

# 用法示例

try{
	lc.lfasrResume();
}catch(LfasrExceptione){
	//初始化对象异常,打印异常信息
	Message initMsg=JSON.parseObject(e.getMessage(),Message.class);
	System.out.println("ecode="+initMsg.getErr_no());
	System.out.println("failed="+initMsg.getFailed());
	System.out.println("data="+initMsg.getData());
  return;
}
# 4、lfasrGetProgress
项目 说明
功能 根据任务ID,查询任务对应处理状态
声明 public Message lfasrGetProgress(String task_id) throws LfasrException
参数 task_id:lfasrUpload接口返回
返回值 Message对象
异常 获取进度错误信息

# 用法示例

try {
  // 获取处理进度
  Message progressMsg = lc.lfasrGetProgress(task_id);

  // 如果返回状态不等于0,则任务失败
  if (progressMsg.getOk() != 0) {
    System.out.println("task was fail. task_id:" + task_id);
    System.out.println("ecode=" + progressMsg.getErr_no());
    System.out.println("failed=" + progressMsg.getFailed());

    return;
  } else {
    ProgressStatus progressStatus = JSON.parseObject(progressMsg.getData(), ProgressStatus.class);
    if (progressStatus.getStatus() == 9) {
      // 处理完成
      System.out.println("task was completed. task_id:" + task_id);
      break;
    } else {
      // 未处理完成
      System.out.println("task is incomplete. task_id:" + task_id + ", status:" + progressStatus.getDesc());
      continue;
    }
  }
} catch (LfasrException e) {
  // 获取进度异常处理,根据返回信息排查问题后,再次进行获取
  Message progressMsg = JSON.parseObject(e.getMessage(), Message.class);
  System.out.println("ecode=" + progressMsg.getErr_no());
  System.out.println("failed=" + progressMsg.getFailed());
  return;
}
# 5、lfasrGetResult
项目 说明
功能 根据任务ID,获取任务转写结果
声明 public Message lfasrGetResult(String task_id) throws LfasrException
参数 task_id:lfasrUpload接口返回
返回值 Message对象
异常 获取结果错误信息

# 用法示例

// 获取任务结果
try {
  Message resultMsg = lc.lfasrGetResult(task_id);
  // 如果返回状态等于0,则获取任务结果成功
  if (resultMsg.getOk() == 0) {
    // 打印转写结果
    System.out.println(resultMsg.getData());
  } else {
    // 获取任务结果失败
    System.out.println("ecode=" + resultMsg.getErr_no());
    System.out.println("failed=" + resultMsg.getFailed());
  }
} catch (LfasrException e) {
  // 获取结果异常处理,解析异常描述信息
  Message resultMsg = JSON.parseObject(e.getMessage(), Message.class);
  System.out.println("ecode=" + resultMsg.getErr_no());
  System.out.println("failed=" + resultMsg.getFailed());
}

# 2.3.3 附录

# 1、转写结果字段说明
字段名 说明
bg 句子相对于本音频的起始时间,单位为ms
ed 句子相对于本音频的终止时间,单位为ms
onebest 句子内容
speaker 说话人编号,从1开始,未开启说话人分离时speaker都为0
si 句子标识,相同si表示同一句话,从0开始
注:仅开启分词或者多候选时返回
wordsResultList 分词列表
注:仅开启分词或者多候选时返回
alternativeList 多候选列表,按置信度排名
注:仅开启分词或者多候选时返回
wordBg 词相对于本句子的起始帧,其中一帧是10ms
注:仅开启分词或者多候选时返回
wordEd 词相对于本句子的终止帧,其中一帧是10ms
注:仅开启分词或者多候选时返回
wordsName 词内容
注:仅开启分词或者多候选时返回
wc 句子置信度,范围为[0,1]
注:仅开启分词或者多候选时返回
wp 词属性,n代表普通词,r代表人名,d代表数字,m代表量词,s代表顺滑词(语气词),t代表地名&多音字,p代表标点,g代表分段标识
注:仅开启分词或者多候选时返回
# 2、错误码
错误码 错误码描述
0 成功
26000 转写内部通用错误
26100 转写配置文件错误
26101 转写配置文件app_id/secret_key为空
26102 转写配置文件lfasr_host错误
26103 转写配置文件file_piece_size错误
26104 转写配置文件file_piece_size建议设置10M-30M之间
26105 转写配置文件store_path错误,或目录不可读写
26201 转写参数上传文件不能为空或文件不存在
26202 转写参数类型不能为空
26203 转写参数客户端生成签名错误
26301 转写断点续传持久化文件读写错误
26302 转写断点续传文件夹读写错误
26303 转写恢复断点续传流程错误,请见日志
26401 转写上传文件路径错误
26402 转写上传文件类型不支持错误
26403 转写本地文件上传超过限定大小500M
26404 转写上传文件读取错误
26500 HTTP请求失败
26501 转写获取版本号接口错误
26502 转写预处理接口错误
26503 转写上传文件接口错误
26504 转写合并文件接口错误
26505 转写获取进度接口错误
26506 转写获取结果接口错误
26600 转写业务通用错误
26601 非法应用信息
26602 任务ID不存在
26603 接口访问频率受限(默认1秒内不得超过20次)
26604 获取结果次数超过限制,最多100次
26605 任务正在处理中,请稍后重试
26606 空音频,请检查
26610 请求参数错误
26621 预处理文件大小受限(500M)
26622 预处理音频时长受限(5小时)
26623 预处理音频格式受限
26625 预处理服务时长不足。您剩余的可用服务时长不足,请移步产品页http://www.xfyun.cn/services/lfasr 进行购买或者免费领取
26631 音频文件大小受限(500M)
26632 音频时长受限(5小时)
26633 音频服务时长不足。您剩余的可用服务时长不足,请移步产品页http://www.xfyun.cn/services/lfasr 进行购买或者免费领
26634 文件下载失败
26635 文件长度校验失败
26640 文件上传失败
26641 上传分片超过限制
26642 分片合并失败
26643 计算音频时长失败,请检查您的音频是否加密或者损坏
26650 音频格式转换失败,请检查您的音频是否加密或者损坏
26660 计费计量失败
26670 转写结果集解析失败
26680 引擎处理阶段错误
# 3、任务状态码
状态ID 状态描述
0 任务创建成功
1 音频上传完成
2 音频合并完成
3 音频转写中
4 转写结果处理中
5 转写完成
9 转写结果上传完成

# 2.4 实践指南

(1)输入音频的格式&比特率

如若条件允许,请尽量使用pcm,alaw或者ulaw编码的原始wav音频或者无损音频压缩编码(FLAC)来录制以及传输音频。

如果有压缩需求,在原始音频比特率较高(大于16kHz16bit)的情况下,可以采用任意系统支持的格式;而在原始音频比特率较低(小于16kHz16bit)的情况下,建议采用压缩比小于10的opus,使用其他有损编码,如mp3,m4a等会减弱识别准确率。

注,无压缩的pcm音频:比特率(bps)=采样率(kHz)*位数(bit)*声道数;其他类型音频的比特率可由查看其音频属性获得。

(2)背景音和噪声

录音时尽量使用靠近并且指向发声方向的麦克风(例如耳麦);对于已录制音频,建议只摘取人说话声音,避免背景音混叠;对于已经录制好的音频,由于转写引擎在转写之前会对音频进行降噪操作,因此不建议您采用额外的降噪处理。

(3)多人同时发音情况

当对多个发音人同时采集音频时,建议对音频进行预先切分,每次请求识别的音频只含有一位发音人的语音。因为当多人同时发音或多人发音音量有区别时,部分语音有可能会被视为背景噪音而剔除。

(4)有效音频的上传

为了避免您的时长损失,请上传普通播放器可播放的音频。如果上传加密、损坏的音频,或者更改音频后缀,可能会造成转写失败或者输出乱码结果。

(5)音频幅值

音频的帧平均幅度值在5000~20000之间为最佳。不需要刻意录制更高幅度值的音频,否则有可能造成截幅,降低识别率。

(6)音频时长

语音转写最大的特点为具有长时记忆功能,即时间越长的音频,其准确率会越高。建议使用大于1分钟的音频进行转写。

# 2.5 教学视频

教学视频

# 3、常见问题

# 语音转写支不支持并发?

答:默认支持10路并发。

# 语音转写可以试用吗?

答:平台免费赠送的时长为5小时,供开发者测试使用,每个账户限领取1次(应用控制台领取即可),有效期为自生效日起30天。

# 语音转写的返回速度有多快?

答:关于返回时长快慢,需要看当时的转写任务量以及是否是高峰期,如任务积压,排队处理需要时间,时间上会长些。
另外语音转写是SLA协议对象服务之一,我们对付费用户承诺有效任务耗时最大不超过12小时,赔偿标准等详情请参考SLA协议

# 语音转写支持哪些应用平台?

答:语音转写支持Java和webapi接口。

# 语音转写支持哪些音频格式?

答:目前语音转写支持的音频格式为:已录制音频,wav,flac,opus,m4a,mp3,单声道&多声道,支持语种:中文普通话、英语;采样率:8KHz,16KHz;采样精度:8bits,16bits

# 语音转写电话版和标准版什么区别?

答:目前电话版和标准版已经合并为统一的版本,电话版老用户的时长可以继续使用。合并后的版本支持多发音人分离,具体参数调整请参考开发文档。

# 语音转写支持什么语言?

答:支持语种:中文普通话、英语