opusfile  0.12
Stand-alone decoder library for .opus files.
opusfile.h
00001 /********************************************************************
00002  *                                                                  *
00003  * THIS FILE IS PART OF THE libopusfile SOFTWARE CODEC SOURCE CODE. *
00004  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
00005  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
00006  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
00007  *                                                                  *
00008  * THE libopusfile SOURCE CODE IS (C) COPYRIGHT 1994-2012           *
00009  * by the Xiph.Org Foundation and contributors https://xiph.org/    *
00010  *                                                                  *
00011  ********************************************************************
00012 
00013  function: stdio-based convenience library for opening/seeking/decoding
00014  last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $
00015 
00016  ********************************************************************/
00017 #if !defined(_opusfile_h)
00018 # define _opusfile_h (1)
00019 
00103 # if defined(__cplusplus)
00104 extern "C" {
00105 # endif
00106 
00107 # include <stdarg.h>
00108 # include <stdio.h>
00109 # include <ogg/ogg.h>
00110 # include <opus_multistream.h>
00111 
00114 /*Enable special features for gcc and gcc-compatible compilers.*/
00115 # if !defined(OP_GNUC_PREREQ)
00116 #  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
00117 #   define OP_GNUC_PREREQ(_maj,_min) \
00118  ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
00119 #  else
00120 #   define OP_GNUC_PREREQ(_maj,_min) 0
00121 #  endif
00122 # endif
00123 
00124 # if OP_GNUC_PREREQ(4,0)
00125 #  pragma GCC visibility push(default)
00126 # endif
00127 
00128 typedef struct OpusHead          OpusHead;
00129 typedef struct OpusTags          OpusTags;
00130 typedef struct OpusPictureTag    OpusPictureTag;
00131 typedef struct OpusServerInfo    OpusServerInfo;
00132 typedef struct OpusFileCallbacks OpusFileCallbacks;
00133 typedef struct OggOpusFile       OggOpusFile;
00134 
00135 /*Warning attributes for libopusfile functions.*/
00136 # if OP_GNUC_PREREQ(3,4)
00137 #  define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
00138 # else
00139 #  define OP_WARN_UNUSED_RESULT
00140 # endif
00141 # if OP_GNUC_PREREQ(3,4)
00142 #  define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
00143 # else
00144 #  define OP_ARG_NONNULL(_x)
00145 # endif
00146 
00158 
00160 #define OP_FALSE         (-1)
00161 /*Currently not used externally.*/
00162 #define OP_EOF           (-2)
00163 
00165 #define OP_HOLE          (-3)
00166 
00168 #define OP_EREAD         (-128)
00169 
00172 #define OP_EFAULT        (-129)
00173 
00175 #define OP_EIMPL         (-130)
00176 
00177 #define OP_EINVAL        (-131)
00178 
00182 #define OP_ENOTFORMAT    (-132)
00183 
00185 #define OP_EBADHEADER    (-133)
00186 
00187 #define OP_EVERSION      (-134)
00188 /*Currently not used at all.*/
00189 #define OP_ENOTAUDIO     (-135)
00190 
00193 #define OP_EBADPACKET    (-136)
00194 
00197 #define OP_EBADLINK      (-137)
00198 
00199 #define OP_ENOSEEK       (-138)
00200 
00201 #define OP_EBADTIMESTAMP (-139)
00202 
00205 
00208 
00210 #define OPUS_CHANNEL_COUNT_MAX (255)
00211 
00215 struct OpusHead{
00225   int           version;
00227   int           channel_count;
00230   unsigned      pre_skip;
00237   opus_uint32   input_sample_rate;
00244   int           output_gain;
00251   int           mapping_family;
00253   int           stream_count;
00260   int           coupled_count;
00268   unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
00269 };
00270 
00301 struct OpusTags{
00303   char **user_comments;
00305   int   *comment_lengths;
00307   int    comments;
00310   char  *vendor;
00311 };
00312 
00315 
00318 #define OP_PIC_FORMAT_UNKNOWN (-1)
00319 
00320 #define OP_PIC_FORMAT_URL     (0)
00321 
00322 #define OP_PIC_FORMAT_JPEG    (1)
00323 
00324 #define OP_PIC_FORMAT_PNG     (2)
00325 
00326 #define OP_PIC_FORMAT_GIF     (3)
00327 
00331 struct OpusPictureTag{
00358   opus_int32     type;
00365   char          *mime_type;
00367   char          *description;
00369   opus_uint32    width;
00371   opus_uint32    height;
00374   opus_uint32    depth;
00377   opus_uint32    colors;
00379   opus_uint32    data_length;
00381   unsigned char *data;
00391   int            format;
00392 };
00393 
00402 
00428 OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
00429  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
00430 
00445 ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
00446  OP_ARG_NONNULL(1);
00447 
00462 OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
00463  const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
00464 
00472 int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);
00473 
00478 void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
00479 
00491 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
00492  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
00493 
00504 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
00505  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00506 
00520 int opus_tags_set_binary_suffix(OpusTags *_tags,
00521  const unsigned char *_data,int _len) OP_ARG_NONNULL(1);
00522 
00538 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
00539  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00540 
00548 int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
00549  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00550 
00556 const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,
00557  int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00558 
00574 int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)
00575  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00576 
00592 int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)
00593  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00594 
00600 void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
00601 
00611 int opus_tagcompare(const char *_tag_name,const char *_comment);
00612 
00626 int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);
00627 
00658 OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,
00659  const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
00660 
00665 void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
00666 
00672 void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
00673 
00677 
00689 
00692 /*These are the raw numbers used to define the request codes.
00693   They should not be used directly.*/
00694 #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
00695 #define OP_HTTP_PROXY_HOST_REQUEST            (6528)
00696 #define OP_HTTP_PROXY_PORT_REQUEST            (6592)
00697 #define OP_HTTP_PROXY_USER_REQUEST            (6656)
00698 #define OP_HTTP_PROXY_PASS_REQUEST            (6720)
00699 #define OP_GET_SERVER_INFO_REQUEST            (6784)
00700 
00701 #define OP_URL_OPT(_request) ((char *)(_request))
00702 
00703 /*These macros trigger compilation errors or warnings if the wrong types are
00704    provided to one of the URL options.*/
00705 #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
00706 #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
00707 #define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))
00708 
00712 struct OpusServerInfo{
00716   char        *name;
00720   char        *description;
00724   char        *genre;
00728   char        *url;
00731   char        *server;
00735   char        *content_type;
00739   opus_int32   bitrate_kbps;
00744   int          is_public;
00749   int          is_ssl;
00750 };
00751 
00756 void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);
00757 
00764 void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
00765 
00772 #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
00773  OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
00774 
00783 #define OP_HTTP_PROXY_HOST(_host) \
00784  OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
00785 
00796 #define OP_HTTP_PROXY_PORT(_port) \
00797  OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
00798 
00809 #define OP_HTTP_PROXY_USER(_user) \
00810  OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)
00811 
00822 #define OP_HTTP_PROXY_PASS(_pass) \
00823  OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)
00824 
00843 #define OP_GET_SERVER_INFO(_info) \
00844  OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
00845 
00848 
00860 
00869 typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
00870 
00880 typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
00881 
00884 typedef opus_int64 (*op_tell_func)(void *_stream);
00885 
00890 typedef int (*op_close_func)(void *_stream);
00891 
00901 struct OpusFileCallbacks{
00904   op_read_func  read;
00907   op_seek_func  seek;
00910   op_tell_func  tell;
00913   op_close_func close;
00914 };
00915 
00933 OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
00934  const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
00935  OP_ARG_NONNULL(3);
00936 
00950 OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
00951  int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
00952 
00972 OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
00973  const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
00974  OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
00975 
00986 OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
00987  const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
00988 
01012 OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
01013  const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
01014 
01034 OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
01035  const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
01036 
01039 
01049 
01080 int op_test(OpusHead *_head,
01081  const unsigned char *_initial_data,size_t _initial_bytes);
01082 
01092 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
01093  OP_ARG_NONNULL(1);
01094 
01103 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
01104  size_t _size,int *_error);
01105 
01132 OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
01133  int *_error,va_list _ap) OP_ARG_NONNULL(1);
01134 
01154 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
01155  int *_error,...) OP_ARG_NONNULL(1);
01156 
01236 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
01237  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
01238  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
01239 
01250 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
01251  OP_ARG_NONNULL(1);
01252 
01262 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
01263  size_t _size,int *_error);
01264 
01293 OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
01294  int *_error,va_list _ap) OP_ARG_NONNULL(1);
01295 
01317 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
01318  int *_error,...) OP_ARG_NONNULL(1);
01319 
01385 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
01386  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
01387  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
01388 
01415 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
01416 
01419 void op_free(OggOpusFile *_of);
01420 
01423 
01441 
01456 int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
01457 
01466 int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
01467 
01481 opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01482 
01498 int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01499 
01520 opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01521 
01538 ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01539 
01554 const OpusHead *op_head(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01555 
01572 const OpusTags *op_tags(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01573 
01589 int op_current_link(const OggOpusFile *_of) OP_ARG_NONNULL(1);
01590 
01611 opus_int32 op_bitrate(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
01612 
01624 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
01625 
01630 opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
01631 
01639 ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
01640 
01643 
01671 
01687 int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
01688 
01703 int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
01704 
01707 
01748 
01751 #define OP_DEC_FORMAT_SHORT (7008)
01752 
01754 #define OP_DEC_FORMAT_FLOAT (7040)
01755 
01758 #define OP_DEC_USE_DEFAULT  (6720)
01759 
01791 typedef int (*op_decode_cb_func)(void *_ctx,OpusMSDecoder *_decoder,void *_pcm,
01792  const ogg_packet *_op,int _nsamples,int _nchannels,int _format,int _li);
01793 
01815 void op_set_decode_callback(OggOpusFile *_of,
01816  op_decode_cb_func _decode_cb,void *_ctx) OP_ARG_NONNULL(1);
01817 
01821 #define OP_HEADER_GAIN   (0)
01822 
01825 #define OP_ALBUM_GAIN    (3007)
01826 
01829 #define OP_TRACK_GAIN    (3008)
01830 
01833 #define OP_ABSOLUTE_GAIN (3009)
01834 
01852 int op_set_gain_offset(OggOpusFile *_of,
01853  int _gain_type,opus_int32 _gain_offset_q8) OP_ARG_NONNULL(1);
01854 
01865 void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
01866 
01947 OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
01948  opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
01949 
02028 OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
02029  float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
02030 
02089 OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
02090  opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
02091 
02150 OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
02151  float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
02152 
02155 
02156 # if OP_GNUC_PREREQ(4,0)
02157 #  pragma GCC visibility pop
02158 # endif
02159 
02160 # if defined(__cplusplus)
02161 }
02162 # endif
02163 
02164 #endif
 All Data Structures Variables