Opus低延迟音频编解码器API手册中文翻译

1Opus：IETF低延迟音频编解码器:API和操作手册Opus简介Opus编解码器是专门设计用于互联网的交互式语音和音频传输。它是由IETF的编解码器工作组设计的，合并了Skype的SILK和Xiph.Org的CELT技术。Opus编解码器的设计目的是处理广泛的交互式音频应用程序,包括IP语音,视频,游戏内聊天,甚至远程现场音乐表演。它可以适用于从低码率窄带语音到非常高质量的立体声音乐。它的主要特点是:采样率从8至48kHz比特率从6kb/s到510kb/s对固定码率(CBR)和可变码率(VBR)都能支持从窄带到宽带的音频带宽支持语音和音乐支持单声道和立体声支持多通道(最多255通道)帧规格从2.5毫秒到60毫秒良好的损失鲁棒性和包丢失隐藏性(PLC)（注：应是指丢包也不容易被发现）浮点和定点执行文档包括:OpusEncoderOpusDecoderRepacketizerOpusMultistreamAPIOpuslibraryinformationfunctionsOpusCustom2OpusEncoder本节描述了Opus编码器OpusEncoder的过程和函数类型定义typedefstructOpusEncoderOpusEncoderOpusencoder状态.函数intopus_encoder_get_size(intchannels)获得OpusEncoder结构的大小OpusEncoder*opus_encoder_create(opus_int32Fs,intchannels,intapplication,int*error)分配和初始化encoder状态.intopus_encoder_init(OpusEncoder*st,opus_int32Fs,intchannels,intapplication)初始化一个以前分配的编码器状态。所指向的内存圣必须至少是opus_encoder_get_size()返回的大小.opus_int32opus_encode(OpusEncoder*st,constopus_int16*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)对一个Opus帧进行编码.opus_int32opus_encode_float(OpusEncoder*st,constfloat*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)根据浮点输入对一个Opus帧进行编码.voidopus_encoder_destroy(OpusEncoder*st)释放一个根据opus_encoder_create()已分配的OpusEncoder对象。intopus_encoder_ctl(OpusEncoder*st,intrequest,...)向一个Opus编码器执行一个CTL函数.3详细描述本节描述了用于编码Opus的过程和函数。既然Opus是一个有状态的编解码器，编码过程始于创建一个编码器状态，用以下方法做到：interror;OpusEncoder*enc;enc=opus_encoder_create(Fs,channels,application,&error);从这一点上,enc可以用于编码音频流。一个编码器状态在同一时间不得用于多于一个音频流。同样,编码器状态不能对于每帧重新初始化。当opus_encoder_create()为状态分配内存时，它也可以初始化预分配的内存：intsize;interror;OpusEncoder*enc;size=opus_encoder_get_size(channels);enc=malloc(size);error=opus_encoder_init(enc,Fs,channels,application);opus_encoder_get_size()返回编码器状态要求的大小。注意,这段代码的未来版本可能改变大小,所以没有assuptions应该对它做出。编码器状态在内存中总是连续,复制它只要一个浅拷贝就足够了。使用opus_encoder_ctl()接口可以改变一些编码器的参数设置。所有这些参数都已有缺省值，所以只在必要的情况下改变它们。最常见的参数设置修改是：opus_encoder_ctl(enc,OPUS_SET_BITRATE(bitrate));opus_encoder_ctl(enc,OPUS_SET_COMPLEXITY(complexity));opus_encoder_ctl(enc,OPUS_SET_SIGNAL(signal_type));在这里：bitrate（比特率）的单位是比特/秒(b/s)complexity（复杂性）是一个值从1到10,1最低，10最高，值越大越复杂signal_type（信号的类型）包括OPUS_AUTO(缺省),OPUS_SIGNAL_VOICE,orOPUS_SIGNAL_MUSIC。看EncoderrelatedCTLs和GenericCTLs可以获得可设置和查询的参数详细清单。在一个音频流处理过程中，大多数参数可以设置或修改。为了对一个帧进行编码，必须正确地用音频数据的帧(2.5,5,10,20,40或60毫4秒)来调用opus_encode()或opus_encode_float()函数。len=opus_encode(enc,audio_frame,frame_size,packet,max_packet);在这里：audio_frame（音频帧）是opus_int16(或用于opus_encode_float()的浮点)格式的音频数据frame_size（帧大小）是样本中帧的最大数(每个通道)packet（包）是写成压缩数据的字节数组,max_packet是可以写入包的字节数的最大值推荐(4000字节)。不要使用max_packet控制VBR的目标比特率,而应该用OPUS_SET_BITRATECTL。opus_encode()和opus_encode_float()返回实际写入包的字节数。返回值可以是负数,这表明一个错误已经发生。如果返回值是1个字节,那么包不需要传播(DTX)。一旦一个编码器状态已不再需要，可以用以下方式解构：opus_encoder_destroy(enc);如果编码器是用opus_encoder_init()创建的，而不是使用opus_encoder_create()函数，那么不需要采取行动，要求从潜在的释放为它手动分配的内存(上述例子是调用free(enc))中分离。类型定义文档typedefstructOpusEncoderOpusEncoderOpus编码器状态。这包含了一个Opus编码器的完整状态。它是位置独立的，并且可以自由复制。函数文档opus_int32opus_encode(OpusEncoder*st,constopus_int16*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)对一个Opus帧进行编码。5参数：[in]stOpusEncoder*:编码器状态[in]pcmopus_int16*:输入信号(如果是2通道有交叉).长度是frame_size*channels*sizeof(opus_int16)[in]frame_sizeint:输入信号的每通道样本数.这必须是编码器采样率的Opus帧大小。比如，48kHz下允许值有120,240,480,960,1920,和2880。少于10毫秒的采样（48kHz有480个样本），将阻止编码器使用LPC或混合模式。[out]dataunsignedchar*:输出负载。必须包含至少max_data_bytes的容量。[in]max_data_bytesopus_int32:为输出负载所分配的内存大小。可以用于限制固定比特率的最大上限，但不能用作唯一的比特率限制，可以用OPUS_SET_BITRATE来控制比特率。返回值：成功，是被编码包的长度（字节数），失败，一个负的错误代码opus_int32opus_encode_float(OpusEncoder*st,constfloat*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)根据浮点输入对一个Opus帧进行编码.参数：[in]stOpusEncoder*:编码器状态[in]pcmfloat*:浮点格式的输入(如果是2通道有交叉)，正常范围在+/-1.0之间.超过该范围的采样也是支持的，但它将被解码器用整型API截取，并且只能在知道远端支持扩展的动态范围的情况下使用。长度是frame_size*channels*sizeof(float)[in]frame_sizeint:输入信号的每通道样本数.这必须是编码器采样率的Opus帧大小。比如，48kHz下允许值有120,240,480,960,1920,和2880。6少于10毫秒的采样（48kHz有480个样本），将阻止编码器使用LPC或混合模式。[out]dataunsignedchar*:输出负载。必须包含至少max_data_bytes的容量。[in]max_data_bytesopus_int32:为输出负载所分配的内存大小。可以用于限制固定比特率的最大上限，但不能用作唯一的比特率限制，可以用OPUS_SET_BITRATE来控制比特率。.返回值：成功，是被编码包的长度（字节数），失败，一个负的错误代码。OpusEncoder*opus_encoder_create(opus_int32Fs,intchannels,intapplication,int*error)分配和初始化一个编码器状态。包括三种编码模式：OPUS_APPLICATION_VOIP：在给定比特率条件下为声音信号提供最高质量，它通过高通滤波和强调共振峰和谐波增强了输入信号。它包括带内前向错误检查以预防包丢失。典型的VOIP应用程序使用这种模式。由于进行了增强，即使是高比特率的情况下，输出的声音与输入相比，听起来可能不一样。OPUS_APPLICATION_AUDIO：对大多数非语音信号，如音乐，在给定比特率条件下提供了最高的质量。使用这种模式的场合包括音乐、混音(音乐/声音),广播,和需要不到15毫秒的信号延迟的其他应用。OPUS_APPLICATION_RESTRICTED_LOWDELAY：配置低延迟模式将为减少延迟禁用语音优化模式。这种模式只能在刚初始化或刚重设编码器的情况下使用，因为在这些情况下编解码器的延迟被修改了。（当心！）当调用者知道语音优化模式不再需要时，配置低延迟模式是有用的。参数：[in]Fsopus_int32:输入信号的采样率(Hz)，必须是8000、12000、16000、724000、或48000。[in]channelsint:输入信号的通道数(1or2)。[in]applicationint:编码模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)[out]errorint*:错误代码注意：无论选择什么样的采样率和通道数,如果选择的比特率太低，Opus编码器可以切换到一个较低的音频带宽或通道数。这也意味着总是使用48kHz立体声输入和让编码器优化编码是安全的。intopus_encoder_ctl(OpusEncoder*st,intrequest,...)向一个Opus编码器执行一个CTL函数.一般其请求和后续的参数是由一个提供便利的宏来产生的。参数:stOpusEncoder*:编码器状态requestint：