Opus從入門到精通(二):編解碼器使用

時間  2019-11-24
標籤 opus 入門 精通 解碼器 使用 简体版
原文   原文鏈接

Opus官方編碼器實現,包括:html

編碼器

類型定義

typedef struct OpusEncoder OpusEncoder //Opus encoder 狀態.git

函數

Function 說明
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是一個有狀態的編解碼器，編碼過程始於建立一個編碼器狀態，用如下方法作到：github

int error;
OpusEncoder *enc;
enc = opus_encoder_create(Fs, channels, application, &error);
複製代碼

從這一點上, enc能夠用於編碼音頻流。一個編碼器狀態在同一時間不得用於多於一個音頻流。一樣,編碼器狀態不能對於每幀從新初始化。當opus_encoder_create()爲狀態分配內存時，它也能夠初始化預分配的內存：api

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()函數。bash

len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);
複製代碼

在這裏：app

  • audio_frame（音頻幀）是opus_int16(或用於opus_encode_float()的浮點)格式的音頻數據
  • frame_size（幀大小）是樣本中幀的最大數(每一個通道)
  • packet（包）是寫成壓縮數據的字節數組,
  • 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編碼器的完整狀態。它是位置獨立的，而且能夠自由複製。less

函數文檔

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:輸入信號的每通道樣本數.
[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、12000、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 函數.通常其請求和後續的參數是由一個提供便利的宏來產生的。

參數
[in] st OpusEncoder*: 編碼器狀態
[in] 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、12000、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

類型定義

typedef struct OpusDecoder OpusDecoder //Opus 解碼器狀態.
複製代碼

函數

functon
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 channel)|初始化之前分配的解碼器狀態.| |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 包的樣本數。|

詳細描述

與編碼類似，解碼進程也是開始於建立一個解碼器狀態。用如下方法作到：

int error;
OpusDecoder *dec;
dec = opus_decoder_create(Fs, channels, &error);
複製代碼

在這裏：   - Fs 是採樣率，必須是8000, 12000, 16000, 24000, 或 48000   - channels 是通道數 (1 或 2)   - error 將保存出錯狀況下的錯誤代碼(或成功狀態下的 OPUS_OK )   - 返回值是一個新建立的用於解碼的解碼器狀態

  當 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); 在這裏   - packet 是包含壓縮數據的字節數組   - len 是包內字節的精確數量   - decoded 是opus_int16 (或由 opus_decode_float()定義的浮點型)格式的解碼後的音頻數據。   - 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 int：在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 int：在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, 12000, 16000, 24000, 或 48000.
[in] channels int: 用於解碼的通道數(1 or 2)
[out] error int*:成功時是 OPUS_OK Success或錯誤代碼 
int opus_decoder_ctl    (   OpusDecoder *   st,
        int     request,
            ... 
    ) 
複製代碼

向一個Opus解碼器執行一個 CTL 函數. 通常其請求和後續的參數是由一個提供便利的宏來產生的。

參數
st OpusDecoder*: 解碼器狀態.!
request int：這個及全部其餘剩餘參數應被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、12000、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 包

返回值:

  • OPUS_BANDWIDTH_NARROWBAND 窄帶 (4kHz bandpass)
  • OPUS_BANDWIDTH_MEDIUMBAND 中等帶寬 (6kHz bandpass)
  • OPUS_BANDWIDTH_WIDEBAND 寬帶 (8kHz bandpass)
  • OPUS_BANDWIDTH_SUPERWIDEBAND 高寬帶 (12kHz bandpass)
  • OPUS_BANDWIDTH_FULLBAND 全寬帶 (20kHz bandpass)
  • OPUS_INVALID_PACKET 經過的被壓縮數據已損壞或其格式不被支持
int opus_packet_get_nb_channels ( const unsigned char *     data )  
複製代碼

得到Opus 包的通道數。

參數
[int] 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
[in] len opus_int32: 包的長度
[in] Fs

返回:   樣本的數量 返回值:   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 char*: TOC 指針
[out] frames char*[48] 封裝過的幀
[out] size short[48] 封裝過的幀的大小
[out] payload_offset int*: 返回在包內負載的位置(按字節)

返回:   幀的數量

Repacketizer

Repacketizer可將多個包Opus合併成一個包，或將之前合併的包分離成多個Opus包。

類型定義

typedef struct OpusRepacketizer OpusRepacketizer
複製代碼

函數

int opus_repacketizer_get_size (void)
//得到 OpusRepacketizer結構的大小
OpusRepacketizer* opus_repacketizer_init (OpusRepacketizer *rp)
 //(從新)初始化之前分配過的repacketizer 狀態. 
OpusRepacketizer* opus_repacketizer_create (void)
//爲用opus_repacketizer_init()產生的新repacketizer 分配內存和初始化。 
void opus_repacketizer_destroy (OpusRepacketizer *rp)
//釋放經過opus_repacketizer_create()分配過的OpusRepacketizer 
int opus_repacketizer_cat (OpusRepacketizer *rp, 
    const unsigned char *data, 
    opus_int32 len )
//給當前的repacketizer 狀態增長一個包。 
opus_int32 opus_repacketizer_out_range (
    OpusRepacketizer *rp, 
    int begin, int end, 
    unsigned char *data, 
    opus_int32 maxlen)
//經過opus_repacketizer_cat()從之前提交給repacketizer狀態的數據構建一個新的包。
int opus_repacketizer_get_nb_frames (OpusRepacketizer *rp)
//返回最後一次調用opus_repacketizer_init() 或 opus_repacketizer_create()後，到當前爲止經過opus_repacketizer_cat()提交的包數據所包含的幀的總數。 
opus_int32 opus_repacketizer_out (
    OpusRepacketizer *rp, 
    unsigned char *data, 
    opus_int32 maxlen)
//經過opus_repacketizer_cat()從之前提交給repacketizer狀態的數據構建一個新的包。
複製代碼

詳細描述

Repacketizer可將多個包Opus合併成一個包，或將之前合併的包分離成多個Opus包。 分離有效的包能夠保證成功，然而，只有在全部的幀都有相同的編碼模式、帶寬、幀大小，而且合併後的包總的時長不超過120毫秒，合併有效的包才能成功。對多流包的操做不會成功，除了這些包由來自同一音頻流的數據組成的退化狀況。 重構包的過程開始於建立一個repacketizer狀態，建立既能夠經過調用opus_repacketizer_create()函數也能夠經過本身分配內存的方式來進行，例如

OpusRepacketizer *rp;
rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size());
if (rp != NULL)
    opus_repacketizer_init(rp);
複製代碼

以後應用程序應經過opus_repacketizer_cat()來提交包，用opus_repacketizer_out()或opus_repacketizer_out_range()提取新的包，而後經過opus_repacketizer_init()爲下一套輸入包重設狀態。 下面的例子中，將一個系列的包分離成各單獨的幀：

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);
}
複製代碼

可選擇將一個系列的幀合併到各個包中，每一個包包含最多TARGET_DURATION_MS毫秒的數據:

// 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); } 複製代碼

合併包的一個可替代方案是僅僅無條件地調用opus_repacketizer_cat()直到失敗。這樣，能夠用opus_repacketizer_out()來得到合併後的包，opus_repacketizer_cat()輸入的包須要從新添加到一個新的從新初始化的repacketizer狀態.

類型定義文檔

typedef struct OpusRepacketizer OpusRepacketizer
複製代碼

函數文檔

int opus_repacketizer_cat ( OpusRepacketizer * rp,
        const unsigned char *   data,
        opus_int32      len 
    ) 
複製代碼

