opusfile  0.8
Stand-alone decoder library for .opus files.
 All Data Structures Functions Variables Typedefs Groups
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 http://www.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 };
269 
300 struct OpusTags{
306  int comments;
309  char *vendor;
310 };
311 
314 
317 #define OP_PIC_FORMAT_UNKNOWN (-1)
318 
319 #define OP_PIC_FORMAT_URL (0)
320 
321 #define OP_PIC_FORMAT_JPEG (1)
322 
323 #define OP_PIC_FORMAT_PNG (2)
324 
325 #define OP_PIC_FORMAT_GIF (3)
326 
357  opus_int32 type;
364  char *mime_type;
366  char *description;
368  opus_uint32 width;
370  opus_uint32 height;
373  opus_uint32 depth;
376  opus_uint32 colors;
378  opus_uint32 data_length;
380  unsigned char *data;
390  int format;
391 };
392 
401 
427 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
428  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
429 
444 ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
445  OP_ARG_NONNULL(1);
446 
461 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
462  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
463 
471 int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);
472 
477 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
478 
490 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
491  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
492 
503 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
504  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
505 
520  const unsigned char *_data,int _len) OP_ARG_NONNULL(1);
521 
537 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
538  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
539 
547 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
548  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
549 
555 const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,
556  int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
557 
573 int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)
574  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
575 
591 int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)
592  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
593 
599 void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
600 
610 int opus_tagcompare(const char *_tag_name,const char *_comment);
611 
625 int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);
626 
657 OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,
658  const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
659 
664 void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
665 
671 void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
672 
676 
688 
691 /*These are the raw numbers used to define the request codes.
692  They should not be used directly.*/
693 #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
694 #define OP_HTTP_PROXY_HOST_REQUEST (6528)
695 #define OP_HTTP_PROXY_PORT_REQUEST (6592)
696 #define OP_HTTP_PROXY_USER_REQUEST (6656)
697 #define OP_HTTP_PROXY_PASS_REQUEST (6720)
698 #define OP_GET_SERVER_INFO_REQUEST (6784)
699 
700 #define OP_URL_OPT(_request) ((_request)+(char *)0)
701 
702 /*These macros trigger compilation errors or warnings if the wrong types are
703  provided to one of the URL options.*/
704 #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
705 #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
706 #define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))
707 
715  char *name;
719  char *description;
723  char *genre;
727  char *url;
730  char *server;
738  opus_int32 bitrate_kbps;
748  int is_ssl;
749 };
750 
755 void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);
756 
763 void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
764 
771 #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
772  OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
773 
782 #define OP_HTTP_PROXY_HOST(_host) \
783  OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
784 
795 #define OP_HTTP_PROXY_PORT(_port) \
796  OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
797 
808 #define OP_HTTP_PROXY_USER(_user) \
809  OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)
810 
821 #define OP_HTTP_PROXY_PASS(_pass) \
822  OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)
823 
842 #define OP_GET_SERVER_INFO(_info) \
843  OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
844 
847 
859 
868 typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
869 
879 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
880 
883 typedef opus_int64 (*op_tell_func)(void *_stream);
884 
889 typedef int (*op_close_func)(void *_stream);
890 
913 };
914 
932 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
933  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
934  OP_ARG_NONNULL(3);
935 
949 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
950  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
951 
971 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
972  const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
973  OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
974 
985 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
986  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
987 
1011 OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
1012  const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1013 
1033 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
1034  const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
1035 
1038 
1048 
1079 int op_test(OpusHead *_head,
1080  const unsigned char *_initial_data,size_t _initial_bytes);
1081 
1091 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
1092  OP_ARG_NONNULL(1);
1093 
1102 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
1103  size_t _size,int *_error);
1104 
1131 OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
1132  int *_error,va_list _ap) OP_ARG_NONNULL(1);
1133 
1153 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
1154  int *_error,...) OP_ARG_NONNULL(1);
1155 
1233 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
1234  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1235  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1236 
1247 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
1248  OP_ARG_NONNULL(1);
1249 
1259 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
1260  size_t _size,int *_error);
1261 
1290 OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
1291  int *_error,va_list _ap) OP_ARG_NONNULL(1);
1292 
1314 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
1315  int *_error,...) OP_ARG_NONNULL(1);
1316 
1380 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
1381  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
1382  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
1383 
1410 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
1411 
1414 void op_free(OggOpusFile *_of);
1415 
1418 
1436 
1451 int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1452 
1461 int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1462 
1476 opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1477 
1493 int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1494 
1515 opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1516 
1533 ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1534 
1549 const OpusHead *op_head(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1550 
1567 const OpusTags *op_tags(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1568 
1584 int op_current_link(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1585 
1606 opus_int32 op_bitrate(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
1607 
1619 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
1620 
1625 opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1626 
1634 ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
1635 
1638 
1666 
1680 int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
1681 
1696 int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
1697 
1700 
1741 
1744 #define OP_DEC_FORMAT_SHORT (7008)
1745 
1747 #define OP_DEC_FORMAT_FLOAT (7040)
1748 
1751 #define OP_DEC_USE_DEFAULT (6720)
1752 
1784 typedef int (*op_decode_cb_func)(void *_ctx,OpusMSDecoder *_decoder,void *_pcm,
1785  const ogg_packet *_op,int _nsamples,int _nchannels,int _format,int _li);
1786 
1808 void op_set_decode_callback(OggOpusFile *_of,
1809  op_decode_cb_func _decode_cb,void *_ctx) OP_ARG_NONNULL(1);
1810 
1814 #define OP_HEADER_GAIN (0)
1815 
1818 #define OP_ALBUM_GAIN (3007)
1819 
1822 #define OP_TRACK_GAIN (3008)
1823 
1826 #define OP_ABSOLUTE_GAIN (3009)
1827 
1845 int op_set_gain_offset(OggOpusFile *_of,
1846  int _gain_type,opus_int32 _gain_offset_q8) OP_ARG_NONNULL(1);
1847 
1858 void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
1859 
1940 OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
1941  opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
1942 
2021 OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
2022  float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
2023 
2082 OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
2083  opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2084 
2143 OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
2144  float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
2145 
2148 
2149 # if OP_GNUC_PREREQ(4,0)
2150 # pragma GCC visibility pop
2151 # endif
2152 
2153 # if defined(__cplusplus)
2154 }
2155 # endif
2156 
2157 #endif