Opus
Opus audio codec (RFC 6716): API and operations manual
1.2
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
40 extern "C" {
41 #endif
42 
164 typedef struct OpusEncoder OpusEncoder;
165 
171 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels);
172 
208 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create(
209  opus_int32 Fs,
210  int channels,
211  int application,
212  int *error
213 );
214 
228 OPUS_EXPORT int opus_encoder_init(
229  OpusEncoder *st,
230  opus_int32 Fs,
231  int channels,
232  int application
233 ) OPUS_ARG_NONNULL(1);
234 
263 OPUS_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 
304 OPUS_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 
315 OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
316 
328 OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
399 typedef struct OpusDecoder OpusDecoder;
400 
406 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels);
407 
423 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create(
424  opus_int32 Fs,
425  int channels,
426  int *error
427 );
428 
440 OPUS_EXPORT int opus_decoder_init(
441  OpusDecoder *st,
442  opus_int32 Fs,
443  int channels
444 ) OPUS_ARG_NONNULL(1);
445 
462 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode(
463  OpusDecoder *st,
464  const unsigned char *data,
465  opus_int32 len,
466  opus_int16 *pcm,
467  int frame_size,
468  int decode_fec
469 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
470 
487 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float(
488  OpusDecoder *st,
489  const unsigned char *data,
490  opus_int32 len,
491  float *pcm,
492  int frame_size,
493  int decode_fec
494 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
495 
507 OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
508 
512 OPUS_EXPORT void opus_decoder_destroy(OpusDecoder *st);
513 
527 OPUS_EXPORT int opus_packet_parse(
528  const unsigned char *data,
529  opus_int32 len,
530  unsigned char *out_toc,
531  const unsigned char *frames[48],
532  opus_int16 size[48],
533  int *payload_offset
534 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
535 
545 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1);
546 
556 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1);
557 
563 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1);
564 
572 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1);
573 
584 OPUS_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);
585 
594 OPUS_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);
595 
606 OPUS_EXPORT void opus_pcm_soft_clip(float *pcm, int frame_size, int channels, float *softclip_mem);
607 
608 
755 
759 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
760 
778 OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
779 
783 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);
784 
789 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
790 
838 OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
839 
840 
872 OPUS_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);
873 
884 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
885 
915 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1);
916 
929 OPUS_EXPORT int opus_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len);
930 
942 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_packet_unpad(unsigned char *data, opus_int32 len);
943 
958 OPUS_EXPORT int opus_multistream_packet_pad(unsigned char *data, opus_int32 len, opus_int32 new_len, int nb_streams);
959 
973 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_packet_unpad(unsigned char *data, opus_int32 len, int nb_streams);
974 
977 #ifdef __cplusplus
978 }
979 #endif
980 
981 #endif /* OPUS_H */
OpusDecoder * opus_decoder_create(opus_int32 Fs, int channels, int *error)
Allocates and initializes a decoder state.
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.
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 reference implementation types.
struct OpusRepacketizer OpusRepacketizer
Definition: opus.h:754
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...
short opus_int16
Definition: opus_types.h:144
int opus_repacketizer_get_size(void)
Gets the size of an OpusRepacketizer structure.
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_packet_get_nb_frames(const unsigned char packet[], opus_int32 len)
Gets the number of frames in an Opus packet.
int opus_packet_get_nb_channels(const unsigned char *data)
Gets the number of channels from an Opus packet.
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_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...
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.
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_packet_get_bandwidth(const unsigned char *data)
Gets the bandwidth of an Opus packet.
int opus_encoder_ctl(OpusEncoder *st, int request,...)
Perform a CTL function on an Opus encoder.
Opus reference implementation constants.
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.
int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len)
Add a packet to the current repacketizer state.
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...
int opus_int32
Definition: opus_types.h:146
struct OpusEncoder OpusEncoder
Opus encoder state.
Definition: opus.h:164
void opus_encoder_destroy(OpusEncoder *st)
Frees an OpusEncoder allocated by opus_encoder_create().
void opus_decoder_destroy(OpusDecoder *st)
Frees an OpusDecoder allocated by opus_decoder_create().
OpusRepacketizer * opus_repacketizer_init(OpusRepacketizer *rp)
(Re)initializes a previously allocated repacketizer 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.
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...
int opus_decoder_init(OpusDecoder *st, opus_int32 Fs, int channels)
Initializes a previously allocated decoder state.
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)...
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.
OpusRepacketizer * opus_repacketizer_create(void)
Allocates memory and initializes the new repacketizer with opus_repacketizer_init().
OpusEncoder * opus_encoder_create(opus_int32 Fs, int channels, int application, int *error)
Allocates and initializes an encoder 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_get_size(int channels)
Gets the size of an OpusDecoder structure.
void opus_repacketizer_destroy(OpusRepacketizer *rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
int opus_decoder_ctl(OpusDecoder *st, int request,...)
Perform a CTL function on an Opus decoder.
struct OpusDecoder OpusDecoder
Opus decoder state.
Definition: opus.h:399
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_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...
For more information visit the Opus Website.