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

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(5);
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
754 typedef struct OpusRepacketizer OpusRepacketizer;
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 */
opus_decoder_create
OpusDecoder * opus_decoder_create(opus_int32 Fs, int channels, int *error)
Allocates and initializes a decoder state.
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.
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_types.h
Opus reference implementation types.
OpusRepacketizer
struct OpusRepacketizer OpusRepacketizer
Definition: opus.h:754
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_int16
short opus_int16
Definition: opus_types.h:159
opus_repacketizer_get_size
int opus_repacketizer_get_size(void)
Gets the size of an OpusRepacketizer structure.
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_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_packet_get_nb_channels
int opus_packet_get_nb_channels(const unsigned char *data)
Gets the number of channels from an Opus packet.
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_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_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_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_packet_get_bandwidth
int opus_packet_get_bandwidth(const unsigned char *data)
Gets the bandwidth of an Opus packet.
opus_encoder_ctl
int opus_encoder_ctl(OpusEncoder *st, int request,...)
Perform a CTL function on an Opus encoder.
opus_defines.h
Opus reference implementation constants.
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.
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_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_int32
int opus_int32
Definition: opus_types.h:161
OpusEncoder
struct OpusEncoder OpusEncoder
Opus encoder state.
Definition: opus.h:164
opus_encoder_destroy
void opus_encoder_destroy(OpusEncoder *st)
Frees an OpusEncoder allocated by opus_encoder_create().
opus_decoder_destroy
void opus_decoder_destroy(OpusDecoder *st)
Frees an OpusDecoder allocated by opus_decoder_create().
opus_repacketizer_init
OpusRepacketizer * opus_repacketizer_init(OpusRepacketizer *rp)
(Re)initializes a previously allocated repacketizer 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_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...
opus_decoder_init
int opus_decoder_init(OpusDecoder *st, opus_int32 Fs, int channels)
Initializes a previously allocated decoder state.
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_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_repacketizer_create
OpusRepacketizer * opus_repacketizer_create(void)
Allocates memory and initializes the new repacketizer with opus_repacketizer_init().
opus_encoder_create
OpusEncoder * opus_encoder_create(opus_int32 Fs, int channels, int application, int *error)
Allocates and initializes an encoder 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_get_size
int opus_decoder_get_size(int channels)
Gets the size of an OpusDecoder structure.
opus_repacketizer_destroy
void opus_repacketizer_destroy(OpusRepacketizer *rp)
Frees an OpusRepacketizer allocated by opus_repacketizer_create().
opus_decoder_ctl
int opus_decoder_ctl(OpusDecoder *st, int request,...)
Perform a CTL function on an Opus decoder.
OpusDecoder
struct OpusDecoder OpusDecoder
Opus decoder state.
Definition: opus.h:399
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_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...

For more information visit the Opus Website. |