Opus
Opus audio codec (RFC 6716): API and operations manual
1.5.2
Loading...
Searching...
No Matches
opus.h
Go to the documentation of this file.
1/* Copyright (c) 2010-2011 Xiph.Org Foundation, Skype Limited
2 Written by Jean-Marc Valin and Koen Vos */
3/*
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions
6 are met:
7
8 - Redistributions of source code must retain the above copyright
9 notice, this list of conditions and the following disclaimer.
10
11 - Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in the
13 documentation and/or other materials provided with the distribution.
14
15 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
19 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
33#ifndef OPUS_H
34#define OPUS_H
35
36#include "opus_types.h"
37#include "opus_defines.h"
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
165
171OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels);
172
208OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create(
209 opus_int32 Fs,
210 int channels,
211 int application,
212 int *error
213);
214
228OPUS_EXPORT int opus_encoder_init(
229 OpusEncoder *st,
230 opus_int32 Fs,
231 int channels,
232 int application
233) OPUS_ARG_NONNULL(1);
234
263OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode(
264 OpusEncoder *st,
265 const opus_int16 *pcm,
266 int frame_size,
267 unsigned char *data,
268 opus_int32 max_data_bytes
269) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
270
304OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float(
305 OpusEncoder *st,
306 const float *pcm,
307 int frame_size,
308 unsigned char *data,
309 opus_int32 max_data_bytes
310) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
311
315OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
316
328OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
400
407
408
414typedef struct OpusDRED OpusDRED;
415
421OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels);
422
438OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create(
439 opus_int32 Fs,
440 int channels,
441 int *error
442);
443
455OPUS_EXPORT int opus_decoder_init(
456 OpusDecoder *st,
457 opus_int32 Fs,
458 int channels
459) OPUS_ARG_NONNULL(1);
460
477OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode(
478 OpusDecoder *st,
479 const unsigned char *data,
480 opus_int32 len,
481 opus_int16 *pcm,
482 int frame_size,
483 int decode_fec
484) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
485
502OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float(
503 OpusDecoder *st,
504 const unsigned char *data,
505 opus_int32 len,
506 float *pcm,
507 int frame_size,
508 int decode_fec
509) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
510
522OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
523
527OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
528
532OPUS_EXPORT int opus_dred_decoder_get_size(void);
533
538
543
548
560OPUS_EXPORT int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request, ...);
561
565OPUS_EXPORT int opus_dred_get_size(void);
566
570OPUS_EXPORT OpusDRED *opus_dred_alloc(int *error);
571
575OPUS_EXPORT void opus_dred_free(OpusDRED *dec);
576
588OPUS_EXPORT int opus_dred_parse(OpusDREDDecoder *dred_dec, OpusDRED *dred, const unsigned char *data, opus_int32 len, opus_int32 max_dred_samples, opus_int32 sampling_rate, int *dred_end, int defer_processing) OPUS_ARG_NONNULL(1);
589
597OPUS_EXPORT int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst);
598
609OPUS_EXPORT int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size);
610
621OPUS_EXPORT int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size);
622
623
637OPUS_EXPORT int opus_packet_parse(
638 const unsigned char *data,
639 opus_int32 len,
640 unsigned char *out_toc,
641 const unsigned char *frames[48],
642 opus_int16 size[48],
643 int *payload_offset
644) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5);
645
655OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1);
656
666OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1);
667
673OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1);
674
682OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1);
683
694OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_samples(const unsigned char packet[], opus_int32 len, opus_int32 Fs) OPUS_ARG_NONNULL(1);
695
702OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len);
703
712OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
713
724OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem);
725
726
873
877OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
878
896OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
897
901OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);
902
908
956OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
957
958
990OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
991
1002OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
1003
1033OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1);
1034
1047OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len);
1048
1060OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len);
1061
1076OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams);
1077
1091OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams);
1092
1095#ifdef __cplusplus
1096}
1097#endif
1098
1099#endif /* OPUS_H */
int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len)
Gets the number of frames in an Opus packet.
void opus_dred_decoder_destroy(OpusDREDDecoder *dec)
Frees an OpusDREDDecoder allocated by opus_dred_decoder_create().
OpusDRED * opus_dred_alloc(int *error)
Allocates and initializes a DRED state.
int opus_decoder_ctl(OpusDecoder *st, int request,...)
Perform a CTL function on an Opus decoder.
int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request,...)
Perform a CTL function on an Opus DRED decoder.
int opus_packet_get_nb_samples(const unsigned char packet[], opus_int32 len, opus_int32 Fs)
Gets the number of samples of an Opus packet.
struct OpusDecoder OpusDecoder
Opus decoder state.
Definition opus.h:399
int opus_packet_get_nb_channels(const unsigned char *data)
Gets the number of channels from an Opus packet.
int opus_dred_decoder_get_size(void)
Gets the size of an OpusDREDDecoder structure.
struct OpusDRED OpusDRED
Opus DRED state.
Definition opus.h:414
int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len)
Gets the number of samples of an Opus packet.
int opus_dred_parse(OpusDREDDecoder *dred_dec, OpusDRED *dred, const unsigned char *data, opus_int32 len, opus_int32 max_dred_samples, opus_int32 sampling_rate, int *dred_end, int defer_processing)
Decode an Opus DRED packet.
OpusDecoder * opus_decoder_create(opus_int32 Fs, int channels, int *error)
Allocates and initializes a decoder state.
int opus_decode(OpusDecoder *st, const unsigned char *data, opus_int32 len, opus_int16 *pcm, int frame_size, int decode_fec)
Decode an Opus packet.
int opus_packet_get_bandwidth(const unsigned char *data)
Gets the bandwidth of an Opus packet.
void opus_dred_free(OpusDRED *dec)
Frees an OpusDRED allocated by opus_dred_create().
int opus_decoder_init(OpusDecoder *st, opus_int32 Fs, int channels)
Initializes a previously allocated decoder state.
int opus_decode_float(OpusDecoder *st, const unsigned char *data, opus_int32 len, float *pcm, int frame_size, int decode_fec)
Decode an Opus packet with floating point output.
int opus_packet_parse(const unsigned char *data, opus_int32 len, unsigned char *out_toc, const unsigned char *frames[48], opus_int16 size[48], int *payload_offset)
Parse an opus packet into one or more frames.
int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size)
Decode audio from an Opus DRED packet with floating point output.
struct OpusDREDDecoder OpusDREDDecoder
Opus DRED decoder.
Definition opus.h:406
int opus_dred_get_size(void)
Gets the size of an OpusDRED structure.
OpusDREDDecoder * opus_dred_decoder_create(int *error)
Allocates and initializes an OpusDREDDecoder state.
int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs)
Gets the number of samples per frame from an Opus packet.
int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size)
Decode audio from an Opus DRED packet with floating point output.
int opus_decoder_get_size(int channels)
Gets the size of an OpusDecoder structure.
int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len)
Checks whether an Opus packet has LBRR.
int opus_dred_decoder_init(OpusDREDDecoder *dec)
Initializes an OpusDREDDecoder state.
int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst)
Finish decoding an Opus DRED packet.
void opus_decoder_destroy(OpusDecoder *st)
Frees an OpusDecoder allocated by opus_decoder_create().
void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem)
Applies soft-clipping to bring a float signal within the [-1,1] range.
OpusEncoder * opus_encoder_create(opus_int32 Fs, int channels, int application, int *error)
Allocates and initializes an encoder state.
int opus_encoder_ctl(OpusEncoder *st, int request,...)
Perform a CTL function on an Opus encoder.
opus_int32 opus_encode_float(OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)
Encodes an Opus frame from floating point input.
int opus_encoder_init(OpusEncoder *st, opus_int32 Fs, int channels, int application)
Initializes a previously allocated encoder state The memory pointed to by st must be at least the siz...
void opus_encoder_destroy(OpusEncoder *st)
Frees an OpusEncoder allocated by opus_encoder_create().
opus_int32 opus_encode(OpusEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)
Encodes an Opus frame.
int opus_encoder_get_size(int channels)
Gets the size of an OpusEncoder structure.
struct OpusEncoder OpusEncoder
Opus encoder state.
Definition opus.h:164
opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len)
Remove all padding from a given Opus packet and rewrite the TOC sequence to minimize space usage.
opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the repacketizer state via opus_repacketizer...
struct OpusRepacketizer OpusRepacketizer
Definition opus.h:872
int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len)
Add a packet to the current repacketizer state.
int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp)
Return the total number of frames contained in packet data submitted to the repacketizer state so far...
int opus_repacketizer_get_size(void)
Gets the size of an OpusRepacketizer structure.
int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len)
Pads a given Opus packet to a larger size (possibly changing the TOC sequence).
OpusRepacketizer * opus_repacketizer_init(OpusRepacketizer *rp)
(Re)initializes a previously allocated repacketizer state.
opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams)
Remove all padding from a given Opus multi-stream packet and rewrite the TOC sequence to minimize spa...
opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen)
Construct a new packet from data previously submitted to the repacketizer state via opus_repacketizer...
int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams)
Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence).
void opus_repacketizer_destroy(OpusRepacketizer *rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
OpusRepacketizer * opus_repacketizer_create(void)
Allocates memory and initializes the new repacketizer with opus_repacketizer_init().
Opus reference implementation constants.
Opus reference implementation types.
int opus_int32
Definition opus_types.h:161
short opus_int16
Definition opus_types.h:159
For more information visit the Opus Website.