Opus低延迟音频编解码器API手册中文翻译.docx
- 文档编号:24173936
- 上传时间:2023-05-25
- 格式:DOCX
- 页数:72
- 大小:50.51KB
Opus低延迟音频编解码器API手册中文翻译.docx
《Opus低延迟音频编解码器API手册中文翻译.docx》由会员分享,可在线阅读,更多相关《Opus低延迟音频编解码器API手册中文翻译.docx(72页珍藏版)》请在冰豆网上搜索。
Opus低延迟音频编解码器API手册中文翻译
Opus低延迟音频编解码器API手册中文翻译
Opus:
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
∙OpusCustom
OpusEncoder
本节描述了Opus编码器OpusEncoder的过程和函数
类型定义
typedefstructOpusEncoder
OpusEncoder
Opusencoder状态.
函数
int
opus_encoder_get_size(intchannels)
获得OpusEncoder结构的大小
OpusEncoder*
opus_encoder_create(opus_int32Fs,intchannels,intapplication,int*error)
分配和初始化encoder状态.
int
opus_encoder_init(OpusEncoder*st,opus_int32Fs,intchannels,intapplication)
初始化一个以前分配的编码器状态。
所指向的内存圣必须至少是opus_encoder_get_size()返回的大小.
opus_int32
opus_encode(OpusEncoder*st,constopus_int16*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)
对一个Opus帧进行编码.
opus_int32
opus_encode_float(OpusEncoder*st,constfloat*pcm,intframe_size,unsignedchar*data,opus_int32max_data_bytes)
根据浮点输入对一个Opus帧进行编码.
void
opus_encoder_destroy(OpusEncoder*st)
释放一个根据opus_encoder_create()已分配的OpusEncoder对象。
int
opus_encoder_ctl(OpusEncoder*st,intrequest,...)
向一个Opus编码器执行一个CTL函数.
详细描述
本节描述了用于编码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毫秒)来调用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))中分离。
类型定义文档
typedefstructOpusEncoderOpusEncoder
Opus编码器状态。
这包含了一个Opus编码器的完整状态。
它是位置独立的,并且可以自由复制。
函数文档
opus_int32opus_encode(OpusEncoder*st,
constopus_int16*pcm,
intframe_size,
unsignedchar*data,
opus_int32max_data_bytes
)
对一个Opus帧进行编码。
参数:
[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。
少于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、24000、或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:
这个及所有其他参数应被1个在GenericCTLs或EncoderrelatedCTLs所提供便利的宏来替代
参见:
GenericCTLs
EncoderrelatedCTLs
voidopus_encoder_destroy(OpusEncoder*st)
FreesanOpusEncoderallocatedbyopus_encoder_create().
释放一个根据opus_encoder_create()已分配的OpusEncoder对象。
参数:
[in]stOpusEncoder*:
用于释放的编码器状态。
intopus_encoder_get_size(intchannels)
获得OpusEncoder结构的大小。
参数:
[in]channelsint:
通道数,必须是1或2.
返回:
字节数的大小.
intopus_encoder_init(OpusEncoder*st,
opus_int32Fs,
intchannels,
intapplication
)
初始化一个以前分配的编码器状态。
状态所指向的内存必须至少是opus_encoder_get_size()返回的大小.
在这里,应用程序不要用系统自动分配内存,而要准备用自己的分配器。
参见:
opus_encoder_create(),opus_encoder_get_size()。
为重设一个以前初始化的状态,使用OPUS_RESET_STATECTL.
参数:
[in]stOpusEncoder*:
编码器状态
[in]Fsopus_int32:
输入信号的采样率(Hz),必须是8000、12000、16000、24000、或48000。
[in]channelsint:
输入信号的通道数(1or2)
[in]applicationint:
编码模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
返回值:
成功,OPUS_OK,失败,错误代码。
OpusDecoder
本节描述了Opus解码器OpusDecoder的过程和函数
类型定义
typedefstructOpusDecoder
OpusDecoder
Opus解码器状态.
函数
int
opus_decoder_get_size(intchannels)
获得OpusDecoder结构的大小.
OpusDecoder*
opus_decoder_create(opus_int32Fs,intchannels,int*error)
分配和初始化解码器状态.
int
opus_decoder_init(OpusDecoder*st,opus_int32Fs,intchannels)
初始化以前分配的解码器状态.
int
opus_decode(OpusDecoder*st,constunsignedchar*data,opus_int32len,opus_int16*pcm,intframe_size,intdecode_fec)
解码一个Opus包.
int
opus_decode_float(OpusDecoder*st,constunsignedchar*data,opus_int32len,float*pcm,intframe_size,intdecode_fec)
解码一个浮点输出的Opus包,.
int
opus_decoder_ctl(OpusDecoder*st,intrequest,...)
向一个Opus解码器执行CTL函数。
void
opus_decoder_destroy(OpusDecoder*st)
释放通过opus_decoder_create().分配过的OpusDecoder。
int
opus_packet_parse(constunsignedchar*data,opus_int32len,unsignedchar*out_toc,constunsignedchar*frames[48],shortsize[48],int*payload_offset)
将一个opus包解析成1个或多个帧.
int
opus_packet_get_bandwidth(constunsignedchar*data)
获得一个Opus包的带宽.
int
opus_packet_get_samples_per_frame(constunsignedchar*data,opus_int32Fs)
获得Opus包每帧的样本数。
int
opus_packet_get_nb_channels(constunsignedchar*data)
获得Opus包的通道数。
int
opus_packet_get_nb_frames(constunsignedcharpacket[],opus_int32len)
获得Opus包所有帧的数量.
int
opus_packet_get_nb_samples(constunsignedcharpacket[],opus_int32len,opus_int32Fs)
获得Opus包的样本数。
int
opus_decoder_get_nb_samples(constOpusDecoder*dec,constunsignedcharpacket[],opus_int32len)
获得Opus包的样本数。
详细描述
本节描述了用于解码Opus的过程和方法.
与编码相似,解码进程也是开始于创建一个解码器状态。
用以下方法做到:
interror;
OpusDecoder*dec;
dec=opus_decoder_create(Fs,channels,&error);
在这里:
⏹Fs是采样率,必须是8000,12000,16000,24000,或48000
⏹channels是通道数(1或2)
⏹error将保存出错情况下的错误代码(或成功状态下的OPUS_OK)
⏹返回值是一个新创建的用于解码的解码器状态
当opus_decoder_create()为状态分配内存时,它也可以初始化预分配的内存:
intsize;
interror;
OpusDecoder*dec;
size=opus_decoder_get_size(channels);
dec=malloc(size);
error=opus_decoder_init(dec,Fs,channels);
opus_decoder_get_size()返回解码器状态要求的大小.注意,这段代码的未来版本可能改变大小,所以没有assuptions应该对它做出。
解码器状态在内存中总是连续,复制它只要一个浅拷贝就足够了。
为解码一个帧,opus_decode()或opus_decode_float()必须用压缩音频数据的包来调用:
frame_size=opus_decode(dec,packet,len,decoded,max_size,0);
在这里
⏹packet是包含压缩数据的字节数组
⏹len是包内字节的精确数量
⏹decoded是opus_int16(或由opus_decode_float()定义的浮点型)格式的解码后的音频数据。
⏹max_size是可以放入解码帧的每个通道各样本中帧的最大值
opus_decode()和opus_decode_float()返回从包解码后的每通道样本的数量。
如果这个值是负的,表示有错误发生。
如果包损坏或音频缓冲太小不足以容纳解码后的音频,错误就会发生。
Opus是包含重叠块的有状态的编解码器,其结果是Opus包并不是彼此独立编码。
包必须按正确的次序,连续地进入解码器进行正确的解码。
丢失的包可以用遗失隐藏来替换,遗失隐藏用一个空的指针和0长度的包来调用解码器。
一个单独的编解码器状态在一个时间只能由一个单独的线程来访问,调用者执行任何需要的锁定。
各分开的音频数据流可以用各自分开的解码器状态平行地进行解码,除非API库在编译时用了NONTHREADSAFE_PSEUDOSTACK定义。
类型定义文档
typedefstructOpusDecoderOpusDecoder
Opus解码器状态.
这包含了一个Opus解码器的完整状态。
它是位置独立的,并且可以自由复制。
参见:
opus_decoder_create,opus_decoder_init
函数文档
intopus_decode(OpusDecoder*st,
constunsignedchar*data,
opus_int32len,
opus_int16*pcm,
intframe_size,
intdecode_fec
)
对一个Opus包进行解码。
参数:
[in]stOpusDecoder*:
解码器状态
[in]datachar*:
输入负载.对包丢失使用一个
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Opus 延迟 音频 编解码器 API 手册 中文翻译
![提示](https://static.bdocx.com/images/bang_tan.gif)