添加一個包到當前repacketizer狀態。   這個包必須符合自從最後一次調用opus_repacketizer_init()後，已經提交給repacketizer狀態的任何包的配置。這意味着它必須有相同的編碼模式、帶寬、幀大小和通道數。能夠提早進行檢查，方法是經過監測包第一個字節的前6位，檢查它們是否與其餘任何已提交的包的第一個字節的前6位項匹配。添加這個包之後，單個包的總時長，以及在repacketizer狀態的音頻總時長都不能超過120毫秒。   This packet must match the configuration of any packets already submitted for repacketization since the last call to opus_repacketizer_init(). This means that it must have the same coding mode, audio bandwidth, frame size, and channel count. This can be checked in advance by examining the top 6 bits of the first byte of the packet, and ensuring they match the top 6 bits of the first byte of any previously submitted packet. The total duration of audio in the repacketizer state also must not exceed 120 ms, the maximum duration of a single packet, after adding this packet.   用opus_repacketizer_out() 或 opus_repacketizer_out_range()，當前repacketizer狀態的內容能夠被提取到新的包。   The contents of the current repacketizer state can be extracted into new packets using opus_repacketizer_out() or opus_repacketizer_out_range().   若是想添加不一樣配置的包，或加更多的超過120毫秒的音頻數據，就必須調用opus_repacketizer_init()來清除repacketizer狀態。若是一個包太大不能總體添加到當前repacketizer狀態，它的任何一部分也不能添加，即便這個包包含多個幀，其中部分也許適合添加。若是你想添加這樣的包的部份內容，你應當首先使用另外一個repacketizer來將這些包分離成適合添加的小片，再一個個地將這些小片加入目標repacketizer狀態。   In order to add a packet with a different configuration or to add more audio beyond 120 ms, you must clear the repacketizer state by calling opus_repacketizer_init(). If a packet is too large to add to the current repacketizer state, no part of it is added, even if it contains multiple frames, some of which might fit. If you wish to be able to add parts of such packets, you should first use another repacketizer to split the packet into pieces and add them individually.

參見:   opus_repacketizer_out_range   opus_repacketizer_out   opus_repacketizer_init 參數: [in] rp OpusRepacketizer*:將要添加包的repacketizer狀態。 The repacketizer state to which to add the packet. [in] data const unsigned char*: 包數據。應用程序必須確保這個指針合法有效直到對opus_repacketizer_init() 或 opus_repacketizer_destroy()的下一次調用。The packet data. The application must ensure this pointer remains valid until the next call to opus_repacketizer_init() or opus_repacketizer_destroy(). [in] len opus_int32: 包數據中的字節數。The number of bytes in the packet data. 返回: 表示操做成功與否的錯誤代碼。 An error code indicating whether or not the operation succeeded. 返回值: OPUS_OK 包的內容已被添加到repacketizer狀態。The packet's contents have been added to the repacketizer狀態. OPUS_INVALID_PACKET 包的TOC系列無效，該系列不能與之前提交的包相匹配（編碼模式、音頻帶寬、幀大小或通道數不吻合），或添加這個包將致使存儲在repacketizer狀態的聲音時長超過120毫秒。The packet did not have a valid TOC sequence, the packet's TOC sequence was not compatible with previously submitted packets (because the coding mode, audio bandwidth, frame size, or channel count did not match), or adding this packet would increase the total amount of audio stored in the repacketizer狀態 to more than 120 ms.

OpusRepacketizer* opus_repacketizer_create ( void )
複製代碼

爲用opus_repacketizer_init()產生的新repacketizer 分配內存和初始化。 Allocates memory and initializes the new repacketizer with opus_repacketizer_init().

void opus_repacketizer_destroy ( OpusRepacketizer * rp )
複製代碼

釋放經過opus_repacketizer_create()分配過的OpusRepacketizer。 Frees an OpusRepacketizer allocated by opus_repacketizer_create(). 參數: [in] rp OpusRepacketizer*:將被釋放的repacketizer狀態。 State to be freed.

int opus_repacketizer_get_nb_frames ( OpusRepacketizer * rp )
複製代碼

返回最後一次調用opus_repacketizer_init() 或 opus_repacketizer_create()後，到當前爲止經過opus_repacketizer_cat()提交的包數據所包含的幀的總數。 Return the total number of frames contained in packet data submitted to the repacketizer狀態 so far via opus_repacketizer_cat() since the last call to opus_repacketizer_init() or opus_repacketizer_create(). 這裏定義了能被opus_repacketizer_out_range() 或 opus_repacketizer_out()提取的有效包的範圍。 This defines the valid range of packets that can be extracted with opus_repacketizer_out_range() or opus_repacketizer_out(). 參數: rp OpusRepacketizer*: 包含各幀的repacketizer狀態。The repacketizer狀態 containing the frames. 返回: 提交給repacketizer狀態的包所包含的幀的總數。 The total number of frames contained in the packet data submitted to the repacketizer狀態.

int opus_repacketizer_get_size ( void )
複製代碼

得到 OpusRepacketizer結構的大小 Gets the size of an OpusRepacketizer structure. 返回: 結構體字節的大小 The size in bytes.

OpusRepacketizer* opus_repacketizer_init ( OpusRepacketizer * rp )
複製代碼

(從新)初始化之前分配過的repacketizer 狀態 (Re)initializes a previously allocated repacketizer狀態. Repacketizer狀態必須至少有opus_repacketizer_get_size()返回的大小。這適用於不使用malloc()，而是用本身的分配器的應用程序。它也要被調用來重設正在等待重構的那些包的隊列，若是最大包時長達到120ms或你但願用不一樣的Opus配置（編碼模式、音頻帶寬、幀大小或通道數）來提交包的時候，這麼作就有必要了。這麼作若是失敗了，系統將阻止用opus_repacketizer_cat()添加新的包。 The state must be at least the size returned by opus_repacketizer_get_size(). This can be used for applications which use their own allocator instead of malloc(). It must also be called to reset the queue of packets waiting to be repacketized, which is necessary if the maximum packet duration of 120 ms is reached or if you wish to submit packets with a different Opus configuration (coding mode, audio bandwidth, frame size, or channel count). Failure to do so will prevent a new packet from being added with opus_repacketizer_cat(). 參見: opus_repacketizer_create opus_repacketizer_get_size opus_repacketizer_cat 參數: rp OpusRepacketizer*:須要 (從新)初始化的repacketizer狀態 返回: 輸入的同一個repacketizer狀態的指針。 A pointer to the same repacketizer狀態 that was passed in.

opus_int32 opus_repacketizer_out    (   OpusRepacketizer *      rp,
        unsigned char *     data,
        opus_int32      maxlen 
    ) 
複製代碼

經過opus_repacketizer_cat()從之前提交給repacketizer狀態的數據構建一個新的包。 Construct a new packet from data previously submitted to the repacketizer狀態 via opus_repacketizer_cat(). 返回迄今提交進單一個包的全部數據能夠提供便利，這麼作等同於調用opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp),data, maxlen) This is a convenience routine that returns all the data submitted so far in a single packet. It is equivalent to calling opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), data, maxlen) 參數: rp OpusRepacketizer*: 準備構建新包的repacketizer狀態。The repacketizer狀態 from which to construct the new packet. [out] data const unsigned char*: 將要存儲輸出包的緩衝區。The buffer in which to store the output packet. maxlen opus_int32: 將要存入輸出緩衝區的字節最大數。爲保證成功，這個值應該至少爲1277opus_repacketizer_get_nb_frames(rp)。然而，1opus_repacketizer_get_nb_frames(rp)加上自從上次調用opus_repacketizer_init() 或opus_repacketizer_create()以來全部提交包數據的大小，也是足夠的，也可能小得多（此話似有矛盾）。 The maximum number of bytes to store in the output buffer. In order to guarantee success, this should be at least 1277opus_repacketizer_get_nb_frames(rp). However, 1opus_repacketizer_get_nb_frames(rp) plus the size of all packet data submitted to the repacketizer since the last call to opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, and possibly much smaller. 返回: 成功，輸出包總的大小，失敗，錯誤代碼。 The total size of the output packet on success, or an error code on failure. 返回值: OPUS_BUFFER_TOO_SMALL 最大容量maxlen不足以包含整個輸出包。maxlen was insufficient to contain the complete output packet.

opus_int32 opus_repacketizer_out_range  (   OpusRepacketizer *      rp,
        int     begin,
        int     end,
        unsigned char *     data,
        opus_int32      maxlen 
    )   
複製代碼

