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

H:\精品资料\建筑精品网原稿ok（删除公文）\建筑精品网5未上传百度
Opus: IETF低延迟音频编解码器:API和操作手册
Opus简介
Opus编解码器是专门设计用于互联网的交互式语音和音频传输。它是由IETF的编解码器工作组设计的, 合并了Skype的SILK和Xiph. Org的CELT技术。
Opus编解码器的设计目的是处理广泛的交互式音频应用程序,包括IP语音,视频,游戏内聊天,甚至远程现场音乐表演。它能够适用于从低码率窄带语音到非常高质量的立体声音乐。它的主要特点是:
· 采样率从8至48 kHz
· 比特率从6kb/s到510kb/s
· 对固定码率(CBR)和可变码率(VBR)都能支持
· 从窄带到宽带的音频带宽
· 支持语音和音乐
· 支持单声道和立体声
· 支持多通道(最多255通道)
· 帧规格从2.5毫秒到60毫秒
· 良好的损失鲁棒性和包丢失隐藏性(PLC)( 注: 应是指丢包也不容易被发现)
· 浮点和定点执行
文档包括:
· Opus Encoder
· Opus Decoder
· Repacketizer
· Opus Multistream API
· Opus library information functions
· Opus Custom

Opus Encoder
本节描述了Opus编码器OpusEncoder的过程和函数
类型定义
typedef struct OpusEncoder 
OpusEncoder

Opus encoder 状态.
函数

int 
opus_encoder_get_size (int channels)

获得 OpusEncoder结构的大小
OpusEncoder * 
opus_encoder_create (opus_int32 Fs, int channels, int application, int *error)

分配和初始化 encoder状态.
int 
opus_encoder_init (OpusEncoder *st, opus_int32 Fs, int channels, int application)

