opusfile  0.12.0.3.4174
Stand-alone decoder library for .opus files.
opusfile.h
1 /********************************************************************
2  * *
3  * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. *
4  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
5  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
6  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
7  * *
8  * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012 *
9  * by the Xiph.Org Foundation and contributors https://xiph.org/ *
10  * *
11  ********************************************************************
12 
13  function: stdio-based convenience library for opening/seeking/decoding
14  last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $
15 
16  ********************************************************************/
17 #if !defined(_opusfile_h)
18 # define _opusfile_h (1)
19 
103 # if defined(__cplusplus)
104 extern "C" {
105 # endif
106 
107 # include <stdarg.h>
108 # include <stdio.h>
109 # include <ogg/ogg.h>
110 # include <opus_multistream.h>
111 
114 /*Enable special features for gcc and gcc-compatible compilers.*/
115 # if !defined(OP_GNUC_PREREQ)
116 # if defined(__GNUC__)&&defined(__GNUC_MINOR__)
117 # define OP_GNUC_PREREQ(_maj,_min) \
118  ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
119 # else
120 # define OP_GNUC_PREREQ(_maj,_min) 0
121 # endif
122 # endif
123 
124 # if OP_GNUC_PREREQ(4,0)
125 # pragma GCC visibility push(default)
126 # endif
127 
128 typedef struct OpusHead OpusHead;
129 typedef struct OpusTags OpusTags;
130 typedef struct OpusPictureTag OpusPictureTag;
131 typedef struct OpusServerInfo OpusServerInfo;
132 typedef struct OpusFileCallbacks OpusFileCallbacks;
133 typedef struct OggOpusFile OggOpusFile;
134 
135 /*Warning attributes for libopusfile functions.*/
136 # if OP_GNUC_PREREQ(3,4)
137 # define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
138 # else
139 # define OP_WARN_UNUSED_RESULT
140 # endif
141 # if OP_GNUC_PREREQ(3,4)
142 # define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
143 # else
144 # define OP_ARG_NONNULL(_x)
145 # endif
146 
158 
160 #define OP_FALSE (-1)
161 /*Currently not used externally.*/
162 #define OP_EOF (-2)
163 
165 #define OP_HOLE (-3)
166 
168 #define OP_EREAD (-128)
169 
172 #define OP_EFAULT (-129)
173 
175 #define OP_EIMPL (-130)
176 
177 #define OP_EINVAL (-131)
178 
182 #define OP_ENOTFORMAT (-132)
183 
185 #define OP_EBADHEADER (-133)
186 
187 #define OP_EVERSION (-134)
188 /*Currently not used at all.*/
189 #define OP_ENOTAUDIO (-135)
190 
193 #define OP_EBADPACKET (-136)
194 
197 #define OP_EBADLINK (-137)
198 
199 #define OP_ENOSEEK (-138)
200 
201 #define OP_EBADTIMESTAMP (-139)
202 
205 
208 
210 #define OPUS_CHANNEL_COUNT_MAX (255)
211 
215 struct OpusHead{
225  int version;
230  unsigned pre_skip;
237  opus_uint32 input_sample_rate;
268  unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
269 };
270 
301 struct OpusTags{
307  int comments;
310  char *vendor;
311 };
312 
315 
318 #define OP_PIC_FORMAT_UNKNOWN (-1)
319 
320 #define OP_PIC_FORMAT_URL (0)
321 
322 #define OP_PIC_FORMAT_JPEG (1)
323 
324 #define OP_PIC_FORMAT_PNG (2)
325 
326 #define OP_PIC_FORMAT_GIF (3)
327 
358  opus_int32 type;
365  char *mime_type;
367  char *description;
369  opus_uint32 width;
371  opus_uint32 height;
374  opus_uint32 depth;
377  opus_uint32 colors;
379  opus_uint32 data_length;
381  unsigned char *data;
391  int format;
392 };
393 
402 
428 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
429  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
430 
445 ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
446  OP_ARG_NONNULL(1);
447 
462 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
463  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
464 
472 int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);
473 
478 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
479 
491 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
492  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
493 
504 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
505  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
506 
520 int opus_tags_set_binary_suffix(OpusTags *_tags,
521  const unsigned char *_data,int _len) OP_ARG_NONNULL(1);
522 
538 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
539  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
540 
548 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
549  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
550 
556 const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,
557  int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
558 
574 int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)
575  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
576 
592 int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)
593  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
594 
600 void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
601 
611 int opus_tagcompare(const char *_tag_name,const char *_comment);
612 
626 int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);
627 
658 OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,
659  const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
660 
665 void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
666 
672 void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
673 
677 
689 
692 /*These are the raw numbers used to define the request codes.
693  They should not be used directly.*/
694 #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
695 #define OP_HTTP_PROXY_HOST_REQUEST (6528)
696 #define OP_HTTP_PROXY_PORT_REQUEST (6592)
697 #define OP_HTTP_PROXY_USER_REQUEST (6656)
698 #define OP_HTTP_PROXY_PASS_REQUEST (6720)
699 #define OP_GET_SERVER_INFO_REQUEST (6784)
700 
701 #define OP_URL_OPT(_request) ((char *)(_request))
702 
703 /*These macros trigger compilation errors or warnings if the wrong types are
704  provided to one of the URL options.*/
705 #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
706 #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
707 #define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))
708 
716  char *name;
720  char *description;
724  char *genre;
728  char *url;
731  char *server;
739  opus_int32 bitrate_kbps;
749  int is_ssl;
750 };
751 
756 void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);
757 
764 void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
765 
772 #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
773  OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
774 
783 #define OP_HTTP_PROXY_HOST(_host) \
784  OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
785 
796 #define OP_HTTP_PROXY_PORT(_port) \
797  OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
798 
809 #define OP_HTTP_PROXY_USER(_user) \
810  OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)
811 
822 #define OP_HTTP_PROXY_PASS(_pass) \
823  OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)
824 
843 #define OP_GET_SERVER_INFO(_info) \
844  OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
845 
848 
860 
869 typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
870 
880 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
881 
884 typedef opus_int64 (*op_tell_func)(void *_stream);
885 
890 typedef int (*op_close_func)(void *_stream);
891 
904  op_read_func read;
907  op_seek_func seek;
910  op_tell_func tell;
913  op_close_func close;
914 };
915 
933 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
934  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
935  OP_ARG_NONNULL(3);
936 
950 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
951  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
952 
972 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
973  const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
974  OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
975 
986 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
987  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
988 
1012 OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
1013  const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1014 
1034 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
1035  const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1036 
1039 
1049 
1080 int op_test(OpusHead *_head,
1081  const unsigned char *_initial_data,size_t _initial_bytes);
1082 
1092 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
1093  OP_ARG_NONNULL(1);
1094 
1103 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
1104  size_t _size,int *_error);
1105 
1132 OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
1133  int *_error,va_list _ap) OP_ARG_NONNULL(1);
1134 
1154 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
1155  int *_error,...) OP_ARG_NONNULL(1);
1156 
1236 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
1237  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1238  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1239 
1250 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
1251  OP_ARG_NONNULL(1);
1252 
1262 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
1263  size_t _size,int *_error);
1264 
1293 OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
1294  int *_error,va_list _ap) OP_ARG_NONNULL(1);
1295 
1317 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
1318  int *_error,...) OP_ARG_NONNULL(1);
1319 
1385 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
1386  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1387  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1388 
1415 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
1416 
1419 void op_free(OggOpusFile *_of);
1420 
1423 
1441 
1456 int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1457 
1466 int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1467 
1481 opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1482 
1498 int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1499 
1520 opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1521 
1538 ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1539 
1554 const OpusHead *op_head(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1555 
1572 const OpusTags *op_tags(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1573 
1589 int op_current_link(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1590 
1611 opus_int32 op_bitrate(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1612 
1624 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
1625 
1630 opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1631 
1639 ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1640 
1643 
1671 
1687 int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
1688 
1703 int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
1704 
1707 
1748 
1751 #define OP_DEC_FORMAT_SHORT (7008)
1752 
1754 #define OP_DEC_FORMAT_FLOAT (7040)
1755 
1758 #define OP_DEC_USE_DEFAULT (6720)
1759 
1791 typedef int (*op_decode_cb_func)(void *_ctx,OpusMSDecoder *_decoder,void *_pcm,
1792  const ogg_packet *_op,int _nsamples,int _nchannels,int _format,int _li);
1793 
1815 void op_set_decode_callback(OggOpusFile *_of,
1816  op_decode_cb_func _decode_cb,void *_ctx) OP_ARG_NONNULL(1);
1817 
1821 #define OP_HEADER_GAIN (0)
1822 
1825 #define OP_ALBUM_GAIN (3007)
1826 
1829 #define OP_TRACK_GAIN (3008)
1830 
1833 #define OP_ABSOLUTE_GAIN (3009)
1834 
1852 int op_set_gain_offset(OggOpusFile *_of,
1853  int _gain_type,opus_int32 _gain_offset_q8) OP_ARG_NONNULL(1);
1854 
1865 void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
1866 
1947 OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
1948  opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1949 
2028 OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
2029  float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
2030 
2089 OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
2090  opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2091 
2150 OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
2151  float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2152 
2155 
2156 # if OP_GNUC_PREREQ(4,0)
2157 # pragma GCC visibility pop
2158 # endif
2159 
2160 # if defined(__cplusplus)
2161 }
2162 # endif
2163 
2164 #endif
OpusHead::pre_skip
unsigned pre_skip
The number of samples that should be discarded from the beginning of the stream.
Definition: opusfile.h:230
OpusPictureTag::type
opus_int32 type
The picture type according to the ID3v2 APIC frame:
Definition: opusfile.h:358
OpusTags::comments
int comments
The total number of comment streams.
Definition: opusfile.h:307
OpusHead::mapping
unsigned char mapping[OPUS_CHANNEL_COUNT_MAX]
The mapping from coded stream channels to output channels.
Definition: opusfile.h:268
OpusFileCallbacks::seek
op_seek_func seek
Used to seek in the stream.
Definition: opusfile.h:907
OpusHead::input_sample_rate
opus_uint32 input_sample_rate
The sampling rate of the original input.
Definition: opusfile.h:237
OpusFileCallbacks::close
op_close_func close
Used to close the stream when the decoder is freed.
Definition: opusfile.h:913
OpusServerInfo
HTTP/Shoutcast/Icecast server information associated with a URL.
Definition: opusfile.h:712
OpusServerInfo::server
char * server
The software used by the origin server (Server).
Definition: opusfile.h:731
OpusServerInfo::content_type
char * content_type
The media type of the entity sent to the recepient (Content-Type).
Definition: opusfile.h:735
OpusHead
Ogg Opus bitstream information.
Definition: opusfile.h:215
OpusTags::comment_lengths
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition: opusfile.h:305
OpusTags
The metadata from an Ogg Opus stream.
Definition: opusfile.h:301
OpusServerInfo::is_ssl
int is_ssl
Flag indicating whether the server is using HTTPS instead of HTTP.
Definition: opusfile.h:749
OpusHead::version
int version
The Ogg Opus format version, in the range 0...255.
Definition: opusfile.h:225
OpusPictureTag::height
opus_uint32 height
The height of the picture in pixels.
Definition: opusfile.h:371
OpusServerInfo::description
char * description
A short description of the server (icy-description/ice-description).
Definition: opusfile.h:720
OpusTags::user_comments
char ** user_comments
The array of comment string vectors.
Definition: opusfile.h:303
OpusFileCallbacks
The callbacks used to access non-FILE stream resources.
Definition: opusfile.h:901
OpusServerInfo::url
char * url
The homepage for the server (icy-url/ice-url).
Definition: opusfile.h:728
OpusPictureTag::colors
opus_uint32 colors
For indexed-color pictures (e.g., GIF), the number of colors used, or 0 for non-indexed pictures.
Definition: opusfile.h:377
OpusPictureTag::mime_type
char * mime_type
The MIME type of the picture, in printable ASCII characters 0x20-0x7E.
Definition: opusfile.h:365
OpusPictureTag
The contents of a METADATA_BLOCK_PICTURE tag.
Definition: opusfile.h:331
OpusFileCallbacks::read
op_read_func read
Used to read data from the stream.
Definition: opusfile.h:904
OpusPictureTag::depth
opus_uint32 depth
The color depth of the picture in bits-per-pixel (not bits-per-channel).
Definition: opusfile.h:374
OpusServerInfo::is_public
int is_public
Flag indicating whether the server is public (1) or not (0) (icy-pub/ice-public).
Definition: opusfile.h:744
OpusPictureTag::width
opus_uint32 width
The width of the picture in pixels.
Definition: opusfile.h:369
OpusHead::stream_count
int stream_count
The number of Opus streams in each Ogg packet, in the range 1...255.
Definition: opusfile.h:253
OpusTags::vendor
char * vendor
The null-terminated vendor string.
Definition: opusfile.h:310
OpusHead::channel_count
int channel_count
The number of channels, in the range 1...255.
Definition: opusfile.h:227
OpusPictureTag::data_length
opus_uint32 data_length
The length of the picture data in bytes.
Definition: opusfile.h:379
OpusPictureTag::description
char * description
The description of the picture, in UTF-8.
Definition: opusfile.h:367
OpusFileCallbacks::tell
op_tell_func tell
Used to return the current read position in the stream.
Definition: opusfile.h:910
OpusPictureTag::data
unsigned char * data
The binary picture data.
Definition: opusfile.h:381
OpusHead::output_gain
int output_gain
The gain to apply to the decoded output, in dB, as a Q8 value in the range -32768....
Definition: opusfile.h:244
OpusHead::mapping_family
int mapping_family
The channel mapping family, in the range 0...255.
Definition: opusfile.h:251
OpusHead::coupled_count
int coupled_count
The number of coupled Opus streams in each Ogg packet, in the range 0...127.
Definition: opusfile.h:260
OpusServerInfo::name
char * name
The name of the server (icy-name/ice-name).
Definition: opusfile.h:716
OpusServerInfo::genre
char * genre
The genre the server falls under (icy-genre/ice-genre).
Definition: opusfile.h:724
OpusServerInfo::bitrate_kbps
opus_int32 bitrate_kbps
The nominal stream bitrate in kbps (icy-br/ice-bitrate).
Definition: opusfile.h:739
OpusPictureTag::format
int format
The format of the picture data, if known.
Definition: opusfile.h:391