經過opus_repacketizer_cat()從之前提交給repacketizer狀態的數據構建一個新的包。 Construct a new packet from data previously submitted to the repacketizer狀態 via opus_repacketizer_cat(). 參數: rp OpusRepacketizer*:準備構建新包的repacketizer狀態。The repacketizer state from which to construct the new packet. begin int: 準備輸出的當前repacketizer狀態第一幀的索引。The index of the first frame in the current repacketizer state to include in the output. end int: 準備輸出的當前repacketizer狀態最後一幀的索引再加1.One past the index of the last frame in the current repacketizer state to include in the output. [out] data const unsigned char*: 準備存儲輸出包的緩衝區。The buffer in which to store the output packet. maxlen opus_int32: 將要存入輸出緩衝區的字節最大數。爲保證成功，這個值應該至少爲1277opus_repacketizer_get_nb_frames(rp)。然而，1opus_repacketizer_get_nb_frames(rp)加上自從上次調用opus_repacketizer_init() 或opus_repacketizer_create()以來全部提交包數據的大小，也是足夠的，也可能小得多（此話似有矛盾）。 The maximum number of bytes to store in the output buffer. In order to guarantee success, this should be at least 1276 for a single frame, or for multiple frames, 1277*(end-begin). However, 1*(end-begin) plus the size of all packet data submitted to the repacketizer since the last call to opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, and possibly much smaller. 返回: 成功，輸出包總的大小，失敗，錯誤代碼。 The total size of the output packet on success, or an error code on failure. 返回值: OPUS_BAD_ARG （begin,end）是幀無效的位置(begin < 0, begin >= end, or end > opus_repacketizer_get_nb_frames()). [begin,end) was an invalid range of frames (begin < 0, begin >= end, or end > opus_repacketizer_get_nb_frames()). OPUS_BUFFER_TOO_SMALL 最大容量maxlen不足以包含整個輸出包。maxlen was insufficient to contain the complete output packet.

Opus Multistream API

Multistream API容許將多個Opus數據流組合成一個包，可以支持多達255通道。 The multistream API allows individual Opus streams to be combined into a single packet, enabling support for up to 255 channels.

類型定義

typedef struct OpusMSEncoder
OpusMSEncoder
複製代碼

Opus 多流編碼器狀態.

typedef struct OpusMSDecoder
OpusMSDecoder
複製代碼

Opus多留解碼器狀態.

多流編碼器函數

//得到OpusMSEncoder結構的大小.
opus_int32
opus_multistream_encoder_get_size (int streams, int coupled_streams)

//分配和初始化多流編碼器狀態。
OpusMSEncoder * opus_multistream_encoder_create (opus_int32 Fs, int channels, int streams, int coupled_streams, const unsigned char *mapping, int application, int *error)

//初始化之前分配的多流編碼器狀態。
int opus_multistream_encoder_init (OpusMSEncoder *st, opus_int32 Fs, int channels, int streams, int coupled_streams, const unsigned char *mapping, int application)

//編碼一個多流Opus幀。
int opus_multistream_encode (OpusMSEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

//從浮點型輸入編碼一個多流Opus幀。
int opus_multistream_encode_float (OpusMSEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)

//釋放經 opus_multistream_encoder_create ()分配過的OpusMSEncoder 。 
void opus_multistream_encoder_destroy (OpusMSEncoder *st)

//向一個多流Opus編碼器執行CTL 函數。
int opus_multistream_encoder_ctl (OpusMSEncoder *st, int request,...)
複製代碼

多流解碼器函數

得到OpusMSDecoder結構的大小.
opus_int32
opus_multistream_decoder_get_size (int streams, int coupled_streams)
//分配和初始化多流解碼器狀態。
OpusMSDecoder * opus_multistream_decoder_create (opus_int32 Fs, int channels, int streams, int coupled_streams, const unsigned char *mapping, int *error)
//初始化之前分配的多流編碼器狀態對象。
int opus_multistream_decoder_init (OpusMSDecoder *st, opus_int32 Fs, int channels, int streams, int coupled_streams, const unsigned char *mapping)
//解碼一個多流Opus包。
int opus_multistream_decode (OpusMSDecoder *st, const unsigned char *data, opus_int32 len, opus_int16 *pcm, int frame_size, int decode_fec)
//用浮點型輸出解碼一個多流Opus包。
int opus_multistream_decode_float (OpusMSDecoder *st, const unsigned char *data, opus_int32 len, float *pcm, int frame_size, int decode_fec)
//向一個多流Opus解碼器執行CTL 函數。 
int opus_multistream_decoder_ctl (OpusMSDecoder *st, int request,...)
//釋放經 opus_multistream_decoder_create ()分配過的OpusMSDecoder。 
void opus_multistream_decoder_destroy (OpusMSDecoder *st)

複製代碼

詳細描述

多流 API容許將多個Opus數據流組合成一個包，可以支持多達255通道。 The multistream API allows individual Opus streams to be combined into a single packet, enabling support for up to 255 channels. 不象一個基本的Opus流，在解碼器能成功解釋編碼器生成的包內的數據前，編碼器和解碼器必須就通道配置協商一致。一些基本的信息，好比包時長，能夠不須要特別的協商就能夠計算得到。 Unlike an elementary Opus stream, the encoder and decoder must negotiate the channel configuration before the decoder can successfully interpret the data in the packets produced by the encoder. Some basic information, such as packet duration, can be computed without any special negotiation. 多流Opus包的格式是定義在Ogg封裝的規格，也是基於RFC 6716附錄B所闡述的自限定Opus框架。標準的Opus包正好是多流Opus包的退化版本，能夠用對流API進行編碼和解碼，只要在初始化編碼器和解碼器時將流數量設置爲1. The format for multistream Opus packets is defined in the Ogg encapsulation specification and is based on the self-delimited Opus framing described in Appendix B of RFC 6716. Normal Opus packets are just a degenerate case of multistream Opus packets, and can be encoded or decoded with the multistream API by setting streams to 1 when initializing the encoder or decoder. 多流Opus數據流能包含最多255個基本的Opus流，這些既能夠是「組隊的」也能夠是「非組隊的」，代表解碼器被配置來分別用1或2個通道來解碼它們。這些流是有序的，以便全部組隊的流起初就能出現（彷佛不夠恰當）。 Multistream Opus streams can contain up to 255 elementary Opus streams. These may be either "uncoupled" or "coupled", indicating that the decoder is configured to decode them to either 1 or 2 channels, respectively. The streams are ordered so that all coupled streams appear at the beginning. 一張映射表用來定義哪一個解碼通道i應被用於哪一個輸入/輸出(I/O)通道j。這張表典型地做爲一個無符號字符型陣列。讓i = mapping[j] 也就是I/O通道j的索引。若是i< 2coupled_streams,那麼i若爲偶數，I/O 通道 j被按照數據流的左聲道進行編碼；若i爲奇數，I/O 通道 j被按照數據流的右聲道進行編碼。其餘狀況下，I/O 通道 j被按照數據流的單聲道編碼(i - coupled_streams),除非它有特殊的值255，在這種狀況下它將被從編碼中完全刪掉（解碼器將其做爲靜音重建）。i的每一個值不是特殊值255就是小於streams + coupled_streams。 A mapping table defines which decoded channel i should be used for each input/output (I/O) channel j. This table is typically provided as an unsigned char array. Let i = mapping[j] be the index for I/O channel j. If i < 2coupled_streams, then I/O channel j is encoded as the left channel of stream (i/2) if i is even, or as the right channel of stream (i/2) if i is odd. Otherwise, I/O channel j is encoded as mono in stream (i - coupled_streams), unless it has the special value 255, in which case it is omitted from the encoding entirely (the decoder will reproduce it as silence). Each value i must either be the special value 255 or be less than streams + coupled_streams. 必須說明，編碼器的輸出通道應使用Vorbis（免費音樂格式）的通道規則。解碼器可能但願應用一個附加的排列以映射用於實現不一樣輸出通道規則的編碼器（例如用於WAV規則的輸出）。 The output channels specified by the encoder should use the Vorbis channel ordering. A decoder may wish to apply an additional permutation to the mapping the encoder used to achieve a different output channel order (e.g. for outputing in WAV order). 多流包包含對應每一個流的各Opus包，在單一多流包內的全部Opus包必須有相同的時長。所以，一個多流包的時長能夠從位於包開始位置的第一個流的TOC序列提取，就象一個基本的Opus流： Each multistream packet contains an Opus psacket for each stream, and all of the Opus packets in a single multistream packet must have the same duration. Therefore the duration of a multistream packet can be extracted from the TOC sequence of the first stream, which is located at the beginning of the packet, just like an elementary Opus stream:

int nb_samples;
int nb_frames;
nb_frames = opus_packet_get_nb_frames(data, len);
if (nb_frames < 1)
    return nb_frames;
nb_samples = opus_packet_get_samples_per_frame(data, 48000) * nb_frames;
複製代碼

通常的編碼和解碼過程執行徹底相同的標準Opus Encoder 和 Opus Decoder API。如何使用相應的多流函數能夠查閱它們的說明文檔。 The general encoding and decoding process proceeds exactly the same as in the normal Opus Encoder and Opus Decoder APIs. See their documentation for an overview of how to use the corresponding multistream functions.

類型定義文檔

typedef struct OpusMSDecoder OpusMSDecoder
複製代碼

Opus多流解碼器狀態。 Opus multistream decoder state. 這包含了一個Opus多流解碼器的完整狀態。它是位置獨立的，而且能夠自由複製。 This contains the complete state of a multistream Opus decoder. It is position independent and can be freely copied. 參見: opus_multistream_decoder_create opus_multistream_decoder_init

typedef struct OpusMSEncoder OpusMSEncoder
複製代碼

Opus多流編碼器狀態。 Opus multistream encoder state. 這包含了一個Opus多流編碼器的完整狀態。它是位置獨立的，而且能夠自由複製。 This contains the complete state of a multistream Opus encoder. It is position independent and can be freely copied. 參見: opus_multistream_encoder_create opus_multistream_encoder_init

函數文檔

int opus_multistream_decode     (   OpusMSDecoder *     st,
        const unsigned char *   data,
        opus_int32      len,
        opus_int16 *    pcm,
        int     frame_size,
        int     decode_fec 
    )   
複製代碼

解碼一個多流Opus包。 Decode a multistream Opus packet. 參數:

  • st OpusMSDecoder*: Opus多流解碼器狀態。Multistream decoder state.
  • [in] data const unsigned char*:輸入負載.對包丟失使用一個空指針來表示。 Input payload. Use a NULL pointer to indicate packet loss.
  • len opus_int32: 在輸入負載中的字節數。Number of bytes in payload.
  • [out] pcm opus_int16*:使用交叉樣本的輸出信號。必須有容納frame_sizechannels樣本數的空間。Output signal, with interleaved samples. This must contain room for frame_sizechannels samples.
  • frame_size int: 在PCM可用空間中每通道的樣本數。若是小於最大包的時長（120毫秒，4848kHz5760個），這個函數將不能解碼一些包。若是是PLC (data==NULL) 或 FEC (decode_fec=1)的狀況，那麼frame_size必須正好是丟失音頻的時長，不然解碼器沒法在解碼下一個包時進入優化狀態。對於PLC 和 FEC 的狀況，frame_size必須是2.5毫秒的倍數。The number of samples per channel of available space in pcm. If this is less than the maximum packet duration (120 ms; 5760 for 48kHz), this function will not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), then frame_size needs to be exactly the duration of audio that is missing, otherwise the decoder will not be in the optimal state to decode the next incoming packet. For the PLC and FEC cases, frame_size must be a multiple of 2.5 ms.
  • decode_fec int: 對於請求任何帶內前向錯誤糾正數據進行解碼的狀態標誌 (0 or 1) 。若是沒有這樣的數據可用，幀在解碼時被認爲已經丟失。 Flag (0 or 1) to request that any in-band forward error correction data be decoded. If no such data is available, the frame is decoded as if it were lost. 返回: 成功，解碼樣本的數量，失敗，負的錯誤代碼。Number of samples decoded on success or a negative error code (see Error codes) on failure.