初始化一个以前分配的编码器状态。所指向的内存圣必须至少是opus_encoder_get_size()返回的大小.
opus_int32 
opus_encode (OpusEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

对一个 Opus帧进行编码.
opus_int32 
opus_encode_float (OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

根据浮点输入对一个 Opus帧进行编码.
void 
opus_encoder_destroy (OpusEncoder *st)

释放一个根据opus_encoder_create()已分配的OpusEncoder 对象。
int 
opus_encoder_ctl (OpusEncoder *st, int request,...)

向一个Opus编码器执行一个 CTL 函数.

详细描述
本节描述了用于编码Opus的过程和函数。
既然Opus是一个有状态的编解码器, 编码过程始于创立一个编码器状态, 用以下方法做到:
int error;
OpusEncoder *enc;
enc = opus_encoder_create(Fs, channels, application, &error);
从这一点上, enc能够用于编码音频流。一个编码器状态在同一时间不得用于多于一个音频流。同样,编码器状态不能对于每帧重新初始化。
当opus_encoder_create()为状态分配内存时, 它也能够初始化预分配的内存:
int size;
int error;
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, or OPUS_SIGNAL_MUSIC。
看Encoder related CTLs 和 Generic CTLs能够获得可设置和查询的参数详细清单。在一个音频流处理过程中, 大多数参数能够设置或修改。
为了对一个帧进行编码, 必须正确地用音频数据的帧(2.5, 5, 10, 20, 40 或60 毫秒)来调用opus_encode() 或opus_encode_float()函数。
len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);
在这里:
l audio_frame( 音频帧) 是opus_int16(或用于opus_encode_float()的浮点)格式的音频数据
l frame_size( 帧大小) 是样本中帧的最大数(每个通道)
l packet( 包) 是写成压缩数据的字节数组,
l max_packet是能够写入包的字节数的最大值推荐(4000字节)。不要使用max_packet控制VBR的目标比特率,而应该用OPUS_SET_BITRATE CTL。
opus_encode() 和opus_encode_float()返回实际写入包的字节数。返回值能够是负数,这表明一个错误已经发生。如果返回值是1个字节,那么包不需要传播(DTX)。
一旦一个编码器状态已不再需要, 能够用以下方式解构:
opus_encoder_destroy(enc);
如果编码器是用opus_encoder_init() 创立的, 而不是使用opus_encoder_create()函数, 那么不需要采取行动, 要求从潜在的释放为它手动分配的内存(上述例子是调用 free(enc))中分离。
类型定义文档
typedef struct OpusEncoder OpusEncoder
Opus编码器状态。
这包含了一个Opus编码器的完整状态。它是位置独立的, 而且能够自由复制。
函数文档
opus_int32 opus_encode ( OpusEncoder * st,
const opus_int16 * pcm,
int frame_size,
unsigned char * data,
opus_int32 max_data_bytes
)
对一个Opus帧进行编码。
参数:
[in] st OpusEncoder*:编码器状态
[in] pcm opus_int16*: 输入信号(如果是2 通道有交叉). 长度是 frame_size*channels*sizeof(opus_int16)
[in] frame_size int:输入信号的每通道样本数. 这必须是编码器采样率的Opus帧大小。比如, 48 kHz 下允许值有120, 240, 480, 960, 1920, 和 2880。少于10毫秒的采样( 48 kHz 有480个样本) , 将阻止编码器使用LPC或混合模式。
[out] data unsigned char*: 输出负载。必须包含至少max_data_bytes 的容量。
[in] max_data_bytes opus_int32: 为输出负载所分配的内存大小。能够用于限制固定比特率的最大上限, 但不能用作唯一的比特率限制, 能够用OPUS_SET_BITRATE来控制比特率。
返回值: 成功, 是被编码包的长度( 字节数) , 失败, 一个负的错误代码

opus_int32 opus_encode_float ( OpusEncoder * st,
const float * pcm,
int frame_size,
unsigned char * data,
opus_int32 max_data_bytes
)
根据浮点输入对一个 Opus帧进行编码.
参数:
[in] st OpusEncoder*:编码器状态
[in] pcm float*:浮点格式的输入(如果是2 通道有交叉), 正常范围在+/-1.0之间. 超过该范围的采样也是支持的, 但它将被解码器用整型API截取, 而且只能在知道远端支持扩展的动态范围的情况下使用。长度是 frame_size*channels*sizeof(float)
[in] frame_size int: 输入信号的每通道样本数. 这必须是编码器采样率的Opus帧大小。比如, 48 kHz 下允许值有120, 240, 480, 960, 1920, 和 2880。少于10毫秒的采样( 48 kHz 有480个样本) , 将阻止编码器使用LPC或混合模式。
[out] data unsigned char*:输出负载。必须包含至少max_data_bytes 的容量。
[in] max_data_bytes opus_int32: 为输出负载所分配的内存大小。能够用于限制固定比特率的最大上限, 但不能用作唯一的比特率限制, 能够用OPUS_SET_BITRATE来控制比特率。.
返回值:
成功, 是被编码包的长度( 字节数) , 失败, 一个负的错误代码。
OpusEncoder* opus_encoder_create ( opus_int32 Fs,
int channels,
int application,
int * error
)
分配和初始化一个编码器状态。
包括三种编码模式:
OPUS_APPLICATION_VOIP: 在给定比特率条件下为声音信号提供最高质量, 它经过高通滤波和强调共振峰和谐波增强了输入信号。它包括带内前向错误检查以预防包丢失。典型的VOIP应用程序使用这种模式。由于进行了增强, 即使是高比特率的情况下, 输出的声音与输入相比, 听起来可能不一样。
OPUS_APPLICATION_AUDIO: 对大多数非语音信号, 如音乐, 在给定比特率条件下提供了最高的质量。使用这种模式的场合包括音乐、 混音(音乐/声音),广播,和需要不到15 毫秒的信号延迟的其它应用。
OPUS_APPLICATION_RESTRICTED_LOWDELAY: 配置低延迟模式将为减少延迟禁用语音优化模式。这种模式只能在刚初始化或刚重设编码器的情况下使用, 因为在这些情况下编解码器的延迟被修改了。
( 当心! ) 当调用者知道语音优化模式不再需要时, 配置低延迟模式是有用的。
参数:
[in] Fs opus_int32: 输入信号的采样率 (Hz), 必须是8000、 1 、 16000、 24000、 或48000。
[in] channels int:输入信号的通道数 (1 or 2) 。
[in] application int:编码模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
[out] error int*: 错误代码
注意: 无论选择什么样的采样率和通道数, 如果选择的比特率太低, Opus编码器能够切换到一个较低的音频带宽或通道数。这也意味着总是使用48 kHz立体声输入和让编码器优化编码是安全的。

int opus_encoder_ctl ( OpusEncoder * st,
int request,
...
)
向一个Opus编码器执行一个 CTL 函数.
一般其请求和后续的参数是由一个提供便利的宏来产生的。
参数:
st OpusEncoder*: 编码器状态
request int: 这个及所有其它参数应被1个在Generic CTLs 或Encoder related CTLs所提供便利的宏来替代
参见:
Generic CTLs
Encoder related CTLs

void opus_encoder_destroy ( OpusEncoder * st )
Frees an OpusEncoder allocated by opus_encoder_create().
释放一个根据opus_encoder_create()已分配的OpusEncoder 对象。
参数:
[in] st OpusEncoder*: 用于释放的编码器状态。

int opus_encoder_get_size ( int channels )
获得 OpusEncoder结构的大小。
参数:
[in] channels int: 通道数, 必须是1或2.

返回:
字节数的大小.

int opus_encoder_init ( OpusEncoder * st,
opus_int32 Fs,
int channels,
int application
)
初始化一个以前分配的编码器状态。状态所指向的内存必须至少是opus_encoder_get_size()返回的大小.
在这里, 应用程序不要用系统自动分配内存, 而要准备用自己的分配器。
参见:
opus_encoder_create(),opus_encoder_get_size()。为重设一个以前初始化的状态, 使用OPUS_RESET_STATE CTL.
参数:
[in] st OpusEncoder*: 编码器状态
[in] Fs opus_int32: 输入信号的采样率 (Hz), 必须是8000、 1 、 16000、 24000、 或48000。
[in] channels int: 输入信号的通道数 (1 or 2)
[in] application int: 编码模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
返回值:
成功, OPUS_OK , 失败, 错误代码。

Opus Decoder
本节描述了Opus解码器OpusDecoder的过程和函数
类型定义
typedef struct OpusDecoder 
OpusDecoder

Opus 解码器状态.
函数
int 
opus_decoder_get_size (int channels)

获得OpusDecoder 结构的大小.
OpusDecoder * 
opus_decoder_create (opus_int32 Fs, int channels, int *error)

分配和初始化解码器状态.
int 
opus_decoder_init (OpusDecoder *st, opus_int32 Fs, int channels)

初始化以前分配的解码器状态.
int 
opus_decode (OpusDecoder *st, const unsigned char *data, opus_int32 len, opus_int16 *pcm, int frame_size, int decode_fec)

解码一个 Opus 包.
int 
opus_decode_float (OpusDecoder *st, const unsigned char *data, opus_int32 len, float *pcm, int frame_size, int decode_fec)

解码一个浮点输出的Opus 包, .
int 
opus_decoder_ctl (OpusDecoder *st, int request,...)

向一个Opus解码器执行CTL 函数。
void 
opus_decoder_destroy (OpusDecoder *st)

释放经过opus_decoder_create().分配过的OpusDecoder。
int 
opus_packet_parse (const unsigned char *data, opus_int32 len, unsigned char *out_toc, const unsigned char *frames[48], short size[48], int *payload_offset)

将一个 opus 包解析成1个或多个帧.
int 
opus_packet_get_bandwidth (const unsigned char *data)

获得一个 Opus包的带宽.
int 
opus_packet_get_samples_per_frame (const unsigned char *data, opus_int32 Fs)

获得Opus 包每帧的样本数。
int 
opus_packet_get_nb_channels (const unsigned char *data)

获得Opus 包的通道数。
int 
opus_packet_get_nb_frames (const unsigned char packet[], opus_int32 len)

获得Opus 包所有帧的数量.
int 
opus_packet_get_nb_samples (const unsigned char packet[], opus_int32 len, opus_int32 Fs)

获得Opus 包的样本数。
int 
opus_decoder_get_nb_samples (const OpusDecoder *dec, const unsigned char packet[], opus_int32 len)

获得Opus 包的样本数。

详细描述
本节描述了用于解码Opus的过程和方法.

与编码相似, 解码进程也是开始于创立一个解码器状态。用以下方法做到:
int error;
OpusDecoder *dec;
dec = opus_decoder_create(Fs, channels, &error);
在这里:
n Fs 是采样率, 必须是8000, 1 , 16000, 24000, 或 48000
n channels 是通道数 (1 或 2)
n error 将保存出错情况下的错误代码(或成功状态下的 OPUS_OK )
n 返回值是一个新创立的用于解码的解码器状态

当 opus_decoder_create() 为状态分配内存时, 它也能够初始化预分配的内存:
int size;
int error;
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);
在这里
n packet 是包含压缩数据的字节数组
n len 是包内字节的精确数量
n decoded 是opus_int16 (或由 opus_decode_float()定义的浮点型)格式的解码后的音频数据。
n max_size是能够放入解码帧的每个通道各样本中帧的最大值
opus_decode() 和 opus_decode_float() 返回从包解码后的每通道样本的数量。如果这个值是负的, 表示有错误发生。如果包损坏或音频缓冲太小不足以容纳解码后的音频, 错误就会发生。

