Opus audio codec (RFC 6716): API and operations manual
| 1.6

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
32
33#ifndef OPUS_H
34#define OPUS_H
35
36#include "opus_types.h"
37#include "opus_defines.h"
38
39#ifdef __cplusplus
40 extern "C" {
41#endif
42
74
158
164 typedef struct OpusEncoder OpusEncoder;
165
174OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels);
175
178
211OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create(
212 opus_int32 Fs,
213 int channels,
214 int application,
215 int *error
216);
217
231OPUS_EXPORT int opus_encoder_init(
232 OpusEncoder *st,
233 opus_int32 Fs,
234 int channels,
235 int application
236) OPUS_ARG_NONNULL(1);
237
266OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode(
267 OpusEncoder *st,
268 const opus_int16 *pcm,
269 int frame_size,
270 unsigned char *data,
271 opus_int32 max_data_bytes
272) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
273
302OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode24(
303 OpusEncoder *st,
304 const opus_int32 *pcm,
305 int frame_size,
306 unsigned char *data,
307 opus_int32 max_data_bytes
308) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
309
343OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float(
344 OpusEncoder *st,
345 const float *pcm,
346 int frame_size,
347 unsigned char *data,
348 opus_int32 max_data_bytes
349) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
350
354OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
355
367OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
369
432
438typedef struct OpusDecoder OpusDecoder;
439
445typedef struct OpusDREDDecoder OpusDREDDecoder;
446
447
453typedef struct OpusDRED OpusDRED;
454
460OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels);
461
477OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create(
478 opus_int32 Fs,
479 int channels,
480 int *error
481);
482
494OPUS_EXPORT int opus_decoder_init(
495 OpusDecoder *st,
496 opus_int32 Fs,
497 int channels
498) OPUS_ARG_NONNULL(1);
499
516OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode(
517 OpusDecoder *st,
518 const unsigned char *data,
519 opus_int32 len,
520 opus_int16 *pcm,
521 int frame_size,
522 int decode_fec
523) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
524
541OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode24(
542 OpusDecoder *st,
543 const unsigned char *data,
544 opus_int32 len,
545 opus_int32 *pcm,
546 int frame_size,
547 int decode_fec
548) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
549
566OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float(
567 OpusDecoder *st,
568 const unsigned char *data,
569 opus_int32 len,
570 float *pcm,
571 int frame_size,
572 int decode_fec
573) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
574
586OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
587
591OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
592
596OPUS_EXPORT int opus_dred_decoder_get_size(void);
597
601OPUS_EXPORT OpusDREDDecoder *opus_dred_decoder_create(int *error);
602
606OPUS_EXPORT int opus_dred_decoder_init(OpusDREDDecoder *dec);
607
611OPUS_EXPORT void opus_dred_decoder_destroy(OpusDREDDecoder *dec);
612
624OPUS_EXPORT int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request, ...);
625
629OPUS_EXPORT int opus_dred_get_size(void);
630
634OPUS_EXPORT OpusDRED *opus_dred_alloc(int *error);
635
639OPUS_EXPORT void opus_dred_free(OpusDRED *dec);
640
652OPUS_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);
653
661OPUS_EXPORT int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst);
662
673OPUS_EXPORT int opus_decoder_dred_decode(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int16 *pcm, opus_int32 frame_size);
674
685OPUS_EXPORT int opus_decoder_dred_decode24(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int32 *pcm, opus_int32 frame_size);
686
697OPUS_EXPORT int opus_decoder_dred_decode_float(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, float *pcm, opus_int32 frame_size);
698
699
713OPUS_EXPORT int opus_packet_parse(
714 const unsigned char *data,
715 opus_int32 len,
716 unsigned char *out_toc,
717 const unsigned char *frames[48],
718 opus_int16 size[48],
719 int *payload_offset
720) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5);
721
731OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1);
732
742OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1);
743
749OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1);
750
758OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1);
759
770OPUS_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);
771
778OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len);
779
788OPUS_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);
789
800OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem);
801
802
804
947
948typedef struct OpusRepacketizer OpusRepacketizer;
949
953OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
954
972OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
973
977OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);
978
983OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
984
1032OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
1033
1034
1066OPUS_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);
1067
1078OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
1079
1109OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1);
1110
1123OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len);
1124
1136OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len);
1137
1152OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams);
1153
1167OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams);
1168
1170
1171#ifdef __cplusplus
1172}
1173#endif
1174
1175#endif /* OPUS_H */
opus_packet_get_nb_frames
int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len)
Gets the number of frames in an Opus packet.
opus_dred_decoder_destroy
void opus_dred_decoder_destroy(OpusDREDDecoder *dec)
Frees an OpusDREDDecoder allocated by opus_dred_decoder_create().
opus_dred_alloc
OpusDRED * opus_dred_alloc(int *error)
Allocates and initializes a DRED state.
opus_decoder_ctl
int opus_decoder_ctl(OpusDecoder *st, int request,...)
Perform a CTL function on an Opus decoder.
opus_dred_decoder_ctl
int opus_dred_decoder_ctl(OpusDREDDecoder *dred_dec, int request,...)
Perform a CTL function on an Opus DRED decoder.
opus_packet_get_nb_samples
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.
OpusDecoder
struct OpusDecoder OpusDecoder
Opus decoder state.
Definition opus.h:438
opus_packet_get_nb_channels
int opus_packet_get_nb_channels(const unsigned char *data)
Gets the number of channels from an Opus packet.
opus_decoder_dred_decode24
int opus_decoder_dred_decode24(OpusDecoder *st, const OpusDRED *dred, opus_int32 dred_offset, opus_int32 *pcm, opus_int32 frame_size)
Decode audio from an Opus DRED packet with 24-bit output.
opus_dred_decoder_get_size
int opus_dred_decoder_get_size(void)
Gets the size of an OpusDREDDecoder structure.
OpusDRED
struct OpusDRED OpusDRED
Opus DRED state.
Definition opus.h:453
opus_decoder_get_nb_samples
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.
opus_dred_parse
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.
opus_decoder_create
OpusDecoder * opus_decoder_create(opus_int32 Fs, int channels, int *error)
Allocates and initializes a decoder state.
opus_decode
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.
opus_packet_get_bandwidth
int opus_packet_get_bandwidth(const unsigned char *data)
Gets the bandwidth of an Opus packet.
opus_dred_free
void opus_dred_free(OpusDRED *dec)
Frees an OpusDRED allocated by opus_dred_create().
opus_decoder_init
int opus_decoder_init(OpusDecoder *st, opus_int32 Fs, int channels)
Initializes a previously allocated decoder state.
opus_decode_float
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.
opus_packet_parse
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.
opus_decoder_dred_decode_float
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.
OpusDREDDecoder
struct OpusDREDDecoder OpusDREDDecoder
Opus DRED decoder.
Definition opus.h:445
opus_dred_get_size
int opus_dred_get_size(void)
Gets the size of an OpusDRED structure.
opus_dred_decoder_create
OpusDREDDecoder * opus_dred_decoder_create(int *error)
Allocates and initializes an OpusDREDDecoder state.
opus_packet_get_samples_per_frame
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.
opus_decoder_dred_decode
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 16-bit output.
opus_decoder_get_size
int opus_decoder_get_size(int channels)
Gets the size of an OpusDecoder structure.
opus_packet_has_lbrr
int opus_packet_has_lbrr(const unsigned char packet[], opus_int32 len)
Checks whether an Opus packet has LBRR.
opus_dred_decoder_init
int opus_dred_decoder_init(OpusDREDDecoder *dec)
Initializes an OpusDREDDecoder state.
opus_dred_process
int opus_dred_process(OpusDREDDecoder *dred_dec, const OpusDRED *src, OpusDRED *dst)
Finish decoding an Opus DRED packet.
opus_decode24
int opus_decode24(OpusDecoder *st, const unsigned char *data, opus_int32 len, opus_int32 *pcm, int frame_size, int decode_fec)
Decode an Opus packet.
opus_decoder_destroy
void opus_decoder_destroy(OpusDecoder *st)
Frees an OpusDecoder allocated by opus_decoder_create().
opus_pcm_soft_clip
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.
opus_encoder_create
OpusEncoder * opus_encoder_create(opus_int32 Fs, int channels, int application, int *error)
Allocates and initializes an encoder state.
opus_encoder_ctl
int opus_encoder_ctl(OpusEncoder *st, int request,...)
Perform a CTL function on an Opus encoder.
opus_encode24
opus_int32 opus_encode24(OpusEncoder *st, const opus_int32 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)
Encodes an Opus frame.
opus_encode_float
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.
opus_encoder_init
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...
opus_encoder_destroy
void opus_encoder_destroy(OpusEncoder *st)
Frees an OpusEncoder allocated by opus_encoder_create().
opus_encode
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.
opus_encoder_get_size
int opus_encoder_get_size(int channels)
Gets the size of an OpusEncoder structure.
OpusEncoder
struct OpusEncoder OpusEncoder
Opus encoder state.
Definition opus.h:164
opus_packet_unpad
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_repacketizer_out
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...
OpusRepacketizer
struct OpusRepacketizer OpusRepacketizer
Definition opus.h:948
opus_repacketizer_cat
int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len)
Add a packet to the current repacketizer state.
opus_repacketizer_get_nb_frames
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...
opus_repacketizer_get_size
int opus_repacketizer_get_size(void)
Gets the size of an OpusRepacketizer structure.
opus_packet_pad
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).
opus_repacketizer_init
OpusRepacketizer * opus_repacketizer_init(OpusRepacketizer *rp)
(Re)initializes a previously allocated repacketizer state.
opus_multistream_packet_unpad
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_repacketizer_out_range
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...
opus_multistream_packet_pad
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).
opus_repacketizer_destroy
void opus_repacketizer_destroy(OpusRepacketizer *rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
opus_repacketizer_create
OpusRepacketizer * opus_repacketizer_create(void)
Allocates memory and initializes the new repacketizer with opus_repacketizer_init().
opus_defines.h
Opus reference implementation constants.
opus_types.h
Opus reference implementation types.
opus_int32
int opus_int32
Definition opus_types.h:161
opus_int16
short opus_int16
Definition opus_types.h:159