int opus_multistream_decode_float   (   OpusMSDecoder *     st,
        const unsigned char *   data,
        opus_int32      len,
        float *     pcm,
        int     frame_size,
        int     decode_fec 
    ) 
複製代碼

用浮點輸出格式解碼一個多流Opus包。 Decode a multistream Opus packet with floating point output. 參數:

  • st OpusMSDecoder*: Opus多流解碼器狀態。Multistream decoder state.
  • [in] data const unsigned char*::輸入負載.對包丟失使用一個空指針來表示。 Input payload. Use a NULL pointer to indicate packet loss.
  • len opus_int32: 在輸入負載中的字節數。 Number of bytes in payload.
  • [out] pcm opus_int16*:使用交叉樣本的輸出信號。必須有容納frame_sizechannels樣本數的空間。Output signal, with interleaved samples. This must contain room for frame_sizechannels samples.
  • frame_size int: 在PCM可用空間中每通道的樣本數。若是小於最大包的時長（120毫秒，4848kHz5760個），這個函數將不能解碼一些包。若是是PLC (data==NULL) 或 FEC (decode_fec=1)的狀況，那麼frame_size必須正好是丟失音頻的時長，不然解碼器沒法在解碼下一個包時進入優化狀態。對於PLC 和 FEC 的狀況，frame_size必須是2.5毫秒的倍數。The number of samples per channel of available space in pcm. If this is less than the maximum packet duration (120 ms; 5760 for 48kHz), this function will not be capable of decoding some packets. In the case of PLC (data==NULL) or FEC (decode_fec=1), then frame_size needs to be exactly the duration of audio that is missing, otherwise the decoder will not be in the optimal state to decode the next incoming packet. For the PLC and FEC cases, frame_size must be a multiple of 2.5 ms.
  • decode_fec int: 對於請求任何帶內前向錯誤糾正數據進行解碼的狀態標誌 (0 or 1) 。若是沒有這樣的數據可用，幀在解碼時被認爲已經丟失。 Flag (0 or 1) to request that any in-band forward error correction data be decoded. If no such data is available, the frame is decoded as if it were lost. 返回: 成功，解碼樣本的數量，失敗，負的錯誤代碼。Number of samples decoded on success or a negative error code (see Error codes) on failure.
OpusMSDecoder* opus_multistream_decoder_create  (   opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int *   error 
    ) 
複製代碼