Opus是包含重叠块的有状态的编解码器, 其结果是Opus 包并不是彼此独立编码。包必须按正确的次序, 连续地进入解码器进行正确的解码。丢失的包能够用遗失隐藏来替换, 遗失隐藏用一个空的指针和0长度的包来调用解码器。
一个单独的编解码器状态在一个时间只能由一个单独的线程来访问, 调用者执行任何需要的锁定。各分开的音频数据流能够用各自分开的解码器状态平行地进行解码, 除非API库在编译时用了NONTHREADSAFE_PSEUDOSTACK定义。
类型定义文档
typedef struct OpusDecoder OpusDecoder

Opus 解码器状态.
这包含了一个Opus解码器的完整状态。它是位置独立的, 而且能够自由复制。
参见:
opus_decoder_create,opus_decoder_init
函数文档
int opus_decode ( OpusDecoder * st,
const unsigned char * data,
opus_int32 len,
opus_int16 * pcm,
int frame_size,
int decode_fec
)
对一个Opus包进行解码。
参数:
[in] st OpusDecoder*: 解码器状态
[in] data char*:输入负载.对包丢失使用一个空指针来表示。
[in] len opus_int32:在输入负载中的字节数
[out] pcm opus_int16*: 输出信号( 如果是2通道有交叉) 。长度等于frame_size*channels*sizeof(opus_int16)
[in] frame_size : 在PCM可用空间中每通道的样本数。如果小于最大包的时长( 120毫秒, 4848kHz5760个) , 这个函数将不能解码一些包。如果是PLC (data==NULL) 或 FEC (decode_fec=1)的情况, 那么frame_size必须正好是丢失音频的时长, 否则解码器无法在解码下一个包时进入优化状态。对于PLC 和 FEC 的情况, frame_size必须是2.5毫秒的倍数。
[in] decode_fec int: 对于请求任何带内前向错误纠正数据进行解码的状态标志 (0 or 1) 。如果没有这样的数据可用, 帧在解码时被认为已经丢失。
返回:
解码样本的数量, 或错误代码。

