Opus低延遲音頻編解碼器API手冊(cè)中文翻譯.doc

《Opus低延遲音頻編解碼器API手冊(cè)中文翻譯.doc》由會(huì)員分享，可在線閱讀，更多相關(guān)《Opus低延遲音頻編解碼器API手冊(cè)中文翻譯.doc（69頁珍藏版）》請(qǐng)?jiān)谘b配圖網(wǎng)上搜索。

Opus：IETF低延遲音頻編解碼器:API和操作手冊(cè) Opus簡(jiǎn)介 Opus編解碼器是專門設(shè)計(jì)用于互聯(lián)網(wǎng)的交互式語音和音頻傳輸。它是由IETF的編解碼器工作組設(shè)計(jì)的，合并了Skype的SILK和Xiph. Org的CELT技術(shù)。 Opus編解碼器的設(shè)計(jì)目的是處理廣泛的交互式音頻應(yīng)用程序,包括IP語音,視頻,游戲內(nèi)聊天,甚至遠(yuǎn)程現(xiàn)場(chǎng)音樂表演。它可以適用于從低碼率窄帶語音到非常高質(zhì)量的立體聲音樂。它的主要特點(diǎn)是: · 采樣率從8至48 kHz · 比特率從6kb/s到510kb/s · 對(duì)固定碼率(CBR)和可變碼率(VBR)都能支持 · 從窄帶到寬帶的音頻帶寬 · 支持語音和音樂 · 支持單聲道和立體聲 · 支持多通道(最多255通道) · 幀規(guī)格從2.5毫秒到60毫秒 · 良好的損失魯棒性和包丟失隱藏性(PLC)（注：應(yīng)是指丟包也不容易被發(fā)現(xiàn)） · 浮點(diǎn)和定點(diǎn)執(zhí)行 文檔包括: · Opus Encoder · Opus Decoder · Repacketizer · Opus Multistream API · Opus library information functions · Opus Custom  Opus Encoder 本節(jié)描述了Opus編碼器OpusEncoder的過程和函數(shù) 類型定義 typedef struct OpusEncoder? OpusEncoder ? Opus encoder 狀態(tài). 函數(shù) int? opus_encoder_get_size (int channels) ? 獲得 OpusEncoder結(jié)構(gòu)的大小 OpusEncoder *? opus_encoder_create (opus_int32 Fs, int channels, int application, int *error) ? 分配和初始化 encoder狀態(tài). int? opus_encoder_init (OpusEncoder *st, opus_int32 Fs, int channels, int application) ? 初始化一個(gè)以前分配的編碼器狀態(tài)。所指向的內(nèi)存圣必須至少是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) ? 對(duì)一個(gè) Opus幀進(jìn)行編碼. opus_int32? opus_encode_float (OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes) ? 根據(jù)浮點(diǎn)輸入對(duì)一個(gè) Opus幀進(jìn)行編碼. void? opus_encoder_destroy (OpusEncoder *st) ? 釋放一個(gè)根據(jù)opus_encoder_create()已分配的OpusEncoder 對(duì)象。 int? opus_encoder_ctl (OpusEncoder *st, int request,...) ? 向一個(gè)Opus編碼器執(zhí)行一個(gè) CTL 函數(shù). 詳細(xì)描述 本節(jié)描述了用于編碼Opus的過程和函數(shù)。 既然Opus是一個(gè)有狀態(tài)的編解碼器，編碼過程始于創(chuàng)建一個(gè)編碼器狀態(tài)，用以下方法做到： int error; OpusEncoder *enc; enc = opus_encoder_create(Fs, channels, application, &error); 從這一點(diǎn)上, enc可以用于編碼音頻流。一個(gè)編碼器狀態(tài)在同一時(shí)間不得用于多于一個(gè)音頻流。同樣,編碼器狀態(tài)不能對(duì)于每幀重新初始化。 當(dāng)opus_encoder_create()為狀態(tài)分配內(nèi)存時(shí)，它也可以初始化預(yù)分配的內(nèi)存： 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()返回編碼器狀態(tài)要求的大小。注意,這段代碼的未來版本可能改變大小,所以沒有assuptions應(yīng)該對(duì)它做出。 編碼器狀態(tài)在內(nèi)存中總是連續(xù),復(fù)制它只要一個(gè)淺拷貝就足夠了。 使用opus_encoder_ctl()接口可以改變一些編碼器的參數(shù)設(shè)置。所有這些參數(shù)都已有缺省值，所以只在必要的情況下改變它們。最常見的參數(shù)設(shè)置修改是： 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（復(fù)雜性）是一個(gè)值從1到10,1最低，10最高，值越大越復(fù)雜 · signal_type（信號(hào)的類型）包括OPUS_AUTO (缺省), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC。 看Encoder related CTLs 和 Generic CTLs可以獲得可設(shè)置和查詢的參數(shù)詳細(xì)清單。在一個(gè)音頻流處理過程中，大多數(shù)參數(shù)可以設(shè)置或修改。 為了對(duì)一個(gè)幀進(jìn)行編碼，必須正確地用音頻數(shù)據(jù)的幀(2.5, 5, 10, 20, 40 或60 毫秒)來調(diào)用opus_encode() 或opus_encode_float()函數(shù)。 len = opus_encode(enc, audio_frame, frame_size, packet, max_packet); 在這里： l audio_frame（音頻幀）是opus_int16(或用于opus_encode_float()的浮點(diǎn))格式的音頻數(shù)據(jù) l frame_size（幀大?。┦菢颖局袔淖畲髷?shù)(每個(gè)通道) l packet（包）是寫成壓縮數(shù)據(jù)的字節(jié)數(shù)組, l max_packet是可以寫入包的字節(jié)數(shù)的最大值推薦(4000字節(jié))。不要使用max_packet控制VBR的目標(biāo)比特率,而應(yīng)該用OPUS_SET_BITRATE CTL。 opus_encode() 和opus_encode_float()返回實(shí)際寫入包的字節(jié)數(shù)。返回值可以是負(fù)數(shù),這表明一個(gè)錯(cuò)誤已經(jīng)發(fā)生。如果返回值是1個(gè)字節(jié),那么包不需要傳播(DTX)。 一旦一個(gè)編碼器狀態(tài)已不再需要，可以用以下方式解構(gòu)： opus_encoder_destroy(enc); 如果編碼器是用opus_encoder_init() 創(chuàng)建的，而不是使用opus_encoder_create()函數(shù)，那么不需要采取行動(dòng)，要求從潛在的釋放為它手動(dòng)分配的內(nèi)存(上述例子是調(diào)用 free(enc))中分離。 類型定義文檔 typedef struct OpusEncoder OpusEncoder Opus編碼器狀態(tài)。 這包含了一個(gè)Opus編碼器的完整狀態(tài)。它是位置獨(dú)立的，并且可以自由復(fù)制。 函數(shù)文檔 opus_int32 opus_encode ( OpusEncoder * st, const opus_int16 * pcm, int frame_size, unsigned char * data, opus_int32 max_data_bytes ) 對(duì)一個(gè)Opus幀進(jìn)行編碼。 參數(shù)： [in] st OpusEncoder*:編碼器狀態(tài) [in] pcm opus_int16*: 輸入信號(hào)(如果是2 通道有交叉). 長度是 frame_size*channels*sizeof(opus_int16) [in] frame_size int:輸入信號(hào)的每通道樣本數(shù). 這必須是編碼器采樣率的Opus幀大小。比如，48 kHz 下允許值有120, 240, 480, 960, 1920, 和 2880。少于10毫秒的采樣（48 kHz 有480個(gè)樣本），將阻止編碼器使用LPC或混合模式。 [out] data unsigned char*: 輸出負(fù)載。必須包含至少max_data_bytes 的容量。 [in] max_data_bytes opus_int32: 為輸出負(fù)載所分配的內(nèi)存大小?？梢杂糜谙拗乒潭ū忍芈实淖畲笊舷?，但不能用作唯一的比特率限制，可以用OPUS_SET_BITRATE來控制比特率。 返回值：成功，是被編碼包的長度（字節(jié)數(shù)），失敗，一個(gè)負(fù)的錯(cuò)誤代碼 opus_int32 opus_encode_float ( OpusEncoder * st, const float * pcm, int frame_size, unsigned char * data, opus_int32 max_data_bytes ) 根據(jù)浮點(diǎn)輸入對(duì)一個(gè) Opus幀進(jìn)行編碼. 參數(shù)： [in] st OpusEncoder*:編碼器狀態(tài) [in] pcm float*:浮點(diǎn)格式的輸入(如果是2 通道有交叉)，正常范圍在+/-1.0之間. 超過該范圍的采樣也是支持的，但它將被解碼器用整型API截取，并且只能在知道遠(yuǎn)端支持?jǐn)U展的動(dòng)態(tài)范圍的情況下使用。長度是 frame_size*channels*sizeof(float) [in] frame_size int: 輸入信號(hào)的每通道樣本數(shù). 這必須是編碼器采樣率的Opus幀大小。比如，48 kHz 下允許值有120, 240, 480, 960, 1920, 和 2880。少于10毫秒的采樣（48 kHz 有480個(gè)樣本），將阻止編碼器使用LPC或混合模式。 [out] data unsigned char*:輸出負(fù)載。必須包含至少max_data_bytes 的容量。 [in] max_data_bytes opus_int32: 為輸出負(fù)載所分配的內(nèi)存大小?？梢杂糜谙拗乒潭ū忍芈实淖畲笊舷?，但不能用作唯一的比特率限制，可以用OPUS_SET_BITRATE來控制比特率。. 返回值： 成功，是被編碼包的長度（字節(jié)數(shù)），失敗，一個(gè)負(fù)的錯(cuò)誤代碼。 OpusEncoder* opus_encoder_create ( opus_int32 Fs, int channels, int application, int * error ) 分配和初始化一個(gè)編碼器狀態(tài)。 包括三種編碼模式： OPUS_APPLICATION_VOIP：在給定比特率條件下為聲音信號(hào)提供最高質(zhì)量，它通過高通濾波和強(qiáng)調(diào)共振峰和諧波增強(qiáng)了輸入信號(hào)。它包括帶內(nèi)前向錯(cuò)誤檢查以預(yù)防包丟失。典型的VOIP應(yīng)用程序使用這種模式。由于進(jìn)行了增強(qiáng)，即使是高比特率的情況下，輸出的聲音與輸入相比，聽起來可能不一樣。 OPUS_APPLICATION_AUDIO：對(duì)大多數(shù)非語音信號(hào)，如音樂，在給定比特率條件下提供了最高的質(zhì)量。使用這種模式的場(chǎng)合包括音樂、混音(音樂/聲音),廣播,和需要不到15 毫秒的信號(hào)延遲的其他應(yīng)用。 OPUS_APPLICATION_RESTRICTED_LOWDELAY：配置低延遲模式將為減少延遲禁用語音優(yōu)化模式。這種模式只能在剛初始化或剛重設(shè)編碼器的情況下使用，因?yàn)樵谶@些情況下編解碼器的延遲被修改了。 （當(dāng)心?。┊?dāng)調(diào)用者知道語音優(yōu)化模式不再需要時(shí)，配置低延遲模式是有用的。 參數(shù)： [in] Fs opus_int32: 輸入信號(hào)的采樣率 (Hz)，必須是8000、12000、16000、24000、或48000。 [in] channels int:輸入信號(hào)的通道數(shù) (1 or 2) 。 [in] application int:編碼模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) [out] error int*: 錯(cuò)誤代碼 注意：無論選擇什么樣的采樣率和通道數(shù), 如果選擇的比特率太低，Opus編碼器可以切換到一個(gè)較低的音頻帶寬或通道數(shù)。這也意味著總是使用48 kHz立體聲輸入和讓編碼器優(yōu)化編碼是安全的。 int opus_encoder_ctl ( OpusEncoder * st, int request, ... ) 向一個(gè)Opus編碼器執(zhí)行一個(gè) CTL 函數(shù). 一般其請(qǐng)求和后續(xù)的參數(shù)是由一個(gè)提供便利的宏來產(chǎn)生的。 參數(shù): st OpusEncoder*: 編碼器狀態(tài) request int：這個(gè)及所有其他參數(shù)應(yīng)被1個(gè)在Generic CTLs 或Encoder related CTLs所提供便利的宏來替代 參見: Generic CTLs Encoder related CTLs void opus_encoder_destroy ( OpusEncoder * st ) Frees an OpusEncoder allocated by opus_encoder_create(). 釋放一個(gè)根據(jù)opus_encoder_create()已分配的OpusEncoder 對(duì)象。 參數(shù): [in] st OpusEncoder*: 用于釋放的編碼器狀態(tài)。 int opus_encoder_get_size ( int channels ) 獲得 OpusEncoder結(jié)構(gòu)的大小。 參數(shù): [in] channels int: 通道數(shù)，必須是1或2. 返回: 字節(jié)數(shù)的大小. int opus_encoder_init ( OpusEncoder * st, opus_int32 Fs, int channels, int application ) 初始化一個(gè)以前分配的編碼器狀態(tài)。狀態(tài)所指向的內(nèi)存必須至少是opus_encoder_get_size()返回的大小. 在這里，應(yīng)用程序不要用系統(tǒng)自動(dòng)分配內(nèi)存，而要準(zhǔn)備用自己的分配器。 參見: opus_encoder_create(),opus_encoder_get_size()。為重設(shè)一個(gè)以前初始化的狀態(tài)，使用OPUS_RESET_STATE CTL. 參數(shù): [in] st OpusEncoder*: 編碼器狀態(tài) [in] Fs opus_int32: 輸入信號(hào)的采樣率 (Hz)，必須是8000、12000、16000、24000、或48000。 [in] channels int: 輸入信號(hào)的通道數(shù) (1 or 2) [in] application int: 編碼模式(OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY) 返回值: 成功，OPUS_OK ，失敗，錯(cuò)誤代碼。  Opus Decoder 本節(jié)描述了Opus解碼器OpusDecoder的過程和函數(shù) 類型定義 typedef struct OpusDecoder? OpusDecoder ? Opus 解碼器狀態(tài). 函數(shù) int? opus_decoder_get_size (int channels) ? 獲得OpusDecoder 結(jié)構(gòu)的大小. OpusDecoder *? opus_decoder_create (opus_int32 Fs, int channels, int *error) ? 分配和初始化解碼器狀態(tài). int? opus_decoder_init (OpusDecoder *st, opus_int32 Fs, int channels) ? 初始化以前分配的解碼器狀態(tài). int? opus_decode (OpusDecoder *st, const unsigned char *data, opus_int32 len, opus_int16 *pcm, int frame_size, int decode_fec) ? 解碼一個(gè) Opus 包. int? opus_decode_float (OpusDecoder *st, const unsigned char *data, opus_int32 len, float *pcm, int frame_size, int decode_fec) ? 解碼一個(gè)浮點(diǎn)輸出的Opus 包，. int? opus_decoder_ctl (OpusDecoder *st, int request,...) ? 向一個(gè)Opus解碼器執(zhí)行CTL 函數(shù)。 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) ? 將一個(gè) opus 包解析成1個(gè)或多個(gè)幀. int? opus_packet_get_bandwidth (const unsigned char *data) ? 獲得一個(gè) Opus包的帶寬. int? opus_packet_get_samples_per_frame (const unsigned char *data, opus_int32 Fs) ? 獲得Opus 包每幀的樣本數(shù)。 int? opus_packet_get_nb_channels (const unsigned char *data) ? 獲得Opus 包的通道數(shù)。 int? opus_packet_get_nb_frames (const unsigned char packet[], opus_int32 len) ? 獲得Opus 包所有幀的數(shù)量. int? opus_packet_get_nb_samples (const unsigned char packet[], opus_int32 len, opus_int32 Fs) ? 獲得Opus 包的樣本數(shù)。 int? opus_decoder_get_nb_samples (const OpusDecoder *dec, const unsigned char packet[], opus_int32 len) ? 獲得Opus 包的樣本數(shù)。 詳細(xì)描述 本節(jié)描述了用于解碼Opus的過程和方法. 與編碼相似，解碼進(jìn)程也是開始于創(chuàng)建一個(gè)解碼器狀態(tài)。用以下方法做到： int error; OpusDecoder *dec; dec = opus_decoder_create(Fs, channels, &error); 在這里： n Fs 是采樣率，必須是8000, 12000, 16000, 24000, 或 48000 n channels 是通道數(shù) (1 或 2) n error 將保存出錯(cuò)情況下的錯(cuò)誤代碼(或成功狀態(tài)下的 OPUS_OK ) n 返回值是一個(gè)新創(chuàng)建的用于解碼的解碼器狀態(tài) 當(dāng) opus_decoder_create() 為狀態(tài)分配內(nèi)存時(shí), 它也可以初始化預(yù)分配的內(nèi)存： 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()返回解碼器狀態(tài)要求的大小. 注意,這段代碼的未來版本可能改變大小,所以沒有assuptions應(yīng)該對(duì)它做出。 解碼器狀態(tài)在內(nèi)存中總是連續(xù),復(fù)制它只要一個(gè)淺拷貝就足夠了。 為解碼一個(gè)幀, opus_decode() 或 opus_decode_float()必須用壓縮音頻數(shù)據(jù)的包來調(diào)用: frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); 在這里 n packet 是包含壓縮數(shù)據(jù)的字節(jié)數(shù)組 n len 是包內(nèi)字節(jié)的精確數(shù)量 n decoded 是opus_int16 (或由 opus_decode_float()定義的浮點(diǎn)型)格式的解碼后的音頻數(shù)據(jù)。 n max_size是可以放入解碼幀的每個(gè)通道各樣本中幀的最大值 opus_decode() 和 opus_decode_float() 返回從包解碼后的每通道樣本的數(shù)量。如果這個(gè)值是負(fù)的，表示有錯(cuò)誤發(fā)生。如果包損壞或音頻緩沖太小不足以容納解碼后的音頻，錯(cuò)誤就會(huì)發(fā)生。 Opus是包含重疊塊的有狀態(tài)的編解碼器，其結(jié)果是Opus 包并不是彼此獨(dú)立編碼。包必須按正確的次序，連續(xù)地進(jìn)入解碼器進(jìn)行正確的解碼。丟失的包可以用遺失隱藏來替換，遺失隱藏用一個(gè)空的指針和0長度的包來調(diào)用解碼器。 一個(gè)單獨(dú)的編解碼器狀態(tài)在一個(gè)時(shí)間只能由一個(gè)單獨(dú)的線程來訪問，調(diào)用者執(zhí)行任何需要的鎖定。各分開的音頻數(shù)據(jù)流可以用各自分開的解碼器狀態(tài)平行地進(jìn)行解碼，除非API庫在編譯時(shí)用了NONTHREADSAFE_PSEUDOSTACK定義。 類型定義文檔 typedef struct OpusDecoder OpusDecoder Opus 解碼器狀態(tài). 這包含了一個(gè)Opus解碼器的完整狀態(tài)。它是位置獨(dú)立的，并且可以自由復(fù)制。 參見: opus_decoder_create,opus_decoder_init 函數(shù)文檔 int opus_decode ( OpusDecoder * st, const unsigned char * data, opus_int32 len, opus_int16 * pcm, int frame_size, int decode_fec ) 對(duì)一個(gè)Opus包進(jìn)行解碼。 參數(shù): [in] st OpusDecoder*: 解碼器狀態(tài) [in] data char*:輸入負(fù)載.對(duì)包丟失使用一個(gè)空指針來表示。 [in] len opus_int32:在輸入負(fù)載中的字節(jié)數(shù) [out] pcm opus_int16*: 輸出信號(hào)（如果是2通道有交叉）。長度等于frame_size*channels*sizeof(opus_int16) [in] frame_size ：在PCM可用空間中每通道的樣本數(shù)。如果小于最大包的時(shí)長（120毫秒，4848kHz5760個(gè)），這個(gè)函數(shù)將不能解碼一些包。如果是PLC (data==NULL) 或 FEC (decode_fec=1)的情況，那么frame_size必須正好是丟失音頻的時(shí)長，否則解碼器無法在解碼下一個(gè)包時(shí)進(jìn)入優(yōu)化狀態(tài)。對(duì)于PLC 和 FEC 的情況，frame_size必須是2.5毫秒的倍數(shù)。 [in] decode_fec int: 對(duì)于請(qǐng)求任何帶內(nèi)前向錯(cuò)誤糾正數(shù)據(jù)進(jìn)行解碼的狀態(tài)標(biāo)志 (0 or 1) 。如果沒有這樣的數(shù)據(jù)可用，幀在解碼時(shí)被認(rèn)為已經(jīng)丟失。 返回: 解碼樣本的數(shù)量，或錯(cuò)誤代碼。 int opus_decode_float ( OpusDecoder * st, const unsigned char * data, opus_int32 len, float * pcm, int frame_size, int decode_fec ) 用浮點(diǎn)輸出格式解碼一個(gè)Opus包。 參數(shù): [in] st OpusDecoder*: 解碼器狀態(tài) [in] data char*:輸入負(fù)載.對(duì)包丟失使用一個(gè)空指針來表示。 [in] len opus_int32: 在輸入負(fù)載中的字節(jié)數(shù) [out] pcm float*:輸出信號(hào)（如果是2通道有交叉）。長度等于frame_size*channels*sizeof(float) [in] frame_size ：在PCM可用空間中每通道的樣本數(shù)。如果小于最大包的時(shí)長（120毫秒，4848kHz5760個(gè)），這個(gè)函數(shù)將不能解碼一些包。如果是PLC (data==NULL) 或 FEC (decode_fec=1)的情況，那么frame_size必須正好是丟失音頻的時(shí)長，否則解碼器無法在解碼下一個(gè)包時(shí)進(jìn)入優(yōu)化狀態(tài)。對(duì)于PLC 和 FEC 的情況，frame_size必須是2.5毫秒的倍數(shù)。 [in] decode_fec int: 對(duì)于請(qǐng)求任何帶內(nèi)前向錯(cuò)誤糾正數(shù)據(jù)進(jìn)行解碼的狀態(tài)標(biāo)志 (0 or 1) 。如果沒有這樣的數(shù)據(jù)可用，幀在解碼時(shí)被認(rèn)為已經(jīng)丟失。 返回: 解碼樣本的數(shù)量，或錯(cuò)誤代碼。 OpusDecoder* opus_decoder_create ( opus_int32 Fs, int channels, int * error ) 分配和初始化解碼器狀態(tài). 參數(shù): [in] Fs opus_int32: 解碼的采樣率 (Hz). 必須是 8000, 12000, 16000, 24000, 或 48000. [in] channels int: 用于解碼的通道數(shù)(1 or 2) [out] error int*:成功時(shí)是 OPUS_OK Success或錯(cuò)誤代碼 Opus在內(nèi)部用48000 Hz來存儲(chǔ)數(shù)據(jù)，所以對(duì)于FS來說48000 Hz是缺省值。然而，解碼器在8, 12, 16, 和 24 kHz下也可以有效解碼到緩沖，所以，由于某些原因調(diào)用者不能在全采樣率下使用數(shù)據(jù)，或知道被壓縮的數(shù)據(jù)不能在全頻率范圍內(nèi)使用，可以請(qǐng)求用更小的頻率解碼。同樣的，解碼器可以根據(jù)調(diào)用者的請(qǐng)求，填充單聲道或交叉立體聲的PCM緩沖區(qū)。 int opus_decoder_ctl ( OpusDecoder * st, int request, ... ) 向一個(gè)Opus解碼器執(zhí)行一個(gè) CTL 函數(shù). 一般其請(qǐng)求和后續(xù)的參數(shù)是由一個(gè)提供便利的宏來產(chǎn)生的。 參數(shù): n st OpusDecoder*: 解碼器狀態(tài). n request ：這個(gè)及所有其他剩余參數(shù)應(yīng)被1個(gè)在Generic CTLs 或Encoder related CTLs所提供便利的宏來替代 參見: Generic CTLs Decoder related CTLs void opus_decoder_destroy ( OpusDecoder * st ) 釋放一個(gè)根據(jù)opus_decoder_create()已分配的OpusDecoder 對(duì)象. 參數(shù): [in] st OpusDecoder*:用于釋放的解碼器狀態(tài)。 int opus_decoder_get_nb_samples ( const OpusDecoder * dec, const unsigned char packet[], opus_int32 len ) 獲得一個(gè)Opus包的樣本數(shù) 參數(shù): [in] dec OpusDecoder*: 解碼器狀態(tài) [in] packet char*: Opus包 [in] len opus_int32: 包的長度 返回: 樣本的數(shù)量 返回值: OPUS_INVALID_PACKET：通過的被壓縮數(shù)據(jù)已損壞或其格式不被支持。 int opus_decoder_get_size ( int channels ) 獲得 OpusDecoder結(jié)構(gòu)的大小。 參數(shù): [in] channels int: 通道數(shù)，必須是1或2. 返回: 字節(jié)數(shù)的大小. int opus_decoder_init ( OpusDecoder * st, opus_int32 Fs, int channels ) 初始化一個(gè)以前分配過的解碼器狀態(tài). 狀態(tài)必須至少是opus_decoder_get_size()返回的大小. 在這里，應(yīng)用程序不要用系統(tǒng)自動(dòng)分配內(nèi)存，而要準(zhǔn)備用自己的分配器。 參見: opus_decoder_create,opus_decoder_get_size,為重設(shè)一個(gè)以前初始化的狀態(tài)，使用OPUS_RESET_STATE CTL. 參數(shù): [in] st OpusDecoder*: 解碼器狀態(tài). [in] Fs opus_int32: 準(zhǔn)備解碼的采樣率 (Hz). 必須是8000、12000、16000、24000、或48000. [in] channels int: 解碼的通道數(shù) (1 or 2) 返回值: 成功，OPUS_OK ，失敗，錯(cuò)誤代碼。 int opus_packet_get_bandwidth ( const unsigned char * data ) 獲得一個(gè)Opus包的帶寬。 參數(shù): [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 通過的被壓縮數(shù)據(jù)已損壞或其格式不被支持 int opus_packet_get_nb_channels ( const unsigned char * data ) 獲得Opus 包的通道數(shù)。 參數(shù): [in] data char*: Opus 包 返回: 通道數(shù)量 返回值: OPUS_INVALID_PACKET 通過的被壓縮數(shù)據(jù)已損壞或其格式不被支持 int opus_packet_get_nb_frames ( const unsigned char packet[], opus_int32 len ) 獲得Opus 包所有幀的數(shù)量. 參數(shù): [in] packet char*: Opus 包 [in] len opus_int32:包的長度 返回: 幀的數(shù)量 返回值: OPUS_INVALID_PACKET 通過的被壓縮數(shù)據(jù)已損壞或其格式不被支持 int opus_packet_get_nb_samples ( const unsigned char packet[], opus_int32 len, opus_int32 Fs ) 獲得Opus 包的樣本數(shù)。 參數(shù): [in] packet char*: Opus 包 [in] len opus_int32: 包的長度 [in] Fs opus_int32: 采樣率（Hz）. 必須是400的倍數(shù)，否則結(jié)果不準(zhǔn)確。 返回: 樣本的數(shù)量 返回值: OPUS_INVALID_PACKET 通過的被壓縮數(shù)據(jù)已損壞或其格式不被支持 int opus_packet_get_samples_per_frame ( const unsigned char * data, opus_int32 Fs ) 獲得Opus 包每幀的樣本數(shù)。 參數(shù): [in] data char*: Opus 包. 必須包含至少一個(gè)字節(jié)的數(shù)據(jù)。 [in] Fs opus_int32: 采樣率（Hz）.必須是400的倍數(shù)，否則結(jié)果不準(zhǔn)確。 返回: 每幀樣本的數(shù)量. 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 ) 將一個(gè) opus 包解析成1個(gè)或多個(gè)幀. Opus_decode在內(nèi)部執(zhí)行這個(gè)操作，所以大多數(shù)應(yīng)用程序不需要用到這個(gè)函數(shù)。這個(gè)函數(shù)不復(fù)制各幀，返回的指針是輸入包內(nèi)部的指針。 參數(shù): [in] data char*:要進(jìn)行解析的 Opus包 [in] len opus_int32: 數(shù)據(jù)的大小 [out] out_toc char*: TOC 指針 [out] frames char*[48] 封裝過的幀 [out] size short[48] 封裝過的幀的大小 [out] payload_offset int*: 返回在包內(nèi)負(fù)載的位置(按字節(jié)) 返回: 幀的數(shù)量  Repacketizer Repacketizer可將多個(gè)包Opus合并成一個(gè)包，或?qū)⒁郧昂喜⒌陌蛛x成多個(gè)Opus包。 類型定義 typedef struct OpusRepacketizer? OpusRepacketizer 函數(shù) int? opus_repacketizer_get_size (void) ? 獲得 OpusRepacketizer結(jié)構(gòu)的大小 OpusRepacketizer *? opus_repacketizer_init (OpusRepacketizer *rp) ? (重新)初始化以前分配過的repacketizer 狀態(tài). OpusRepacketizer *? opus_repacketizer_create (void) ? 為用opus_repacketizer_init()產(chǎn)生的新repacketizer 分配內(nèi)存和初始化。 void? opus_repacketizer_destroy (OpusRepacketizer *rp) ? 釋放通過opus_repacketizer_create()分配過的OpusRepacketizer int? opus_repacketizer_cat (OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) ? 給當(dāng)前的repacketizer 狀態(tài)增加一個(gè)包。 opus_int32? opus_repacketizer_out_range (OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen) ? 通過opus_repacketizer_cat()從以前提交給repacketizer狀態(tài)的數(shù)據(jù)構(gòu)建一個(gè)新的包。 int? opus_repacketizer_get_nb_frames (OpusRepacketizer *rp) ? 返回最后一次調(diào)用opus_repacketizer_init() 或 opus_repacketizer_create()后，到當(dāng)前為止通過opus_repacketizer_cat()提交的包數(shù)據(jù)所包含的幀的總數(shù)。 opus_int32? opus_repacketizer_out (OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) ? 通過opus_repacketizer_cat()從以前提交給repacketizer狀態(tài)的數(shù)據(jù)構(gòu)建一個(gè)新的包。 詳細(xì)描述 Repacketizer可將多個(gè)包Opus合并成一個(gè)包，或?qū)⒁郧昂喜⒌陌蛛x成多個(gè)Opus包。 分離有效的包可以保證成功，然而，只有在所有的幀都有相同的編碼模式、帶寬、幀大小，并且合并后的包總的時(shí)長不超過120毫秒，合并有效的包才能成功。對(duì)多流包的操作不會(huì)成功，除了這些包由來自同一音頻流的數(shù)據(jù)組成的退化情況。 重構(gòu)包的過程開始于創(chuàng)建一個(gè)repacketizer狀態(tài)，創(chuàng)建既可以通過調(diào)用opus_repacketizer_create()函數(shù)也可以通過自己分配內(nèi)存的方式來進(jìn)行，例如 OpusRepacketizer *rp; rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size()); if (rp != NULL) opus_repacketizer_init(rp); 之后應(yīng)用程序應(yīng)通過opus_repacketizer_cat()來提交包，用opus_repacketizer_out()或opus_repacketizer_out_range()提取新的包，然后通過opus_repacketizer_init()為下一套輸入包重設(shè)狀態(tài)。 下面的例子中，將一個(gè)系列的包分離成各單獨(dú)的幀： unsigned char *data; int len; while (get_next_packet(&data, &len)) { unsigned char out[1276]; opus_int32 out_len; int nb_frames; int err; int i; err = opus_repacketizer_cat(rp, data, len); if (err != OPUS_OK) { release_packet(data); return err; } nb_frames = opus_repacketizer_get_nb_frames(rp); for (i = 0; i < nb_frames; i++) { out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out)); if (out_len < 0) { release_packet(data); return (int)out_len; } output_next_packet(out, out_len); } opus_repacketizer_init(rp); release_packet(data); } 可選擇將一個(gè)系列的幀合并到各個(gè)包中，每個(gè)包包含最多TARGET_DURATION_MS毫秒的數(shù)據(jù): // The maximum number of packets with duration TARGET_DURATION_MS occurs // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5) // packets. unsigned char *data[(TARGET_DURATION_MS*2/5)+1]; opus_int32 len[(TARGET_DURATION_MS*2/5)+1]; int nb_packets; unsigned char out[1277*(TARGET_DURATION_MS*2/2)]; opus_int32 out_len; int prev_toc; nb_packets = 0; while (get_next_packet(data+nb_packets, len+nb_packets)) { int nb_frames; int err; nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]); if (nb_frames < 1) { release_packets(data, nb_packets+1); return nb_frames; } nb_frames += opus_repacketizer_get_nb_frames(rp); // If adding the next packet would exceed our target, or it has an // incompatible TOC sequence, output the packets we already have before // submitting it. // N.B., The nb_packets > 0 check ensures we've submitted at least one // packet since the last call to opus_repacketizer_init(). Otherwise a // single packet longer than TARGET_DURATION_MS would cause us to try to // output an (invalid) empty packet. It also ensures that prev_toc has // been set to a valid value. Additionally, len[nb_packets] > 0 is // guaranteed by the call to opus_packet_get_nb_frames() above, so the // reference to data[nb_packets][0] should be valid. if (nb_packets > 0 && ( ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) || opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames > TARGET_DURATION_MS*48)) { out_len = opus_repacketizer_out(rp, out, sizeof(out)); if (out_len < 0) { release_packets(data, nb_packets+1); return (int)out_len; } output_next_packet(out, out_len); opus_repacketizer_init(rp); release_packets(data, nb_packets); data[0] = data[nb_packets]; len[0] = len[nb_packets]; nb_packets = 0; } err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]); if (err != OPUS_OK) { release_packets(data, nb_packets+1); return err; } prev_toc = data[nb_packets][0]; nb_packets++; } // Output the final, partial packet. if (nb_packets > 0) { out_len = opus_repacketizer_out(rp, out, sizeof(out)); release_packets(data, nb_packets); if (out_len < 0) return (int)out_len; output_next_packet(out, out_len); } 合并包的一個(gè)可替代方案是僅僅無條件地調(diào)用opus_repacketizer_cat()直到失敗。這樣，可以用opus_repacketizer_out()來獲得合并后的包，opus_repacketizer_cat()輸入的包需要重新添加到一個(gè)新的重新初始化的repacketizer狀態(tài). 類型定義文檔 typedef struct OpusRepacketizer OpusRepacketizer 函數(shù)文檔 int opus_repacketizer_cat ( OpusRepacketizer * rp, const unsigned char * data, opus_int32 len )