分配和初始化多流解碼器狀態。 Allocates and initializes a multistream decoder state. 當結束時要調用opus_multistream_decoder_destroy()來釋放這個對象。 Call opus_multistream_decoder_destroy() to release this object when finished. 參數:

  • Fs opus_int32: 解碼的採樣率 (Hz). 必須是 8000, 12000, 16000, 24000, 或 48000.Sampling rate to decode at (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
  • channels int: 用於解碼的通道數，這個數最大是255，可能與編碼通道(streams + coupled_streams)的數量不一樣。Number of channels to output. This must be at most 255. It may be different from the number of coded channels (streams + coupled_streams).
  • streams int:編碼進輸入的數據流的總數，必須不能超過255. The total number of streams coded in the input. This must be no more than 255.
  • coupled_streams int: 要解碼爲組對流（2通道）的數據流的數量。必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的數量必須不大於255.Number of streams to decode as coupled (2 channel) streams. This must be no larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255.
  • [in] mapping const unsigned char[channels]:被編碼通道與輸出通道的映射關係表。Mapping from coded channels to output channels, as described in Opus Multistream API.
  • [out] error int *:成功，返回OPUS_OK，失敗，返回錯誤代碼。 Returns OPUS_OK on success, or an error code (see Error codes) on failure.
int opus_multistream_decoder_ctl    (   OpusMSDecoder *     st,
        int     request,
            ... 
    )      
複製代碼

向一個Opus多流解碼器執行一個 CTL 函數. Perform a CTL function on a multistream Opus decoder. 通常其請求和後續的參數是由一個提供便利的宏來產生的。 Generally the request and subsequent arguments are generated by a convenience macro. 參數:

  • st OpusMSDecoder*: 多流解碼器狀態。Multistream decoder state.
  • Request : 這個及全部其餘剩餘參數應被1個在Generic CTLs，Decoder相關的CTLs, 或Multistream 具體的編碼器和解碼器CTLs所提供便利的宏來替代。This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs, Decoder related CTLs, or Multistream specific encoder and decoder CTLs. 參見: Generic CTLs Decoder related CTLs Multistream specific encoder and decoder CTLs
void opus_multistream_decoder_destroy ( OpusMSDecoder * st ) 
複製代碼

釋放一個根據opus_ multistream_decoder_create()已分配的OpusMSDecoder對象. Frees an OpusMSDecoder allocated by opus_multistream_decoder_create(). 參數:

  • st OpusMSDecoder: 用於釋放的多流解碼器狀態。Multistream decoder state to be freed.
opus_int32 opus_multistream_decoder_get_size ( int streams,
int coupled_streams
)
複製代碼

得到 OpusMSDecoder結構的大小。 Gets the size of an OpusMSDecoder structure. 參數:

  • streams int: 編碼進輸入的數據流的總數，必須不能超過255. The total number of streams coded in the input. This must be no more than 255.
  • coupled_streams int: 要解碼爲組對流（2通道）的數據流的數量。必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的數量必須不大於255.Number streams to decode as coupled (2 channel) streams. This must be no larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255. 返回: 成功，字節數，失敗，負的錯誤代碼。 The size in bytes on success, or a negative error code (see Error codes) on error.
int opus_multistream_decoder_init   (   OpusMSDecoder *     st,
        opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping 
    ) 
複製代碼

初始化一個之前分配過的解碼器狀對象。 Intialize a previously allocated decoder state object. st所指向的內存必須至少是opus_multistream_decoder_get_size()返回的大小，是給不用系統自動分配內存，而要準備用本身的分配器的應用程序用的。爲重設之前初始化的狀態，使用OPUS_RESET_STATE CTL。 The memory pointed to by st must be at least the size returned by opus_multistream_decoder_get_size(). This is intended for applications which use their own allocator instead of malloc. To reset a previously initialized state, use the OPUS_RESET_STATE CTL. 參見: opus_multistream_decoder_create opus_multistream_deocder_get_size 參數:

  • st OpusMSEncoder*:準備初始化的多流解碼器狀態。Multistream encoder state to initialize.
  • Fs opus_int32: 解碼的採樣率 (Hz). 必須是 8000, 12000, 16000, 24000, 或 48000.Sampling rate to decode at (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
  • channels int: 用於輸出的通道數，這個數最大是255，可能與編碼通道(streams + coupled_streams)的數量不一樣。Number of channels to output. This must be at most 255. It may be different from the number of coded channels (streams + coupled_streams).
  • streams int: 編碼進輸入的數據流的總數，必須不能超過255.The total number of streams coded in the input. This must be no more than 255.
  • coupled_streams int: 要解碼爲組對流（2通道）的數據流的數量。必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的數量必須不大於255.Number of streams to decode as coupled (2 channel) streams. This must be no larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255.
  • [in] mapping const unsigned char[channels]: 被編碼通道與輸出通道的映射關係表。Mapping from coded channels to output channels, as described in Opus Multistream API.

返回: 成功，返回OPUS_OK，失敗，返回錯誤代碼。 OPUS_OK on success, or an error code (see Error codes) on failure.

int opus_multistream_encode     (   OpusMSEncoder *     st,
        const opus_int16 *      pcm,
        int     frame_size,
        unsigned char *     data,
        opus_int32      max_data_bytes 
    )   
複製代碼

對一個多流Opus幀進行編碼。 Encodes a multistream Opus frame. 參數:

  • st OpusMSEncoder*:多流編碼器狀態。Multistream encoder state.
  • [in] pcm const opus_int16*:使用交叉樣本的輸入信號。必須有容納frame_sizechannels樣本數的空間。The input signal as interleaved samples. This must contain frame_sizechannels samples.
  • frame_size int: 輸入信號的每通道使用交叉樣本的輸出信號。必須有容納frame_size*channels樣本數的空間。數. 這必須是編碼器採樣率的Opus幀大小。好比，48 kHz 下容許值有120, 240, 480, 960, 1920, 和 2880。少於10毫秒的採樣（48 kHz 有480個樣本），將阻止編碼器使用LPC或混合模式。Number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
  • [out] data unsigned char*:輸出負載。必須包含至少max_data_bytes 的容量。 Output payload. This must contain storage for at least max_data_bytes.
  • [in] max_data_bytes opus_int32: 爲輸出負載所分配的內存大小。能夠用於限制固定比特率的最大上限，但不能用做惟一的比特率限制，能夠用OPUS_SET_BITRATE來控制比特率。Size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use OPUS_SET_BITRATE to control the bitrate. 返回: 成功，是被編碼包的長度（字節數），失敗，一個負的錯誤代碼。 The length of the encoded packet (in bytes) on success or a negative error code (see Error codes) on failure.
int opus_multistream_encode_float   (   OpusMSEncoder *     st,
        const float *   pcm,
        int     frame_size,
        unsigned char *     data,
        opus_int32      max_data_bytes 
    )   
複製代碼

根據浮點輸入對一個 Opus幀進行編碼. Encodes a multistream Opus frame from floating point input. 參數:

  • st OpusMSEncoder*:多流編碼器狀態。Multistream encoder state.
  • [in] pcm const float*:交叉樣本的輸入信號，正常範圍在+/-1.0之間. 超過該範圍的採樣也是支持的，但它將被解碼器用整型API截取，而且只能在知道遠端支持擴展的動態範圍的狀況下使用。必須有容納frame_sizechannels樣本數的空間。The input signal as interleaved samples with a normal range of +/-1.0. Samples with a range beyond +/-1.0 are supported but will be clipped by decoders using the integer API and should only be used if it is known that the far end supports extended dynamic range. This must contain frame_sizechannels samples.
  • frame_size int: 輸入信號的每通道使用交叉樣本的輸出信號。必須有容納frame_size*channels樣本數的空間。數. 這必須是編碼器採樣率的Opus幀大小。好比，48 kHz 下容許值有120, 240, 480, 960, 1920, 和 2880。少於10毫秒的採樣（48 kHz 有480個樣本），將阻止編碼器使用LPC或混合模式。Number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
  • [out] data unsigned char*:輸出負載。必須包含至少max_data_bytes 的容量。Output payload. This must contain storage for at least max_data_bytes.
  • [in] max_data_bytes opus_int32: 爲輸出負載所分配的內存大小。能夠用於限制固定比特率的最大上限，但不能用做惟一的比特率限制，能夠用OPUS_SET_BITRATE來控制比特率。Size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use OPUS_SET_BITRATE to control the bitrate.

返回: 成功，是被編碼包的長度（字節數），失敗，一個負的錯誤代碼。 The length of the encoded packet (in bytes) on success or a negative error code (see Error codes) on failure.

OpusMSEncoder* opus_multistream_encoder_create  (   opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int     application,
        int *   error 
    )   
複製代碼

分配和初始化多流編碼器狀態。 Allocates and initializes a multistream encoder state. 當結束時要調用opus_multistream_encoder_destroy()來釋放這個對象。 Call opus_multistream_encoder_destroy() to release this object when finished. 參數:

  • Fs opus_int32: 解碼的採樣率 (Hz). 必須是 8000, 12000, 16000, 24000, 或 48000.Sampling rate of the input signal (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
  • channels int: 輸入信號中的通道數，這個數最大是255，可能比編碼通道(streams + coupled_streams)的數量更大。Number of channels in the input signal. This must be at most 255. It may be greater than the number of coded channels (streams + coupled_streams).
  • streams int從:輸入要編碼的數據流的總數，必須不能超過通道數. The total number of streams to encode from the input. This must be no more than the number of channels.
  • coupled_streams int: 要編碼的組對（2通道）數據流的總數，必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的總數必須不超過輸入通道的數量.Number of coupled (2 channel) streams to encode. This must be no larger than the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than the number of input channels.
  • [in] mapping const unsigned char[channels]: 被編碼通道與輸入通道的映射關係表。做爲一個額外的限制，多流編碼器不容許對一個通道不可用的組對數據流進行編碼，由於這個想法太爛了。Mapping from encoded channels to input channels, as described in Opus Multistream API. As an extra constraint, the multistream encoder does not allow encoding coupled streams for which one channel is unused since this is never a good idea.
  • application int: 目標編碼器應用程序，必須是如下之一：The target encoder application. This must be one of the following:
    • OPUS_APPLICATION_VOIP 改進語音清晰度的處理信號。Process signal for improved speech intelligibility.
    • OPUS_APPLICATION_AUDIO 偏好與原始輸入的正確性。Favor faithfulness to the original input.
    • OPUS_APPLICATION_RESTRICTED_LOWDELAY 經過使特定操做模式失效以使編碼延遲儘量小。Configure the minimum possible coding delay by disabling certain modes of operation.
  • [out] error int *:成功，返回OPUS_OK，失敗，返回錯誤代碼。Returns OPUS_OK on success, or an error code (see Error codes) on failure.
int opus_multistream_encoder_ctl    (   OpusMSEncoder *     st,
        int     request,
            ... 
    ) 
複製代碼

向一個Opus多流編碼器執行一個 CTL 函數. Perform a CTL function on a multistream Opus encoder. 通常其請求和後續的參數是由一個提供便利的宏來產生的。 Generally the request and subsequent arguments are generated by a convenience macro. 參數: st OpusMSEncoder*: 多流編碼器狀態。Multistream encoder state. request ：這個及全部其餘剩餘參數應被1個在Generic CTLs，Encoder相關的CTLs, 或Multistream 具體的編碼器和解碼器CTLs所提供便利的宏來替代。This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs, Encoder related CTLs, or Multistream specific encoder and decoder CTLs. 參見: Generic CTLs Encoder related CTLs Multistream specific encoder and decoder CTLs

void opus_multistream_encoder_destroy ( OpusMSEncoder * st ) 釋放一個根據opus_ multistream_encoder_create()已分配的OpusMSEncoder對象. Frees an OpusMSEncoder allocated by opus_multistream_encoder_create(). 參數:

  • st OpusMSEncoder*:用於釋放的多流編碼器狀態。 Multistream encoder state to be freed.
opus_int32 opus_multistream_encoder_get_size    (   int     streams,
        int     coupled_streams 
    )   
複製代碼

得到 OpusMSEncoder結構的大小。 Gets the size of an OpusMSEncoder structure. 參數:

  • streams int: 從輸入用於編碼的數據流的總數，必須不能超過255. The total number of streams to encode from the input. This must be no more than 255.
  • coupled_streams int: 要編碼的組對流（2通道）的數量。必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的數量必須不大於255.Number of coupled (2 channel) streams to encode. This must be no larger than the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than 255. 返回: 成功，字節數，失敗，負的錯誤代碼。 The size in bytes on success, or a negative error code (see Error codes) on error.
int opus_multistream_encoder_init   (   OpusMSEncoder *     st,
        opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int     application 
    )   
複製代碼

初始化一個之前分配過的編碼器狀對象。 Initialize a previously allocated multistream encoder state. st所指向的內存必須至少是opus_multistream_encoder_get_size()返回的大小，是給不用系統自動分配內存，而要準備用本身的分配器的應用程序用的。爲重設之前初始化的狀態，使用OPUS_RESET_STATE CTL。 The memory pointed to by st must be at least the size returned by opus_multistream_encoder_get_size(). This is intended for applications which use their own allocator instead of malloc. To reset a previously initialized state, use the OPUS_RESET_STATE CTL. 參見: opus_multistream_encoder_create opus_multistream_encoder_get_size 參數:

  • st OpusMSEncoder*:準備初始化的多流編碼器狀態。Multistream encoder state to initialize.
  • Fs opus_int32: 輸入信號的採樣率 (Hz). 必須是 8000, 12000, 16000, 24000, 或 48000.Sampling rate of the input signal (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
  • channels int: 輸入信號中的通道數，這個數最大是255，可能大於編碼通道(streams + coupled_streams)的數量。Number of channels in the input signal. This must be at most 255. It may be greater than the number of coded channels (streams + coupled_streams).
  • streams int: 從輸入要編碼的數據流的總數，必須不大於通道的數量. The total number of streams to encode from the input. This must be no more than the number of channels.
  • coupled_streams int: 要編碼的組對（2通道）數據流的總數，必須不大於數據流的總數。另外，編碼通道(streams + coupled_streams)的總數必須不超過輸入通道的數量.Number of coupled (2 channel) streams to encode. This must be no larger than the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than the number of input channels.
  • [in] mapping const unsigned char[channels]: 被編碼通道與輸入通道的映射關係表。做爲一個額外的限制，多流編碼器不容許對一個通道不可用的組對數據流進行編碼，由於這個想法太爛了。Mapping from encoded channels to input channels, as described in Opus Multistream API. As an extra constraint, the multistream encoder does not allow encoding coupled streams for which one channel is unused since this is never a good idea.
  • application int: 目標編碼器應用程序，必須是如下之一：The target encoder application. This must be one of the following: - OPUS_APPLICATION_VOIP 改進語音清晰度的處理信號。Process signal for improved speech intelligibility. - OPUS_APPLICATION_AUDIO 偏好與原始輸入的正確性。Favor faithfulness to the original input. - OPUS_APPLICATION_RESTRICTED_LOWDELAY 經過使特定操做模式失效以使編碼延遲儘量小。Configure the minimum possible coding delay by disabling certain modes of operation. 返回: 成功，返回OPUS_OK，失敗，返回錯誤代碼。 OPUS_OK on success, or an error code (see Error codes) on failure.

Opus library information functions

本節描述了Opus庫信息函數

函數

Converts an opus error code into a human readable string.

const char * opus_strerror (int error)
複製代碼

Gets the libopus version string.

const char * opus_get_version_string (void)
複製代碼

函數文檔

const char* opus_get_version_string ( void )
複製代碼

得到libopus的版本信息，用字符串表示。 Gets the libopus version string. 返回: 版本字符串。Version string

const char* opus_strerror ( int error )
複製代碼

將Opus錯誤代碼轉換爲人可讀的字符串。 Converts an opus error code into a human readable string. 參數:

  • [in] error int: 錯誤號。Error number 返回: 錯誤字符串。Error string

Opus Custom

Opus Custom是Opus規範和參考實現的可選部分，可用於使用與正常API不一樣的獨特API，而且支持非正常的幀大小。Opus Custom只用於一些很是特別的應用程序，這些應用程序須要處理與2.五、 五、10或20 ms不一樣的幀規格（因爲複雜度或其餘潛在緣由），互操做性就不那麼重要了。 Opus Custom is an optional part of the Opus specification and reference implementation which uses a distinct API from the regular API and supports frame sizes that are not normally supported. Use of Opus Custom is discouraged for all but very special applications for which a frame size different from 2.5, 5, 10, or 20 ms is needed (for either complexity or latency reasons) and where interoperability is less important.

類型定義

編碼器狀態Contains the state of an encoder.

typedef struct OpusCustomEncoder
OpusCustomEncoder
複製代碼

解碼器狀態State of the decoder.

typedef struct OpusCustomDecoder

複製代碼

包含用於建立編碼器的全部必要信息的模式The mode contains all the information necessary to create an encoder.

函數

OpusCustomMode *
opus_custom_mode_create (opus_int32 Fs, int frame_size, int *error)
複製代碼

建立新的模式結構。Creates a new mode struct.

void opus_custom_mode_destroy (OpusCustomMode *mode)
複製代碼

解構一個模式結構。Destroys a mode struct.

int opus_custom_encoder_get_size (const OpusCustomMode *mode, int channels)
複製代碼

得到OpusCustomEncoder 結構的大小。Gets the size of an OpusCustomEncoder structure.

OpusCustomEncoder * opus_custom_encoder_create (const OpusCustomMode *mode, int channels, int *error)
複製代碼

建立新的編碼器狀態。Creates a new encoder state.

int opus_custom_encoder_init (OpusCustomEncoder *st, const OpusCustomMode *mode, int channels)
複製代碼

初始化一個之前分配過的編碼器狀態，st所指向的內存必須是opus_custom_encoder_get_size 返回的大小。Initializes a previously allocated encoder state The memory pointed to by st must be the size returned by opus_custom_encoder_get_size.

void opus_custom_encoder_destroy (OpusCustomEncoder *st)
複製代碼

解構一個編碼器狀態。Destroys a an encoder state.

int opus_custom_encode_float (OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes)
複製代碼

給一個音頻幀進行編碼。Encodes a frame of audio.

int opus_custom_encode (OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes)
複製代碼

給一個音頻幀進行編碼。Encodes a frame of audio.

int opus_custom_encoder_ctl (OpusCustomEncoder *OPUS_RESTRICT st, int request,...)
複製代碼

爲一個Opus 定製編碼器執行一個CTL 函數。Perform a CTL function on an Opus custom encoder.

int opus_custom_decoder_get_size (const OpusCustomMode *mode, int channels)
複製代碼

得到一個OpusCustomDecoder 結構的大小。Gets the size of an OpusCustomDecoder structure.

OpusCustomDecoder * opus_custom_decoder_create (const OpusCustomMode *mode, int channels, int *error)
複製代碼

建立新的解碼器狀態。Creates a new decoder state.

int opus_custom_decoder_init (OpusCustomDecoder *st, const OpusCustomMode *mode, int channels)
複製代碼

初始化一個之前分配過的解碼器狀態，st所指向的內存必須是opus_custom_decoder_get_size 返回的大小。Initializes a previously allocated decoder state The memory pointed to by st must be the size returned by opus_custom_decoder_get_size.

void opus_custom_decoder_destroy (OpusCustomDecoder *st)
複製代碼

解構一個解碼器狀態。Destroys a an decoder state.

int opus_custom_decode_float (OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size)
複製代碼

使用浮點輸出解碼一個Opus定製幀。Decode an opus custom frame with floating point output.

int opus_custom_decode (OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size)
複製代碼

解碼一個Opus定製幀。Decode an opus custom frame.

int opus_custom_decoder_ctl (OpusCustomDecoder *OPUS_RESTRICT st, int request,...)
複製代碼

爲一個Opus 定製解碼器執行一個CTL 函數。Perform a CTL function on an Opus custom decoder.

詳細描述

Opus Custom是Opus規範和參考實現的可選部分，可用於使用與正常API不一樣的獨特API，而且支持非正常的幀大小。Opus Custom只用於一些很是特別的應用程序，這些應用程序須要處理與2.五、 五、10或20 ms不一樣的幀規格（因爲複雜度或其餘潛在緣由），互操做性就不那麼重要了。 Opus Custom is an optional part of the Opus specification and reference implementation which uses a distinct API from the regular API and supports frame sizes that are not normally supported. Use of Opus Custom is discouraged for all but very special applications for which a frame size different from 2.5, 5, 10, or 20 ms is needed (for either complexity or latency reasons) and where interoperability is less important. 除了互操做性的限制外，Opus定製的使用還會致使大部分的編解碼器功能不能使用，而且一般會在一個給定的比特率上下降可達到的質量。正常狀況下當應用程序須要從編解碼器得到一個不一樣的幀大小，它應當創建緩衝區以容納幀所需空間，但這會增長一小點延遲，而這一小點延遲對一些很是低延遲應用程序來講是重要的。一些傳輸協議（特別是恆定流量的RF傳輸協議）可能也能夠對特殊時長幀的處理達到最佳。 In addition to the interoperiability limitations the use of Opus custom disables a substantial chunk of the codec and generally lowers the quality available at a given bitrate. Normally when an application needs a different frame size from the codec it should buffer to match the sizes but this adds a small amount of delay which may be important in some very low latency applications. Some transports (especially constant rate RF transports) may also work best with frames of particular durations. 若是在編譯期激活，libopus僅支持定製模式。 Libopus only supports custom modes if they are enabled at compile time. Opus定製API與普通API類似，但opus_encoder_create和opus_decoder_create的調用一個附加的模式參數，這個模式參數是經過調用opus_custom_mode_create產生的結構。編碼器和解碼器必須達成一個模式，使用相同的採樣率(fs)和幀規格(frame size),這些參數必須或者被示意在波段外，或固定在一個特別的實現過程當中。 The Opus Custom API is similar to the regular API but the opus_encoder_create and opus_decoder_create calls take an additional mode parameter which is a structure produced by a call to opus_custom_mode_create. Both the encoder and decoder must create a mode using the same sample rate (fs) and frame size (frame size) so these parameters must either be signaled out of band or fixed in a particular implementation. 與普通的相似，Opus定製模式支持飛行幀大小轉換，不過這些可用的大小取決於使用中的特殊幀大小。對於單一數據流的一些開頭的幀的大小，飛行幀大小是可用的。 Similar to regular Opus the custom modes support on the fly frame size switching, but the sizes available depend on the particular frame size in use. For some initial frame sizes on a single on the fly size is available.

類型定義文檔

typedef struct OpusCustomDecoder OpusCustomDecoder
複製代碼

解碼器狀態。State of the decoder. 對於每一個數據流，須要一個解碼器狀態。解碼器狀態在數據流的開頭一次性初始化。對於每一個幀不要創新初始化。 One decoder state is needed for each stream. It is initialized once at the beginning of the stream. Do not re-initialize the state for every frame. Decoder state

typedef struct OpusCustomEncoder OpusCustomEncoder
複製代碼

編碼器狀態。Contains the state of an encoder. 對於每一個數據流，須要一個編碼器狀態。編碼器狀態在數據流的開頭一次性初始化。對於每一個幀不要創新初始化。 One encoder state is needed for each stream. It is initialized once at the beginning of the stream. Do not re-initialize the state for every frame. Encoder state

typedef struct OpusCustomMode OpusCustomMode
複製代碼

包含用於建立編碼器的全部必要信息的模式 The mode contains all the information necessary to create an encoder. 編碼器和解碼器須要用徹底相同的模式來初始化，不然輸出將會被破壞。 Both the encoder and decoder need to be initialized with exactly the same mode, otherwise the output will be corrupted. Mode configuration

函數文檔

int opus_custom_decode  (   OpusCustomDecoder *     st,
        const unsigned char *   data,
        int     len,
        opus_int16 *    pcm,
        int     frame_size 
    ) 
複製代碼

解碼一個Opus定製幀。 Decode an opus custom frame. 參數:

  • [in] st OpusCustomDecoder*:解碼器狀態Decoder state
  • [in] data char*:輸入負載.對包丟失使用一個空指針來表示。 Input payload. Use a NULL pointer to indicate packet loss
  • [in] len int: 在輸入負載中的字節數Number of bytes in payload
  • [out] pcm opus_int16*:輸出信號（若是是2通道有交叉）。長度等於frame_sizechannelssizeof(opus_int16)。Output signal (interleaved if 2 channels). length is frame_sizechannelssizeof(opus_int16)
  • [in] frame_size: 在*pcm的可用空間每通道的樣本數。Number of samples per channel of available space in *pcm. 返回: 解碼樣本的數量，或錯誤代碼。Number of decoded samples or Error codes
int opus_custom_decode_float    (   OpusCustomDecoder *     st,
        const unsigned char *   data,
        int     len,
        float *     pcm,
        int     frame_size 
    )
複製代碼

用浮點輸出解碼一個Opus定製幀。 Decode an opus custom frame with floating point output. 參數:

  • [in] st OpusCustomDecoder*:解碼器狀態。 Decoder state
  • [in] data char*:輸入負載.對包丟失使用一個空指針來表示。 Input payload. Use a NULL pointer to indicate packet loss
  • [in] len int: 在輸入負載中的字節數Number of bytes in payload
  • [out] pcm float*:輸出信號（若是是2通道有交叉）。長度等於frame_sizechannelssizeof(float)。Output signal (interleaved if 2 channels). length is frame_sizechannelssizeof(float)
  • [in] frame_size: 在*pcm的可用空間每通道的樣本數。Number of samples per channel of available space in *pcm. 返回: 解碼樣本的數量，或錯誤代碼。Number of decoded samples or Error codes
OpusCustomDecoder* opus_custom_decoder_create   (   const OpusCustomMode *      mode,
        int     channels,
        int *   error 
    )
複製代碼

建立新的解碼器狀態。 Creates a new decoder state. 每一個數據流須要有它本身的解碼器狀態（不能與同時發生的數據流共享）。 Each stream needs its own decoder state (can't be shared across simultaneous streams). 參數:

  • [in] mode OpusCustomMode: 包含關於數據流的特徵的全部信息（必須與用於編碼器的相同）。Contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
  • [in] channels int: 通道數。Number of channels
  • [out] error int*: 返回錯誤代碼。Returns an error code 返回: 新建立的解碼器狀態。Newly created decoder state.
int opus_custom_decoder_ctl     (   OpusCustomDecoder *OPUS_RESTRICT    st,
        int     request,
            ... 
    )   
複製代碼

爲Opus定製解碼器執行一個CTL函數。 Perform a CTL function on an Opus custom decoder. 通常其請求和後續的參數是由一個提供便利的宏來產生的。 Generally the request and subsequent arguments are generated by a convenience macro. 參見: Generic CTLs

void opus_custom_decoder_destroy ( OpusCustomDecoder * st ) 解構一個解碼器狀態。Destroys a an decoder state.
複製代碼

參數:

  • [in] st OpusCustomDecoder*:將要釋放的狀態。 State to be freed.
int opus_custom_decoder_get_size    (   const OpusCustomMode *      mode,
        int     channels 
    )   
複製代碼

得到OpusCustomDecoder結構的大小。 Gets the size of an OpusCustomDecoder structure. 參數:

  • [in] mode OpusCustomMode *: 模式配置。Mode configuration
  • [in] channels int: 通道數。Number of channels 返回: 大小。size
int opus_custom_decoder_init    (   OpusCustomDecoder *     st,
        const OpusCustomMode *      mode,
        int     channels 
    )
複製代碼

初始化一個之前分配過的解碼器狀態.st所指向的內存 必須是opus_ custom_ decoder_get_size()返回的大小.在這裏，應用程序不要用系統自動分配內存，而要準備用本身的分配器。 Initializes a previously allocated decoder state The memory pointed to by st must be the size retured by opus_custom_decoder_get_size. This is intended for applications which use their own allocator instead of malloc. 參見: opus_custom_decoder_create(),opus_custom_decoder_get_size(),爲重設一個之前初始化的狀態，使用OPUS_RESET_STATE CTL.To reset a previously initialized state use the OPUS_RESET_STATE CTL. 參數:

  • [in] st OpusCustomDecoder*:解碼器狀態.Decoder state
  • [in] mode OpusCustomMode *:包含關於數據流的特徵的全部信息（必須與用於編碼器的相同）。Contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
  • [in] channels int: 通道數。Number of channels 返回: 成功，OPUS_OK ，失敗，錯誤代碼。OPUS_OK Success or Error codes
int opus_custom_encode  (   OpusCustomEncoder *     st,
        const opus_int16 *      pcm,
        int     frame_size,
        unsigned char *     compressed,
        int     maxCompressedBytes 
    )
複製代碼

編碼一個音頻幀。 Encodes a frame of audio. 參數:

  • [in] st OpusCustomEncoder*:編碼器狀態Encoder state
  • [in] pcm opus_int16*: 16位格式信號的PCM音頻（本來的字節存儲次序）。每通道必須剛好有frame_size 個樣本。PCM audio in signed 16-bit format (native endian). There must be exactly frame_size samples per channel.
  • [in] frame_size int: 輸入信號每幀的樣本數。Number of samples per frame of input signal
  • [out] compressed char *: 壓縮數據被寫入到這。可能不是PCM格式，必須具備maxCompressedBytes 的長度。The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
  • [in] maxCompressedBytes int: 用於壓縮幀的字節最大數（從一幀到另外一幀時能夠改變）。Maximum number of bytes to use for compressing the frame (can change from one frame to another) 返回: 寫入到「壓縮區」的字節數。若是是負的，表示是一個錯誤(見錯誤代碼)。將該長度以某種方式傳遞給解碼器很重要，如沒有這麼作，沒法進行解碼。Number of bytes written to "compressed". If negative, an error has occurred (see error codes). It is IMPORTANT that the length returned be somehow transmitted to the decoder. Otherwise, no decoding is possible.
int opus_custom_encode_float    (   OpusCustomEncoder *     st,
        const float *   pcm,
        int     frame_size,
        unsigned char *     compressed,
        int     maxCompressedBytes 
    )   
複製代碼

編碼一個音頻幀。 Encodes a frame of audio. 參數:

  • [in] st OpusCustomEncoder*: 編碼器狀態Encoder state
  • [in] pcm float*: 浮點格式的PCM音頻數據，正常範圍在+/-1.0之間. 超過該範圍的採樣也是支持的，但它將被解碼器用整型API截取，而且只能在知道遠端支持擴展的動態範圍的狀況下使用。每通道必須有準確的frame_size樣本。PCM audio in float format, with a normal range of +/-1.0. Samples with a range beyond +/-1.0 are supported but will be clipped by decoders using the integer API and should only be used if it is known that the far end supports extended dynamic range. There must be exactly frame_size samples per channel.
  • [in] frame_size int: 輸入信號每幀的樣本數。Number of samples per frame of input signal
  • [out] compressed char *:壓縮數據被寫入到這。可能不是PCM格式，必須具備maxCompressedBytes 的長度。 The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
  • [in] maxCompressedBytes int: 用於壓縮幀的字節最大數（從一幀到另外一幀時能夠改變）。 Maximum number of bytes to use for compressing the frame (can change from one frame to another) 返回: 寫入到「壓縮區」的字節數。若是是負的，表示是一個錯誤(見錯誤代碼)。將該長度以某種方式傳遞給解碼器很重要，如沒有這麼作，沒法進行解碼。 Number of bytes written to "compressed". If negative, an error has occurred (see error codes). It is IMPORTANT that the length returned be somehow transmitted to the decoder. Otherwise, no decoding is possible.
OpusCustomEncoder* opus_custom_encoder_create   (   const OpusCustomMode *      mode,
        int     channels,
        int *   error 
    )
複製代碼

建立新的編碼器狀態。 Creates a new encoder state. 每一個數據流須要有它本身的編碼器狀態（不能與同時發生的數據流共享）。 Each stream needs its own encoder state (can't be shared across simultaneous streams). 參數:

  • [in] mode OpusCustomMode*:包含關於數據流的特徵的全部信息（必須與用於解碼器的相同）。 Contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
  • [in] channels int: 通道數。Number of channels
  • [out] error int*:返回錯誤代碼。Returns an error code 返回: 新建立的編碼器狀態。Newly created encoder state.
int opus_custom_encoder_ctl     (   OpusCustomEncoder *OPUS_RESTRICT    st,
        int     request,
            ... 
    )
複製代碼

爲Opus定製編碼器執行一個CTL函數。 Perform a CTL function on an Opus custom encoder. 通常其請求和後續的參數是由一個提供便利的宏來產生的。 Generally the request and subsequent arguments are generated by a convenience macro.

參見: Encoder related CTLs

void opus_custom_encoder_destroy ( OpusCustomEncoder * st ) 解構一個編碼器狀態。Destroys a an encoder state.
複製代碼

參數:

  • [in] st OpusCustomEncoder*:須要釋放的狀態。State to be freed.
int opus_custom_encoder_get_size    (   const OpusCustomMode *      mode,
        int     channels 
    )
複製代碼

得到OpusCustomEncoder結構的大小。 Gets the size of an OpusCustomEncoder structure. 參數:

  • [in] mode OpusCustomMode *:模式配置。Mode configuration
  • [in] channels int: 通道數。 Number of channels 返回: 大小。size
int opus_custom_encoder_init    (   OpusCustomEncoder *     st,
        const OpusCustomMode *      mode,
        int     channels 
    )
複製代碼

初始化一個之前分配過的編碼器狀態.st所指向的內存 必須是opus_ custom_encoder_get_size()返回的大小.在這裏，應用程序不要用系統自動分配內存，而要準備用本身的分配器。 Initializes a previously allocated encoder state The memory pointed to by st must be the size returned by opus_custom_encoder_get_size. This is intended for applications which use their own allocator instead of malloc. 參見: opus_custom_encoder_create(),opus_custom_encoder_get_size(),爲重設一個之前初始化的狀態，使用OPUS_RESET_STATE CTL. To reset a previously initialized state use the OPUS_RESET_STATE CTL. 參數:

  • [in] st OpusCustomEncoder*: 編碼器狀態.Encoder state
  • [in] mode OpusCustomMode *:包含關於數據流的特徵的全部信息（必須與用於解碼器的相同）。Contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
  • [in] channels int: 通道數。Number of channels 返回: 成功，OPUS_OK ，失敗，錯誤代碼。OPUS_OK Success or Error codes
OpusCustomMode* opus_custom_mode_create     (   opus_int32      Fs,
        int     frame_size,
        int *   error 
    )
複製代碼

建立新的模式結構。 Creates a new mode struct. 這個模式結構將傳遞給編碼器和解碼器使用。在使用它的編碼器和解碼器被解構前，該模式結構必須不能被解構。 This will be passed to an encoder or decoder. The mode MUST NOT BE DESTROYED until the encoders and decoders that use it are destroyed as well. 參數:

  • [in] Fs int: 採用率（8000至96000Hz）Sampling rate (8000 to 96000 Hz)
  • [in] frame_size int: 編碼給每一個包（每通道）的採樣數（64－1024，因子分解必須包括0或二、三、5，不能是其餘素數）。Number of samples (per channel) to encode in each packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes)
  • [out] error int*: 返回的錯誤代碼（如爲Null，表示沒有錯誤）。Returned error code (if NULL, no error will be returned) 返回: 一個新建立的模式對象。A newly created mode
void opus_custom_mode_destroy ( OpusCustomMode * mode )
複製代碼

解構一個模式結構。 Destroys a mode struct. 注意，須在全部使用這個模式對象的編碼器和解碼器解構後才能調用這個函數。 Only call this after all encoders and decoders using this mode are destroyed as well. 參數:

  • [in] mode OpusCustomMode*: 將要釋放的模式結構。Mode to be freed.
相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程