int opus_decode_float ( OpusDecoder * st,
const unsigned char * data,
opus_int32 len,
float * pcm,
int frame_size,
int decode_fec
)
用浮点输出格式解码一个Opus包。
参数:
[in] st OpusDecoder*: 解码器状态
[in] data char*:输入负载.对包丢失使用一个空指针来表示。
[in] len opus_int32: 在输入负载中的字节数
[out] pcm float*:输出信号( 如果是2通道有交叉) 。长度等于frame_size*channels*sizeof(float)
[in] frame_size : 在PCM可用空间中每通道的样本数。如果小于最大包的时长( 120毫秒, 4848kHz5760个) , 这个函数将不能解码一些包。如果是PLC (data==NULL) 或 FEC (decode_fec=1)的情况, 那么frame_size必须正好是丢失音频的时长, 否则解码器无法在解码下一个包时进入优化状态。对于PLC 和 FEC 的情况, frame_size必须是2.5毫秒的倍数。
[in] decode_fec int: 对于请求任何带内前向错误纠正数据进行解码的状态标志 (0 or 1) 。如果没有这样的数据可用, 帧在解码时被认为已经丢失。
返回:
解码样本的数量, 或错误代码。

OpusDecoder* opus_decoder_create ( opus_int32 Fs,
int channels,
int * error
)
分配和初始化解码器状态.
参数:
[in] Fs opus_int32: 解码的采样率 (Hz). 必须是 8000, 1 , 16000, 24000, 或 48000.
[in] channels int: 用于解码的通道数(1 or 2)
[out] error int*:成功时是 OPUS_OK Success或错误代码
Opus在内部用48000 Hz来存储数据, 因此对于FS来说48000 Hz是缺省值。然而, 解码器在8, 12, 16, 和 24 kHz下也能够有效解码到缓冲, 因此, 由于某些原因调用者不能在全采样率下使用数据, 或知道被压缩的数据不能在全频率范围内使用, 能够请求用更小的频率解码。同样的, 解码器能够根据调用者的请求, 填充单声道或交叉立体声的PCM缓冲区。

int opus_decoder_ctl ( OpusDecoder * st,
int request,
...
)
向一个Opus解码器执行一个 CTL 函数.
一般其请求和后续的参数是由一个提供便利的宏来产生的。
参数:
n st OpusDecoder*: 解码器状态.
n request : 这个及所有其它剩余参数应被1个在Generic CTLs 或Encoder related CTLs所提供便利的宏来替代
参见:
Generic CTLs
Decoder related CTLs

void opus_decoder_destroy ( OpusDecoder * st )
释放一个根据opus_decoder_create()已分配的OpusDecoder 对象.
参数:
[in] st OpusDecoder*:用于释放的解码器状态。

int opus_decoder_get_nb_samples ( const OpusDecoder * dec,
const unsigned char packet[],
opus_int32 len
)
获得一个Opus包的样本数
参数:
[in] dec OpusDecoder*: 解码器状态
[in] packet char*: Opus包
[in] len opus_int32: 包的长度
返回:
样本的数量
返回值:
OPUS_INVALID_PACKET: 经过的被压缩数据已损坏或其格式不被支持。

int opus_decoder_get_size ( int channels )
获得 OpusDecoder结构的大小。
参数:
[in] channels int: 通道数, 必须是1或2.

返回:
字节数的大小.

int opus_decoder_init ( OpusDecoder * st,
opus_int32 Fs,
int channels
)
初始化一个以前分配过的解码器状态.
状态必须至少是opus_decoder_get_size()返回的大小.
在这里, 应用程序不要用系统自动分配内存, 而要准备用自己的分配器。
参见:
opus_decoder_create,opus_decoder_get_size,为重设一个以前初始化的状态, 使用OPUS_RESET_STATE CTL.
参数:
[in] st OpusDecoder*: 解码器状态.
[in] Fs opus_int32: 准备解码的采样率 (Hz). 必须是8000、 1 、 16000、 24000、 或48000.
[in] channels int: 解码的通道数 (1 or 2)
返回值:
成功, OPUS_OK , 失败, 错误代码。

int opus_packet_get_bandwidth ( const unsigned char * data ) 获得一个Opus包的带宽。
参数:
[in] data char*: Opus 包

返回值:
n OPUS_BANDWIDTH_NARROWBAND 窄带 (4kHz bandpass)
n OPUS_BANDWIDTH_MEDIUMBAND 中等带宽 (6kHz bandpass)
n OPUS_BANDWIDTH_WIDEBAND 宽带 (8kHz bandpass)
n OPUS_BANDWIDTH_SUPERWIDEBAND 高宽带 (12kHz bandpass)
n OPUS_BANDWIDTH_FULLBAND 全宽带 (20kHz bandpass)
n OPUS_INVALID_PACKET 经过的被压缩数据已损坏或其格式不被支持

int opus_packet_get_nb_channels ( const unsigned char * data )
获得Opus 包的通道数。
参数:
[in] data char*: Opus 包
返回:
通道数量
返回值:
OPUS_INVALID_PACKET 经过的被压缩数据已损坏或其格式不被支持

int opus_packet_get_nb_frames ( const unsigned char packet[],
opus_int32 len
)
获得Opus 包所有帧的数量.
参数:
[in] packet char*: Opus 包
[in] len opus_int32:包的长度
返回:
帧的数量
返回值:
OPUS_INVALID_PACKET 经过的被压缩数据已损坏或其格式不被支持

int opus_packet_get_nb_samples ( const unsigned char packet[],
opus_int32 len,
opus_int32 Fs
)
获得Opus 包的样本数。
参数:
[in] packet char*: Opus 包
[in] len opus_int32: 包的长度
[in] Fs opus_int32: 采样率( Hz) . 必须是400的倍数, 否则结果不准确。
返回:
样本的数量
返回值:
OPUS_INVALID_PACKET 经过的被压缩数据已损坏或其格式不被支持

int opus_packet_get_samples_per_frame ( const unsigned char * data,
opus_int32 Fs
)
获得Opus 包每帧的样本数。
参数:
[in] data char*: Opus 包. 必须包含至少一个字节的数据。
[in] Fs opus_int32: 采样率( Hz) .必须是400的倍数, 否则结果不准确。

返回:
每帧样本的数量.

int opus_packet_parse ( const unsigned char * data,
opus_int32 len,
unsigned char * out_toc,
const unsigned char * frames[48],
short size[48],
int * payload_offset
)
将一个 opus 包解析成1个或多个帧.
Opus_decode在内部执行这个操作, 因此大多数应用程序不需要用到这个函数。这个函数不复制各帧, 返回的指针是输入包内部的指针。
参数:
[in] data char*:要进行解析的 Opus包
[in] len opus_int32: 数据的大小
[out] out_toc cha