opusfile.h 113 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151
  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. function: stdio-based convenience library for opening/seeking/decoding
  13. last mod: $Id: vorbisfile.h 17182 2010-04-29 03:48:32Z xiphmont $
  14. ********************************************************************/
  15. #if !defined(_opusfile_h)
  16. # define _opusfile_h (1)
  17. /**\mainpage
  18. \section Introduction
  19. This is the documentation for the <tt>libopusfile</tt> C API.
  20. The <tt>libopusfile</tt> package provides a convenient high-level API for
  21. decoding and basic manipulation of all Ogg Opus audio streams.
  22. <tt>libopusfile</tt> is implemented as a layer on top of Xiph.Org's
  23. reference
  24. <tt><a href="https://www.xiph.org/ogg/doc/libogg/reference.html">libogg</a></tt>
  25. and
  26. <tt><a href="https://opus-codec.org/docs/opus_api-1.3.1/">libopus</a></tt>
  27. libraries.
  28. <tt>libopusfile</tt> provides several sets of built-in routines for
  29. file/stream access, and may also use custom stream I/O routines provided by
  30. the embedded environment.
  31. There are built-in I/O routines provided for ANSI-compliant
  32. <code>stdio</code> (<code>FILE *</code>), memory buffers, and URLs
  33. (including <file:> URLs, plus optionally <http:> and <https:> URLs).
  34. \section Organization
  35. The main API is divided into several sections:
  36. - \ref stream_open_close
  37. - \ref stream_info
  38. - \ref stream_decoding
  39. - \ref stream_seeking
  40. Several additional sections are not tied to the main API.
  41. - \ref stream_callbacks
  42. - \ref header_info
  43. - \ref error_codes
  44. \section Overview
  45. The <tt>libopusfile</tt> API always decodes files to 48&nbsp;kHz.
  46. The original sample rate is not preserved by the lossy compression, though
  47. it is stored in the header to allow you to resample to it after decoding
  48. (the <tt>libopusfile</tt> API does not currently provide a resampler,
  49. but the
  50. <a href="https://www.speex.org/docs/manual/speex-manual/node7.html#SECTION00760000000000000000">the
  51. Speex resampler</a> is a good choice if you need one).
  52. In general, if you are playing back the audio, you should leave it at
  53. 48&nbsp;kHz, provided your audio hardware supports it.
  54. When decoding to a file, it may be worth resampling back to the original
  55. sample rate, so as not to surprise users who might not expect the sample
  56. rate to change after encoding to Opus and decoding.
  57. Opus files can contain anywhere from 1 to 255 channels of audio.
  58. The channel mappings for up to 8 channels are the same as the
  59. <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
  60. mappings</a>.
  61. A special stereo API can convert everything to 2 channels, making it simple
  62. to support multichannel files in an application which only has stereo
  63. output.
  64. Although the <tt>libopusfile</tt> ABI provides support for the theoretical
  65. maximum number of channels, the current implementation does not support
  66. files with more than 8 channels, as they do not have well-defined channel
  67. mappings.
  68. Like all Ogg files, Opus files may be "chained".
  69. That is, multiple Opus files may be combined into a single, longer file just
  70. by concatenating the original files.
  71. This is commonly done in internet radio streaming, as it allows the title
  72. and artist to be updated each time the song changes, since each link in the
  73. chain includes its own set of metadata.
  74. <tt>libopusfile</tt> fully supports chained files.
  75. It will decode the first Opus stream found in each link of a chained file
  76. (ignoring any other streams that might be concurrently multiplexed with it,
  77. such as a video stream).
  78. The channel count can also change between links.
  79. If your application is not prepared to deal with this, it can use the stereo
  80. API to ensure the audio from all links will always get decoded into a
  81. common format.
  82. Since <tt>libopusfile</tt> always decodes to 48&nbsp;kHz, you do not have to
  83. worry about the sample rate changing between links (as was possible with
  84. Vorbis).
  85. This makes application support for chained files with <tt>libopusfile</tt>
  86. very easy.*/
  87. # if defined(__cplusplus)
  88. extern "C" {
  89. # endif
  90. # include <stdarg.h>
  91. # include <stdio.h>
  92. # include <ogg/ogg.h>
  93. # include <opus_multistream.h>
  94. /**@cond PRIVATE*/
  95. /*Enable special features for gcc and gcc-compatible compilers.*/
  96. # if !defined(OP_GNUC_PREREQ)
  97. # if defined(__GNUC__)&&defined(__GNUC_MINOR__)
  98. # define OP_GNUC_PREREQ(_maj,_min) \
  99. ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
  100. # else
  101. # define OP_GNUC_PREREQ(_maj,_min) 0
  102. # endif
  103. # endif
  104. # if OP_GNUC_PREREQ(4,0)
  105. # pragma GCC visibility push(default)
  106. # endif
  107. typedef struct OpusHead OpusHead;
  108. typedef struct OpusTags OpusTags;
  109. typedef struct OpusPictureTag OpusPictureTag;
  110. typedef struct OpusServerInfo OpusServerInfo;
  111. typedef struct OpusFileCallbacks OpusFileCallbacks;
  112. typedef struct OggOpusFile OggOpusFile;
  113. /*Warning attributes for libopusfile functions.*/
  114. # if OP_GNUC_PREREQ(3,4)
  115. # define OP_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
  116. # else
  117. # define OP_WARN_UNUSED_RESULT
  118. # endif
  119. # if OP_GNUC_PREREQ(3,4)
  120. # define OP_ARG_NONNULL(_x) __attribute__((__nonnull__(_x)))
  121. # else
  122. # define OP_ARG_NONNULL(_x)
  123. # endif
  124. /**@endcond*/
  125. /**\defgroup error_codes Error Codes*/
  126. /**@{*/
  127. /**\name List of possible error codes
  128. Many of the functions in this library return a negative error code when a
  129. function fails.
  130. This list provides a brief explanation of the common errors.
  131. See each individual function for more details on what a specific error code
  132. means in that context.*/
  133. /**@{*/
  134. /**A request did not succeed.*/
  135. #define OP_FALSE (-1)
  136. /**Currently not used externally.**/
  137. #define OP_EOF (-2)
  138. /**There was a hole in the page sequence numbers (e.g., a page was corrupt or
  139. missing).*/
  140. #define OP_HOLE (-3)
  141. /**An underlying read, seek, or tell operation failed when it should have
  142. succeeded.*/
  143. #define OP_EREAD (-128)
  144. /**A <code>NULL</code> pointer was passed where one was unexpected, or an
  145. internal memory allocation failed, or an internal library error was
  146. encountered.*/
  147. #define OP_EFAULT (-129)
  148. /**The stream used a feature that is not implemented, such as an unsupported
  149. channel family.*/
  150. #define OP_EIMPL (-130)
  151. /**One or more parameters to a function were invalid.*/
  152. #define OP_EINVAL (-131)
  153. /**A purported Ogg Opus stream did not begin with an Ogg page, a purported
  154. header packet did not start with one of the required strings, "OpusHead" or
  155. "OpusTags", or a link in a chained file was encountered that did not
  156. contain any logical Opus streams.*/
  157. #define OP_ENOTFORMAT (-132)
  158. /**A required header packet was not properly formatted, contained illegal
  159. values, or was missing altogether.*/
  160. #define OP_EBADHEADER (-133)
  161. /**The ID header contained an unrecognized version number.*/
  162. #define OP_EVERSION (-134)
  163. /**Currently not used at all.**/
  164. #define OP_ENOTAUDIO (-135)
  165. /**An audio packet failed to decode properly.
  166. This is usually caused by a multistream Ogg packet where the durations of
  167. the individual Opus packets contained in it are not all the same.*/
  168. #define OP_EBADPACKET (-136)
  169. /**We failed to find data we had seen before, or the bitstream structure was
  170. sufficiently malformed that seeking to the target destination was
  171. impossible.*/
  172. #define OP_EBADLINK (-137)
  173. /**An operation that requires seeking was requested on an unseekable stream.*/
  174. #define OP_ENOSEEK (-138)
  175. /**The first or last granule position of a link failed basic validity checks.*/
  176. #define OP_EBADTIMESTAMP (-139)
  177. /**@}*/
  178. /**@}*/
  179. /**\defgroup header_info Header Information*/
  180. /**@{*/
  181. /**The maximum number of channels in an Ogg Opus stream.*/
  182. #define OPUS_CHANNEL_COUNT_MAX (255)
  183. /**Ogg Opus bitstream information.
  184. This contains the basic playback parameters for a stream, and corresponds to
  185. the initial ID header packet of an Ogg Opus stream.*/
  186. struct OpusHead{
  187. /**The Ogg Opus format version, in the range 0...255.
  188. The top 4 bits represent a "major" version, and the bottom four bits
  189. represent backwards-compatible "minor" revisions.
  190. The current specification describes version 1.
  191. This library will recognize versions up through 15 as backwards compatible
  192. with the current specification.
  193. An earlier draft of the specification described a version 0, but the only
  194. difference between version 1 and version 0 is that version 0 did
  195. not specify the semantics for handling the version field.*/
  196. int version;
  197. /**The number of channels, in the range 1...255.*/
  198. int channel_count;
  199. /**The number of samples that should be discarded from the beginning of the
  200. stream.*/
  201. unsigned pre_skip;
  202. /**The sampling rate of the original input.
  203. All Opus audio is coded at 48 kHz, and should also be decoded at 48 kHz
  204. for playback (unless the target hardware does not support this sampling
  205. rate).
  206. However, this field may be used to resample the audio back to the original
  207. sampling rate, for example, when saving the output to a file.*/
  208. opus_uint32 input_sample_rate;
  209. /**The gain to apply to the decoded output, in dB, as a Q8 value in the range
  210. -32768...32767.
  211. The <tt>libopusfile</tt> API will automatically apply this gain to the
  212. decoded output before returning it, scaling it by
  213. <code>pow(10,output_gain/(20.0*256))</code>.
  214. You can adjust this behavior with op_set_gain_offset().*/
  215. int output_gain;
  216. /**The channel mapping family, in the range 0...255.
  217. Channel mapping family 0 covers mono or stereo in a single stream.
  218. Channel mapping family 1 covers 1 to 8 channels in one or more streams,
  219. using the Vorbis speaker assignments.
  220. Channel mapping family 255 covers 1 to 255 channels in one or more
  221. streams, but without any defined speaker assignment.*/
  222. int mapping_family;
  223. /**The number of Opus streams in each Ogg packet, in the range 1...255.*/
  224. int stream_count;
  225. /**The number of coupled Opus streams in each Ogg packet, in the range
  226. 0...127.
  227. This must satisfy <code>0 <= coupled_count <= stream_count</code> and
  228. <code>coupled_count + stream_count <= 255</code>.
  229. The coupled streams appear first, before all uncoupled streams, in an Ogg
  230. Opus packet.*/
  231. int coupled_count;
  232. /**The mapping from coded stream channels to output channels.
  233. Let <code>index=mapping[k]</code> be the value for channel <code>k</code>.
  234. If <code>index<2*coupled_count</code>, then it refers to the left channel
  235. from stream <code>(index/2)</code> if even, and the right channel from
  236. stream <code>(index/2)</code> if odd.
  237. Otherwise, it refers to the output of the uncoupled stream
  238. <code>(index-coupled_count)</code>.*/
  239. unsigned char mapping[OPUS_CHANNEL_COUNT_MAX];
  240. };
  241. /**The metadata from an Ogg Opus stream.
  242. This structure holds the in-stream metadata corresponding to the 'comment'
  243. header packet of an Ogg Opus stream.
  244. The comment header is meant to be used much like someone jotting a quick
  245. note on the label of a CD.
  246. It should be a short, to the point text note that can be more than a couple
  247. words, but not more than a short paragraph.
  248. The metadata is stored as a series of (tag, value) pairs, in length-encoded
  249. string vectors, using the same format as Vorbis (without the final "framing
  250. bit"), Theora, and Speex, except for the packet header.
  251. The first occurrence of the '=' character delimits the tag and value.
  252. A particular tag may occur more than once, and order is significant.
  253. The character set encoding for the strings is always UTF-8, but the tag
  254. names are limited to ASCII, and treated as case-insensitive.
  255. See <a href="https://www.xiph.org/vorbis/doc/v-comment.html">the Vorbis
  256. comment header specification</a> for details.
  257. In filling in this structure, <tt>libopusfile</tt> will null-terminate the
  258. #user_comments strings for safety.
  259. However, the bitstream format itself treats them as 8-bit clean vectors,
  260. possibly containing NUL characters, so the #comment_lengths array should be
  261. treated as their authoritative length.
  262. This structure is binary and source-compatible with a
  263. <code>vorbis_comment</code>, and pointers to it may be freely cast to
  264. <code>vorbis_comment</code> pointers, and vice versa.
  265. It is provided as a separate type to avoid introducing a compile-time
  266. dependency on the libvorbis headers.*/
  267. struct OpusTags{
  268. /**The array of comment string vectors.*/
  269. char **user_comments;
  270. /**An array of the corresponding length of each vector, in bytes.*/
  271. int *comment_lengths;
  272. /**The total number of comment streams.*/
  273. int comments;
  274. /**The null-terminated vendor string.
  275. This identifies the software used to encode the stream.*/
  276. char *vendor;
  277. };
  278. /**\name Picture tag image formats*/
  279. /**@{*/
  280. /**The MIME type was not recognized, or the image data did not match the
  281. declared MIME type.*/
  282. #define OP_PIC_FORMAT_UNKNOWN (-1)
  283. /**The MIME type indicates the image data is really a URL.*/
  284. #define OP_PIC_FORMAT_URL (0)
  285. /**The image is a JPEG.*/
  286. #define OP_PIC_FORMAT_JPEG (1)
  287. /**The image is a PNG.*/
  288. #define OP_PIC_FORMAT_PNG (2)
  289. /**The image is a GIF.*/
  290. #define OP_PIC_FORMAT_GIF (3)
  291. /**@}*/
  292. /**The contents of a METADATA_BLOCK_PICTURE tag.*/
  293. struct OpusPictureTag{
  294. /**The picture type according to the ID3v2 APIC frame:
  295. <ol start="0">
  296. <li>Other</li>
  297. <li>32x32 pixels 'file icon' (PNG only)</li>
  298. <li>Other file icon</li>
  299. <li>Cover (front)</li>
  300. <li>Cover (back)</li>
  301. <li>Leaflet page</li>
  302. <li>Media (e.g. label side of CD)</li>
  303. <li>Lead artist/lead performer/soloist</li>
  304. <li>Artist/performer</li>
  305. <li>Conductor</li>
  306. <li>Band/Orchestra</li>
  307. <li>Composer</li>
  308. <li>Lyricist/text writer</li>
  309. <li>Recording Location</li>
  310. <li>During recording</li>
  311. <li>During performance</li>
  312. <li>Movie/video screen capture</li>
  313. <li>A bright colored fish</li>
  314. <li>Illustration</li>
  315. <li>Band/artist logotype</li>
  316. <li>Publisher/Studio logotype</li>
  317. </ol>
  318. Others are reserved and should not be used.
  319. There may only be one each of picture type 1 and 2 in a file.*/
  320. opus_int32 type;
  321. /**The MIME type of the picture, in printable ASCII characters 0x20-0x7E.
  322. The MIME type may also be <code>"-->"</code> to signify that the data part
  323. is a URL pointing to the picture instead of the picture data itself.
  324. In this case, a terminating NUL is appended to the URL string in #data,
  325. but #data_length is set to the length of the string excluding that
  326. terminating NUL.*/
  327. char *mime_type;
  328. /**The description of the picture, in UTF-8.*/
  329. char *description;
  330. /**The width of the picture in pixels.*/
  331. opus_uint32 width;
  332. /**The height of the picture in pixels.*/
  333. opus_uint32 height;
  334. /**The color depth of the picture in bits-per-pixel (<em>not</em>
  335. bits-per-channel).*/
  336. opus_uint32 depth;
  337. /**For indexed-color pictures (e.g., GIF), the number of colors used, or 0
  338. for non-indexed pictures.*/
  339. opus_uint32 colors;
  340. /**The length of the picture data in bytes.*/
  341. opus_uint32 data_length;
  342. /**The binary picture data.*/
  343. unsigned char *data;
  344. /**The format of the picture data, if known.
  345. One of
  346. <ul>
  347. <li>#OP_PIC_FORMAT_UNKNOWN,</li>
  348. <li>#OP_PIC_FORMAT_URL,</li>
  349. <li>#OP_PIC_FORMAT_JPEG,</li>
  350. <li>#OP_PIC_FORMAT_PNG, or</li>
  351. <li>#OP_PIC_FORMAT_GIF.</li>
  352. </ul>*/
  353. int format;
  354. };
  355. /**\name Functions for manipulating header data
  356. These functions manipulate the #OpusHead and #OpusTags structures,
  357. which describe the audio parameters and tag-value metadata, respectively.
  358. These can be used to query the headers returned by <tt>libopusfile</tt>, or
  359. to parse Opus headers from sources other than an Ogg Opus stream, provided
  360. they use the same format.*/
  361. /**@{*/
  362. /**Parses the contents of the ID header packet of an Ogg Opus stream.
  363. \param[out] _head Returns the contents of the parsed packet.
  364. The contents of this structure are untouched on error.
  365. This may be <code>NULL</code> to merely test the header
  366. for validity.
  367. \param[in] _data The contents of the ID header packet.
  368. \param _len The number of bytes of data in the ID header packet.
  369. \return 0 on success or a negative value on error.
  370. \retval #OP_ENOTFORMAT If the data does not start with the "OpusHead"
  371. string.
  372. \retval #OP_EVERSION If the version field signaled a version this library
  373. does not know how to parse.
  374. \retval #OP_EIMPL If the channel mapping family was 255, which general
  375. purpose players should not attempt to play.
  376. \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
  377. Ogg Opus specification:
  378. <ul>
  379. <li>Insufficient data,</li>
  380. <li>Too much data for the known minor versions,</li>
  381. <li>An unrecognized channel mapping family,</li>
  382. <li>Zero channels or too many channels,</li>
  383. <li>Zero coded streams,</li>
  384. <li>Too many coupled streams, or</li>
  385. <li>An invalid channel mapping index.</li>
  386. </ul>*/
  387. OP_WARN_UNUSED_RESULT int opus_head_parse(OpusHead *_head,
  388. const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
  389. /**Converts a granule position to a sample offset for a given Ogg Opus stream.
  390. The sample offset is simply <code>_gp-_head->pre_skip</code>.
  391. Granule position values smaller than OpusHead#pre_skip correspond to audio
  392. that should never be played, and thus have no associated sample offset.
  393. This function returns -1 for such values.
  394. This function also correctly handles extremely large granule positions,
  395. which may have wrapped around to a negative number when stored in a signed
  396. ogg_int64_t value.
  397. \param _head The #OpusHead information from the ID header of the stream.
  398. \param _gp The granule position to convert.
  399. \return The sample offset associated with the given granule position
  400. (counting at a 48 kHz sampling rate), or the special value -1 on
  401. error (i.e., the granule position was smaller than the pre-skip
  402. amount).*/
  403. ogg_int64_t opus_granule_sample(const OpusHead *_head,ogg_int64_t _gp)
  404. OP_ARG_NONNULL(1);
  405. /**Parses the contents of the 'comment' header packet of an Ogg Opus stream.
  406. \param[out] _tags An uninitialized #OpusTags structure.
  407. This returns the contents of the parsed packet.
  408. The contents of this structure are untouched on error.
  409. This may be <code>NULL</code> to merely test the header
  410. for validity.
  411. \param[in] _data The contents of the 'comment' header packet.
  412. \param _len The number of bytes of data in the 'info' header packet.
  413. \retval 0 Success.
  414. \retval #OP_ENOTFORMAT If the data does not start with the "OpusTags"
  415. string.
  416. \retval #OP_EBADHEADER If the contents of the packet otherwise violate the
  417. Ogg Opus specification.
  418. \retval #OP_EFAULT If there wasn't enough memory to store the tags.*/
  419. OP_WARN_UNUSED_RESULT int opus_tags_parse(OpusTags *_tags,
  420. const unsigned char *_data,size_t _len) OP_ARG_NONNULL(2);
  421. /**Performs a deep copy of an #OpusTags structure.
  422. \param _dst The #OpusTags structure to copy into.
  423. If this function fails, the contents of this structure remain
  424. untouched.
  425. \param _src The #OpusTags structure to copy from.
  426. \retval 0 Success.
  427. \retval #OP_EFAULT If there wasn't enough memory to copy the tags.*/
  428. int opus_tags_copy(OpusTags *_dst,const OpusTags *_src) OP_ARG_NONNULL(1);
  429. /**Initializes an #OpusTags structure.
  430. This should be called on a freshly allocated #OpusTags structure before
  431. attempting to use it.
  432. \param _tags The #OpusTags structure to initialize.*/
  433. void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
  434. /**Add a (tag, value) pair to an initialized #OpusTags structure.
  435. \note Neither opus_tags_add() nor opus_tags_add_comment() support values
  436. containing embedded NULs, although the bitstream format does support them.
  437. To add such tags, you will need to manipulate the #OpusTags structure
  438. directly.
  439. \param _tags The #OpusTags structure to add the (tag, value) pair to.
  440. \param _tag A NUL-terminated, case-insensitive, ASCII string containing
  441. the tag to add (without an '=' character).
  442. \param _value A NUL-terminated UTF-8 containing the corresponding value.
  443. \return 0 on success, or a negative value on failure.
  444. \retval #OP_EFAULT An internal memory allocation failed.*/
  445. int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
  446. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
  447. /**Add a comment to an initialized #OpusTags structure.
  448. \note Neither opus_tags_add_comment() nor opus_tags_add() support comments
  449. containing embedded NULs, although the bitstream format does support them.
  450. To add such tags, you will need to manipulate the #OpusTags structure
  451. directly.
  452. \param _tags The #OpusTags structure to add the comment to.
  453. \param _comment A NUL-terminated UTF-8 string containing the comment in
  454. "TAG=value" form.
  455. \return 0 on success, or a negative value on failure.
  456. \retval #OP_EFAULT An internal memory allocation failed.*/
  457. int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
  458. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  459. /**Replace the binary suffix data at the end of the packet (if any).
  460. \param _tags An initialized #OpusTags structure.
  461. \param _data A buffer of binary data to append after the encoded user
  462. comments.
  463. The least significant bit of the first byte of this data must
  464. be set (to ensure the data is preserved by other editors).
  465. \param _len The number of bytes of binary data to append.
  466. This may be zero to remove any existing binary suffix data.
  467. \return 0 on success, or a negative value on error.
  468. \retval #OP_EINVAL \a _len was negative, or \a _len was positive but
  469. \a _data was <code>NULL</code> or the least significant
  470. bit of the first byte was not set.
  471. \retval #OP_EFAULT An internal memory allocation failed.*/
  472. int opus_tags_set_binary_suffix(OpusTags *_tags,
  473. const unsigned char *_data,int _len) OP_ARG_NONNULL(1);
  474. /**Look up a comment value by its tag.
  475. \param _tags An initialized #OpusTags structure.
  476. \param _tag The tag to look up.
  477. \param _count The instance of the tag.
  478. The same tag can appear multiple times, each with a distinct
  479. value, so an index is required to retrieve them all.
  480. The order in which these values appear is significant and
  481. should be preserved.
  482. Use opus_tags_query_count() to get the legal range for the
  483. \a _count parameter.
  484. \return A pointer to the queried tag's value.
  485. This points directly to data in the #OpusTags structure.
  486. It should not be modified or freed by the application, and
  487. modifications to the structure may invalidate the pointer.
  488. \retval NULL If no matching tag is found.*/
  489. const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
  490. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  491. /**Look up the number of instances of a tag.
  492. Call this first when querying for a specific tag and then iterate over the
  493. number of instances with separate calls to opus_tags_query() to retrieve
  494. all the values for that tag in order.
  495. \param _tags An initialized #OpusTags structure.
  496. \param _tag The tag to look up.
  497. \return The number of instances of this particular tag.*/
  498. int opus_tags_query_count(const OpusTags *_tags,const char *_tag)
  499. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  500. /**Retrieve the binary suffix data at the end of the packet (if any).
  501. \param _tags An initialized #OpusTags structure.
  502. \param[out] _len Returns the number of bytes of binary suffix data returned.
  503. \return A pointer to the binary suffix data, or <code>NULL</code> if none
  504. was present.*/
  505. const unsigned char *opus_tags_get_binary_suffix(const OpusTags *_tags,
  506. int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  507. /**Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.
  508. This searches for the first R128_ALBUM_GAIN tag with a valid signed,
  509. 16-bit decimal integer value and returns the value.
  510. This routine is exposed merely for convenience for applications which wish
  511. to do something special with the album gain (i.e., display it).
  512. If you simply wish to apply the album gain instead of the header gain, you
  513. can use op_set_gain_offset() with an #OP_ALBUM_GAIN type and no offset.
  514. \param _tags An initialized #OpusTags structure.
  515. \param[out] _gain_q8 The album gain, in 1/256ths of a dB.
  516. This will lie in the range [-32768,32767], and should
  517. be applied in <em>addition</em> to the header gain.
  518. On error, no value is returned, and the previous
  519. contents remain unchanged.
  520. \return 0 on success, or a negative value on error.
  521. \retval #OP_FALSE There was no album gain available in the given tags.*/
  522. int opus_tags_get_album_gain(const OpusTags *_tags,int *_gain_q8)
  523. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  524. /**Get the track gain from an R128_TRACK_GAIN tag, if one was specified.
  525. This searches for the first R128_TRACK_GAIN tag with a valid signed,
  526. 16-bit decimal integer value and returns the value.
  527. This routine is exposed merely for convenience for applications which wish
  528. to do something special with the track gain (i.e., display it).
  529. If you simply wish to apply the track gain instead of the header gain, you
  530. can use op_set_gain_offset() with an #OP_TRACK_GAIN type and no offset.
  531. \param _tags An initialized #OpusTags structure.
  532. \param[out] _gain_q8 The track gain, in 1/256ths of a dB.
  533. This will lie in the range [-32768,32767], and should
  534. be applied in <em>addition</em> to the header gain.
  535. On error, no value is returned, and the previous
  536. contents remain unchanged.
  537. \return 0 on success, or a negative value on error.
  538. \retval #OP_FALSE There was no track gain available in the given tags.*/
  539. int opus_tags_get_track_gain(const OpusTags *_tags,int *_gain_q8)
  540. OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  541. /**Clears the #OpusTags structure.
  542. This should be called on an #OpusTags structure after it is no longer
  543. needed.
  544. It will free all memory used by the structure members.
  545. \param _tags The #OpusTags structure to clear.*/
  546. void opus_tags_clear(OpusTags *_tags) OP_ARG_NONNULL(1);
  547. /**Check if \a _comment is an instance of a \a _tag_name tag.
  548. \see opus_tagncompare
  549. \param _tag_name A NUL-terminated, case-insensitive, ASCII string containing
  550. the name of the tag to check for (without the terminating
  551. '=' character).
  552. \param _comment The comment string to check.
  553. \return An integer less than, equal to, or greater than zero if \a _comment
  554. is found respectively, to be less than, to match, or be greater
  555. than a "tag=value" string whose tag matches \a _tag_name.*/
  556. int opus_tagcompare(const char *_tag_name,const char *_comment);
  557. /**Check if \a _comment is an instance of a \a _tag_name tag.
  558. This version is slightly more efficient than opus_tagcompare() if the length
  559. of the tag name is already known (e.g., because it is a constant).
  560. \see opus_tagcompare
  561. \param _tag_name A case-insensitive ASCII string containing the name of the
  562. tag to check for (without the terminating '=' character).
  563. \param _tag_len The number of characters in the tag name.
  564. This must be non-negative.
  565. \param _comment The comment string to check.
  566. \return An integer less than, equal to, or greater than zero if \a _comment
  567. is found respectively, to be less than, to match, or be greater
  568. than a "tag=value" string whose tag matches the first \a _tag_len
  569. characters of \a _tag_name.*/
  570. int opus_tagncompare(const char *_tag_name,int _tag_len,const char *_comment);
  571. /**Parse a single METADATA_BLOCK_PICTURE tag.
  572. This decodes the BASE64-encoded content of the tag and returns a structure
  573. with the MIME type, description, image parameters (if known), and the
  574. compressed image data.
  575. If the MIME type indicates the presence of an image format we recognize
  576. (JPEG, PNG, or GIF) and the actual image data contains the magic signature
  577. associated with that format, then the OpusPictureTag::format field will be
  578. set to the corresponding format.
  579. This is provided as a convenience to avoid requiring applications to parse
  580. the MIME type and/or do their own format detection for the commonly used
  581. formats.
  582. In this case, we also attempt to extract the image parameters directly from
  583. the image data (overriding any that were present in the tag, which the
  584. specification says applications are not meant to rely on).
  585. The application must still provide its own support for actually decoding the
  586. image data and, if applicable, retrieving that data from URLs.
  587. \param[out] _pic Returns the parsed picture data.
  588. No sanitation is done on the type, MIME type, or
  589. description fields, so these might return invalid values.
  590. The contents of this structure are left unmodified on
  591. failure.
  592. \param _tag The METADATA_BLOCK_PICTURE tag contents.
  593. The leading "METADATA_BLOCK_PICTURE=" portion is optional,
  594. to allow the function to be used on either directly on the
  595. values in OpusTags::user_comments or on the return value
  596. of opus_tags_query().
  597. \return 0 on success or a negative value on error.
  598. \retval #OP_ENOTFORMAT The METADATA_BLOCK_PICTURE contents were not valid.
  599. \retval #OP_EFAULT There was not enough memory to store the picture tag
  600. contents.*/
  601. OP_WARN_UNUSED_RESULT int opus_picture_tag_parse(OpusPictureTag *_pic,
  602. const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  603. /**Initializes an #OpusPictureTag structure.
  604. This should be called on a freshly allocated #OpusPictureTag structure
  605. before attempting to use it.
  606. \param _pic The #OpusPictureTag structure to initialize.*/
  607. void opus_picture_tag_init(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
  608. /**Clears the #OpusPictureTag structure.
  609. This should be called on an #OpusPictureTag structure after it is no longer
  610. needed.
  611. It will free all memory used by the structure members.
  612. \param _pic The #OpusPictureTag structure to clear.*/
  613. void opus_picture_tag_clear(OpusPictureTag *_pic) OP_ARG_NONNULL(1);
  614. /**@}*/
  615. /**@}*/
  616. /**\defgroup url_options URL Reading Options*/
  617. /**@{*/
  618. /**\name URL reading options
  619. Options for op_url_stream_create() and associated functions.
  620. These allow you to provide proxy configuration parameters, skip SSL
  621. certificate checks, etc.
  622. Options are processed in order, and if the same option is passed multiple
  623. times, only the value specified by the last occurrence has an effect
  624. (unless otherwise specified).
  625. They may be expanded in the future.*/
  626. /**@{*/
  627. /**@cond PRIVATE*/
  628. /*These are the raw numbers used to define the request codes.
  629. They should not be used directly.*/
  630. #define OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST (6464)
  631. #define OP_HTTP_PROXY_HOST_REQUEST (6528)
  632. #define OP_HTTP_PROXY_PORT_REQUEST (6592)
  633. #define OP_HTTP_PROXY_USER_REQUEST (6656)
  634. #define OP_HTTP_PROXY_PASS_REQUEST (6720)
  635. #define OP_GET_SERVER_INFO_REQUEST (6784)
  636. #define OP_URL_OPT(_request) ((char *)(_request))
  637. /*These macros trigger compilation errors or warnings if the wrong types are
  638. provided to one of the URL options.*/
  639. #define OP_CHECK_INT(_x) ((void)((_x)==(opus_int32)0),(opus_int32)(_x))
  640. #define OP_CHECK_CONST_CHAR_PTR(_x) ((_x)+((_x)-(const char *)(_x)))
  641. #define OP_CHECK_SERVER_INFO_PTR(_x) ((_x)+((_x)-(OpusServerInfo *)(_x)))
  642. /**@endcond*/
  643. /**HTTP/Shoutcast/Icecast server information associated with a URL.*/
  644. struct OpusServerInfo{
  645. /**The name of the server (icy-name/ice-name).
  646. This is <code>NULL</code> if there was no <code>icy-name</code> or
  647. <code>ice-name</code> header.*/
  648. char *name;
  649. /**A short description of the server (icy-description/ice-description).
  650. This is <code>NULL</code> if there was no <code>icy-description</code> or
  651. <code>ice-description</code> header.*/
  652. char *description;
  653. /**The genre the server falls under (icy-genre/ice-genre).
  654. This is <code>NULL</code> if there was no <code>icy-genre</code> or
  655. <code>ice-genre</code> header.*/
  656. char *genre;
  657. /**The homepage for the server (icy-url/ice-url).
  658. This is <code>NULL</code> if there was no <code>icy-url</code> or
  659. <code>ice-url</code> header.*/
  660. char *url;
  661. /**The software used by the origin server (Server).
  662. This is <code>NULL</code> if there was no <code>Server</code> header.*/
  663. char *server;
  664. /**The media type of the entity sent to the recepient (Content-Type).
  665. This is <code>NULL</code> if there was no <code>Content-Type</code>
  666. header.*/
  667. char *content_type;
  668. /**The nominal stream bitrate in kbps (icy-br/ice-bitrate).
  669. This is <code>-1</code> if there was no <code>icy-br</code> or
  670. <code>ice-bitrate</code> header.*/
  671. opus_int32 bitrate_kbps;
  672. /**Flag indicating whether the server is public (<code>1</code>) or not
  673. (<code>0</code>) (icy-pub/ice-public).
  674. This is <code>-1</code> if there was no <code>icy-pub</code> or
  675. <code>ice-public</code> header.*/
  676. int is_public;
  677. /**Flag indicating whether the server is using HTTPS instead of HTTP.
  678. This is <code>0</code> unless HTTPS is being used.
  679. This may not match the protocol used in the original URL if there were
  680. redirections.*/
  681. int is_ssl;
  682. };
  683. /**Initializes an #OpusServerInfo structure.
  684. All fields are set as if the corresponding header was not available.
  685. \param _info The #OpusServerInfo structure to initialize.
  686. \note If you use this function, you must link against <tt>libopusurl</tt>.*/
  687. void opus_server_info_init(OpusServerInfo *_info) OP_ARG_NONNULL(1);
  688. /**Clears the #OpusServerInfo structure.
  689. This should be called on an #OpusServerInfo structure after it is no longer
  690. needed.
  691. It will free all memory used by the structure members.
  692. \param _info The #OpusServerInfo structure to clear.
  693. \note If you use this function, you must link against <tt>libopusurl</tt>.*/
  694. void opus_server_info_clear(OpusServerInfo *_info) OP_ARG_NONNULL(1);
  695. /**Skip the certificate check when connecting via TLS/SSL (https).
  696. \param _b <code>opus_int32</code>: Whether or not to skip the certificate
  697. check.
  698. The check will be skipped if \a _b is non-zero, and will not be
  699. skipped if \a _b is zero.
  700. \hideinitializer*/
  701. #define OP_SSL_SKIP_CERTIFICATE_CHECK(_b) \
  702. OP_URL_OPT(OP_SSL_SKIP_CERTIFICATE_CHECK_REQUEST),OP_CHECK_INT(_b)
  703. /**Proxy connections through the given host.
  704. If no port is specified via #OP_HTTP_PROXY_PORT, the port number defaults
  705. to 8080 (http-alt).
  706. All proxy parameters are ignored for non-http and non-https URLs.
  707. \param _host <code>const char *</code>: The proxy server hostname.
  708. This may be <code>NULL</code> to disable the use of a proxy
  709. server.
  710. \hideinitializer*/
  711. #define OP_HTTP_PROXY_HOST(_host) \
  712. OP_URL_OPT(OP_HTTP_PROXY_HOST_REQUEST),OP_CHECK_CONST_CHAR_PTR(_host)
  713. /**Use the given port when proxying connections.
  714. This option only has an effect if #OP_HTTP_PROXY_HOST is specified with a
  715. non-<code>NULL</code> \a _host.
  716. If this option is not provided, the proxy port number defaults to 8080
  717. (http-alt).
  718. All proxy parameters are ignored for non-http and non-https URLs.
  719. \param _port <code>opus_int32</code>: The proxy server port.
  720. This must be in the range 0...65535 (inclusive), or the
  721. URL function this is passed to will fail.
  722. \hideinitializer*/
  723. #define OP_HTTP_PROXY_PORT(_port) \
  724. OP_URL_OPT(OP_HTTP_PROXY_PORT_REQUEST),OP_CHECK_INT(_port)
  725. /**Use the given user name for authentication when proxying connections.
  726. All proxy parameters are ignored for non-http and non-https URLs.
  727. \param _user const char *: The proxy server user name.
  728. This may be <code>NULL</code> to disable proxy
  729. authentication.
  730. A non-<code>NULL</code> value only has an effect
  731. if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_PASS
  732. are also specified with non-<code>NULL</code>
  733. arguments.
  734. \hideinitializer*/
  735. #define OP_HTTP_PROXY_USER(_user) \
  736. OP_URL_OPT(OP_HTTP_PROXY_USER_REQUEST),OP_CHECK_CONST_CHAR_PTR(_user)
  737. /**Use the given password for authentication when proxying connections.
  738. All proxy parameters are ignored for non-http and non-https URLs.
  739. \param _pass const char *: The proxy server password.
  740. This may be <code>NULL</code> to disable proxy
  741. authentication.
  742. A non-<code>NULL</code> value only has an effect
  743. if #OP_HTTP_PROXY_HOST and #OP_HTTP_PROXY_USER
  744. are also specified with non-<code>NULL</code>
  745. arguments.
  746. \hideinitializer*/
  747. #define OP_HTTP_PROXY_PASS(_pass) \
  748. OP_URL_OPT(OP_HTTP_PROXY_PASS_REQUEST),OP_CHECK_CONST_CHAR_PTR(_pass)
  749. /**Parse information about the streaming server (if any) and return it.
  750. Very little validation is done.
  751. In particular, OpusServerInfo::url may not be a valid URL,
  752. OpusServerInfo::bitrate_kbps may not really be in kbps, and
  753. OpusServerInfo::content_type may not be a valid MIME type.
  754. The character set of the string fields is not specified anywhere, and should
  755. not be assumed to be valid UTF-8.
  756. \param _info OpusServerInfo *: Returns information about the server.
  757. If there is any error opening the stream, the
  758. contents of this structure remain
  759. unmodified.
  760. On success, fills in the structure with the
  761. server information that was available, if
  762. any.
  763. After a successful return, the contents of
  764. this structure should be freed by calling
  765. opus_server_info_clear().
  766. \hideinitializer*/
  767. #define OP_GET_SERVER_INFO(_info) \
  768. OP_URL_OPT(OP_GET_SERVER_INFO_REQUEST),OP_CHECK_SERVER_INFO_PTR(_info)
  769. /**@}*/
  770. /**@}*/
  771. /**\defgroup stream_callbacks Abstract Stream Reading Interface*/
  772. /**@{*/
  773. /**\name Functions for reading from streams
  774. These functions define the interface used to read from and seek in a stream
  775. of data.
  776. A stream does not need to implement seeking, but the decoder will not be
  777. able to seek if it does not do so.
  778. These functions also include some convenience routines for working with
  779. standard <code>FILE</code> pointers, complete streams stored in a single
  780. block of memory, or URLs.*/
  781. /**@{*/
  782. /**Reads up to \a _nbytes bytes of data from \a _stream.
  783. \param _stream The stream to read from.
  784. \param[out] _ptr The buffer to store the data in.
  785. \param _nbytes The maximum number of bytes to read.
  786. This function may return fewer, though it will not
  787. return zero unless it reaches end-of-file.
  788. \return The number of bytes successfully read, or a negative value on
  789. error.*/
  790. typedef int (*op_read_func)(void *_stream,unsigned char *_ptr,int _nbytes);
  791. /**Sets the position indicator for \a _stream.
  792. The new position, measured in bytes, is obtained by adding \a _offset
  793. bytes to the position specified by \a _whence.
  794. If \a _whence is set to <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or
  795. <code>SEEK_END</code>, the offset is relative to the start of the stream,
  796. the current position indicator, or end-of-file, respectively.
  797. \retval 0 Success.
  798. \retval -1 Seeking is not supported or an error occurred.
  799. <code>errno</code> need not be set.*/
  800. typedef int (*op_seek_func)(void *_stream,opus_int64 _offset,int _whence);
  801. /**Obtains the current value of the position indicator for \a _stream.
  802. \return The current position indicator.*/
  803. typedef opus_int64 (*op_tell_func)(void *_stream);
  804. /**Closes the underlying stream.
  805. \retval 0 Success.
  806. \retval EOF An error occurred.
  807. <code>errno</code> need not be set.*/
  808. typedef int (*op_close_func)(void *_stream);
  809. /**The callbacks used to access non-<code>FILE</code> stream resources.
  810. The function prototypes are basically the same as for the stdio functions
  811. <code>fread()</code>, <code>fseek()</code>, <code>ftell()</code>, and
  812. <code>fclose()</code>.
  813. The differences are that the <code>FILE *</code> arguments have been
  814. replaced with a <code>void *</code>, which is to be used as a pointer to
  815. whatever internal data these functions might need, that #seek and #tell
  816. take and return 64-bit offsets, and that #seek <em>must</em> return -1 if
  817. the stream is unseekable.*/
  818. struct OpusFileCallbacks{
  819. /**Used to read data from the stream.
  820. This must not be <code>NULL</code>.*/
  821. op_read_func read;
  822. /**Used to seek in the stream.
  823. This may be <code>NULL</code> if seeking is not implemented.*/
  824. op_seek_func seek;
  825. /**Used to return the current read position in the stream.
  826. This may be <code>NULL</code> if seeking is not implemented.*/
  827. op_tell_func tell;
  828. /**Used to close the stream when the decoder is freed.
  829. This may be <code>NULL</code> to leave the stream open.*/
  830. op_close_func close;
  831. };
  832. /**Opens a stream with <code>fopen()</code> and fills in a set of callbacks
  833. that can be used to access it.
  834. This is useful to avoid writing your own portable 64-bit seeking wrappers,
  835. and also avoids cross-module linking issues on Windows, where a
  836. <code>FILE *</code> must be accessed by routines defined in the same module
  837. that opened it.
  838. \param[out] _cb The callbacks to use for this file.
  839. If there is an error opening the file, nothing will be
  840. filled in here.
  841. \param _path The path to the file to open.
  842. On Windows, this string must be UTF-8 (to allow access to
  843. files whose names cannot be represented in the current
  844. MBCS code page).
  845. All other systems use the native character encoding.
  846. \param _mode The mode to open the file in.
  847. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  848. error.*/
  849. OP_WARN_UNUSED_RESULT void *op_fopen(OpusFileCallbacks *_cb,
  850. const char *_path,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
  851. OP_ARG_NONNULL(3);
  852. /**Opens a stream with <code>fdopen()</code> and fills in a set of callbacks
  853. that can be used to access it.
  854. This is useful to avoid writing your own portable 64-bit seeking wrappers,
  855. and also avoids cross-module linking issues on Windows, where a
  856. <code>FILE *</code> must be accessed by routines defined in the same module
  857. that opened it.
  858. \param[out] _cb The callbacks to use for this file.
  859. If there is an error opening the file, nothing will be
  860. filled in here.
  861. \param _fd The file descriptor to open.
  862. \param _mode The mode to open the file in.
  863. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  864. error.*/
  865. OP_WARN_UNUSED_RESULT void *op_fdopen(OpusFileCallbacks *_cb,
  866. int _fd,const char *_mode) OP_ARG_NONNULL(1) OP_ARG_NONNULL(3);
  867. /**Opens a stream with <code>freopen()</code> and fills in a set of callbacks
  868. that can be used to access it.
  869. This is useful to avoid writing your own portable 64-bit seeking wrappers,
  870. and also avoids cross-module linking issues on Windows, where a
  871. <code>FILE *</code> must be accessed by routines defined in the same module
  872. that opened it.
  873. \param[out] _cb The callbacks to use for this file.
  874. If there is an error opening the file, nothing will be
  875. filled in here.
  876. \param _path The path to the file to open.
  877. On Windows, this string must be UTF-8 (to allow access
  878. to files whose names cannot be represented in the
  879. current MBCS code page).
  880. All other systems use the native character encoding.
  881. \param _mode The mode to open the file in.
  882. \param _stream A stream previously returned by op_fopen(), op_fdopen(),
  883. or op_freopen().
  884. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  885. error.*/
  886. OP_WARN_UNUSED_RESULT void *op_freopen(OpusFileCallbacks *_cb,
  887. const char *_path,const char *_mode,void *_stream) OP_ARG_NONNULL(1)
  888. OP_ARG_NONNULL(2) OP_ARG_NONNULL(3) OP_ARG_NONNULL(4);
  889. /**Creates a stream that reads from the given block of memory.
  890. This block of memory must contain the complete stream to decode.
  891. This is useful for caching small streams (e.g., sound effects) in RAM.
  892. \param[out] _cb The callbacks to use for this stream.
  893. If there is an error creating the stream, nothing will be
  894. filled in here.
  895. \param _data The block of memory to read from.
  896. \param _size The size of the block of memory.
  897. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  898. error.*/
  899. OP_WARN_UNUSED_RESULT void *op_mem_stream_create(OpusFileCallbacks *_cb,
  900. const unsigned char *_data,size_t _size) OP_ARG_NONNULL(1);
  901. /**Creates a stream that reads from the given URL.
  902. This function behaves identically to op_url_stream_create(), except that it
  903. takes a va_list instead of a variable number of arguments.
  904. It does not call the <code>va_end</code> macro, and because it invokes the
  905. <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
  906. \note If you use this function, you must link against <tt>libopusurl</tt>.
  907. \param[out] _cb The callbacks to use for this stream.
  908. If there is an error creating the stream, nothing will
  909. be filled in here.
  910. \param _url The URL to read from.
  911. Currently only the <file:>, <http:>, and <https:>
  912. schemes are supported.
  913. Both <http:> and <https:> may be disabled at compile
  914. time, in which case opening such URLs will always fail.
  915. Currently this only supports URIs.
  916. IRIs should be converted to UTF-8 and URL-escaped, with
  917. internationalized domain names encoded in punycode,
  918. before passing them to this function.
  919. \param[in,out] _ap A list of the \ref url_options "optional flags" to use.
  920. This is a variable-length list of options terminated
  921. with <code>NULL</code>.
  922. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  923. error.*/
  924. OP_WARN_UNUSED_RESULT void *op_url_stream_vcreate(OpusFileCallbacks *_cb,
  925. const char *_url,va_list _ap) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  926. /**Creates a stream that reads from the given URL.
  927. \note If you use this function, you must link against <tt>libopusurl</tt>.
  928. \param[out] _cb The callbacks to use for this stream.
  929. If there is an error creating the stream, nothing will be
  930. filled in here.
  931. \param _url The URL to read from.
  932. Currently only the <file:>, <http:>, and <https:> schemes
  933. are supported.
  934. Both <http:> and <https:> may be disabled at compile time,
  935. in which case opening such URLs will always fail.
  936. Currently this only supports URIs.
  937. IRIs should be converted to UTF-8 and URL-escaped, with
  938. internationalized domain names encoded in punycode, before
  939. passing them to this function.
  940. \param ... The \ref url_options "optional flags" to use.
  941. This is a variable-length list of options terminated with
  942. <code>NULL</code>.
  943. \return A stream handle to use with the callbacks, or <code>NULL</code> on
  944. error.*/
  945. OP_WARN_UNUSED_RESULT void *op_url_stream_create(OpusFileCallbacks *_cb,
  946. const char *_url,...) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
  947. /**@}*/
  948. /**@}*/
  949. /**\defgroup stream_open_close Opening and Closing*/
  950. /**@{*/
  951. /**\name Functions for opening and closing streams
  952. These functions allow you to test a stream to see if it is Opus, open it,
  953. and close it.
  954. Several flavors are provided for each of the built-in stream types, plus a
  955. more general version which takes a set of application-provided callbacks.*/
  956. /**@{*/
  957. /**Test to see if this is an Opus stream.
  958. For good results, you will need at least 57 bytes (for a pure Opus-only
  959. stream).
  960. Something like 512 bytes will give more reliable results for multiplexed
  961. streams.
  962. This function is meant to be a quick-rejection filter.
  963. Its purpose is not to guarantee that a stream is a valid Opus stream, but to
  964. ensure that it looks enough like Opus that it isn't going to be recognized
  965. as some other format (except possibly an Opus stream that is also
  966. multiplexed with other codecs, such as video).
  967. \param[out] _head The parsed ID header contents.
  968. You may pass <code>NULL</code> if you do not need
  969. this information.
  970. If the function fails, the contents of this structure
  971. remain untouched.
  972. \param _initial_data An initial buffer of data from the start of the
  973. stream.
  974. \param _initial_bytes The number of bytes in \a _initial_data.
  975. \return 0 if the data appears to be Opus, or a negative value on error.
  976. \retval #OP_FALSE There was not enough data to tell if this was an Opus
  977. stream or not.
  978. \retval #OP_EFAULT An internal memory allocation failed.
  979. \retval #OP_EIMPL The stream used a feature that is not implemented,
  980. such as an unsupported channel family.
  981. \retval #OP_ENOTFORMAT If the data did not contain a recognizable ID
  982. header for an Opus stream.
  983. \retval #OP_EVERSION If the version field signaled a version this library
  984. does not know how to parse.
  985. \retval #OP_EBADHEADER The ID header was not properly formatted or contained
  986. illegal values.*/
  987. int op_test(OpusHead *_head,
  988. const unsigned char *_initial_data,size_t _initial_bytes);
  989. /**Open a stream from the given file path.
  990. \param _path The path to the file to open.
  991. \param[out] _error Returns 0 on success, or a failure code on error.
  992. You may pass in <code>NULL</code> if you don't want the
  993. failure code.
  994. The failure code will be #OP_EFAULT if the file could not
  995. be opened, or one of the other failure codes from
  996. op_open_callbacks() otherwise.
  997. \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
  998. OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
  999. OP_ARG_NONNULL(1);
  1000. /**Open a stream from a memory buffer.
  1001. \param _data The memory buffer to open.
  1002. \param _size The number of bytes in the buffer.
  1003. \param[out] _error Returns 0 on success, or a failure code on error.
  1004. You may pass in <code>NULL</code> if you don't want the
  1005. failure code.
  1006. See op_open_callbacks() for a full list of failure codes.
  1007. \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1008. OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
  1009. size_t _size,int *_error);
  1010. /**Open a stream from a URL.
  1011. This function behaves identically to op_open_url(), except that it
  1012. takes a va_list instead of a variable number of arguments.
  1013. It does not call the <code>va_end</code> macro, and because it invokes the
  1014. <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
  1015. \note If you use this function, you must link against <tt>libopusurl</tt>.
  1016. \param _url The URL to open.
  1017. Currently only the <file:>, <http:>, and <https:>
  1018. schemes are supported.
  1019. Both <http:> and <https:> may be disabled at compile
  1020. time, in which case opening such URLs will always
  1021. fail.
  1022. Currently this only supports URIs.
  1023. IRIs should be converted to UTF-8 and URL-escaped,
  1024. with internationalized domain names encoded in
  1025. punycode, before passing them to this function.
  1026. \param[out] _error Returns 0 on success, or a failure code on error.
  1027. You may pass in <code>NULL</code> if you don't want
  1028. the failure code.
  1029. See op_open_callbacks() for a full list of failure
  1030. codes.
  1031. \param[in,out] _ap A list of the \ref url_options "optional flags" to
  1032. use.
  1033. This is a variable-length list of options terminated
  1034. with <code>NULL</code>.
  1035. \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1036. OP_WARN_UNUSED_RESULT OggOpusFile *op_vopen_url(const char *_url,
  1037. int *_error,va_list _ap) OP_ARG_NONNULL(1);
  1038. /**Open a stream from a URL.
  1039. \note If you use this function, you must link against <tt>libopusurl</tt>.
  1040. \param _url The URL to open.
  1041. Currently only the <file:>, <http:>, and <https:> schemes
  1042. are supported.
  1043. Both <http:> and <https:> may be disabled at compile
  1044. time, in which case opening such URLs will always fail.
  1045. Currently this only supports URIs.
  1046. IRIs should be converted to UTF-8 and URL-escaped, with
  1047. internationalized domain names encoded in punycode,
  1048. before passing them to this function.
  1049. \param[out] _error Returns 0 on success, or a failure code on error.
  1050. You may pass in <code>NULL</code> if you don't want the
  1051. failure code.
  1052. See op_open_callbacks() for a full list of failure codes.
  1053. \param ... The \ref url_options "optional flags" to use.
  1054. This is a variable-length list of options terminated with
  1055. <code>NULL</code>.
  1056. \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1057. OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
  1058. int *_error,...) OP_ARG_NONNULL(1);
  1059. /**Open a stream using the given set of callbacks to access it.
  1060. \param _stream The stream to read from (e.g., a <code>FILE *</code>).
  1061. This value will be passed verbatim as the first
  1062. argument to all of the callbacks.
  1063. \param _cb The callbacks with which to access the stream.
  1064. \ref op_read_func "read()" must be implemented.
  1065. \ref op_seek_func "seek()" and \ref op_tell_func
  1066. "tell()" may be <code>NULL</code>, or may always
  1067. return -1 to indicate a stream is unseekable, but if
  1068. \ref op_seek_func "seek()" is implemented and
  1069. succeeds on a particular stream, then \ref
  1070. op_tell_func "tell()" must also.
  1071. \ref op_close_func "close()" may be <code>NULL</code>,
  1072. but if it is not, it will be called when the \c
  1073. OggOpusFile is destroyed by op_free().
  1074. It will not be called if op_open_callbacks() fails
  1075. with an error.
  1076. \param _initial_data An initial buffer of data from the start of the
  1077. stream.
  1078. Applications can read some number of bytes from the
  1079. start of the stream to help identify this as an Opus
  1080. stream, and then provide them here to allow the
  1081. stream to be opened, even if it is unseekable.
  1082. \param _initial_bytes The number of bytes in \a _initial_data.
  1083. If the stream is seekable, its current position (as
  1084. reported by \ref op_tell_func "tell()" at the start
  1085. of this function) must be equal to \a _initial_bytes.
  1086. Otherwise, seeking to absolute positions will
  1087. generate inconsistent results.
  1088. \param[out] _error Returns 0 on success, or a failure code on error.
  1089. You may pass in <code>NULL</code> if you don't want
  1090. the failure code.
  1091. The failure code will be one of
  1092. <dl>
  1093. <dt>#OP_EREAD</dt>
  1094. <dd>An underlying read, seek, or tell operation
  1095. failed when it should have succeeded, or we failed
  1096. to find data in the stream we had seen before.</dd>
  1097. <dt>#OP_EFAULT</dt>
  1098. <dd>There was a memory allocation failure, or an
  1099. internal library error.</dd>
  1100. <dt>#OP_EIMPL</dt>
  1101. <dd>The stream used a feature that is not
  1102. implemented, such as an unsupported channel
  1103. family.</dd>
  1104. <dt>#OP_EINVAL</dt>
  1105. <dd>\ref op_seek_func "seek()" was implemented and
  1106. succeeded on this source, but \ref op_tell_func
  1107. "tell()" did not, or the starting position
  1108. indicator was not equal to \a _initial_bytes.</dd>
  1109. <dt>#OP_ENOTFORMAT</dt>
  1110. <dd>The stream contained a link that did not have
  1111. any logical Opus streams in it.</dd>
  1112. <dt>#OP_EBADHEADER</dt>
  1113. <dd>A required header packet was not properly
  1114. formatted, contained illegal values, or was missing
  1115. altogether.</dd>
  1116. <dt>#OP_EVERSION</dt>
  1117. <dd>An ID header contained an unrecognized version
  1118. number.</dd>
  1119. <dt>#OP_EBADLINK</dt>
  1120. <dd>We failed to find data we had seen before after
  1121. seeking.</dd>
  1122. <dt>#OP_EBADTIMESTAMP</dt>
  1123. <dd>The first or last timestamp in a link failed
  1124. basic validity checks.</dd>
  1125. </dl>
  1126. \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.
  1127. <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
  1128. if the call fails.
  1129. The calling application is responsible for closing the stream if
  1130. this call returns an error.*/
  1131. OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
  1132. const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  1133. size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
  1134. /**Partially open a stream from the given file path.
  1135. \see op_test_callbacks
  1136. \param _path The path to the file to open.
  1137. \param[out] _error Returns 0 on success, or a failure code on error.
  1138. You may pass in <code>NULL</code> if you don't want the
  1139. failure code.
  1140. The failure code will be #OP_EFAULT if the file could not
  1141. be opened, or one of the other failure codes from
  1142. op_open_callbacks() otherwise.
  1143. \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1144. OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
  1145. OP_ARG_NONNULL(1);
  1146. /**Partially open a stream from a memory buffer.
  1147. \see op_test_callbacks
  1148. \param _data The memory buffer to open.
  1149. \param _size The number of bytes in the buffer.
  1150. \param[out] _error Returns 0 on success, or a failure code on error.
  1151. You may pass in <code>NULL</code> if you don't want the
  1152. failure code.
  1153. See op_open_callbacks() for a full list of failure codes.
  1154. \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1155. OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
  1156. size_t _size,int *_error);
  1157. /**Partially open a stream from a URL.
  1158. This function behaves identically to op_test_url(), except that it
  1159. takes a va_list instead of a variable number of arguments.
  1160. It does not call the <code>va_end</code> macro, and because it invokes the
  1161. <code>va_arg</code> macro, the value of \a _ap is undefined after the call.
  1162. \note If you use this function, you must link against <tt>libopusurl</tt>.
  1163. \see op_test_url
  1164. \see op_test_callbacks
  1165. \param _url The URL to open.
  1166. Currently only the <file:>, <http:>, and <https:>
  1167. schemes are supported.
  1168. Both <http:> and <https:> may be disabled at compile
  1169. time, in which case opening such URLs will always
  1170. fail.
  1171. Currently this only supports URIs.
  1172. IRIs should be converted to UTF-8 and URL-escaped,
  1173. with internationalized domain names encoded in
  1174. punycode, before passing them to this function.
  1175. \param[out] _error Returns 0 on success, or a failure code on error.
  1176. You may pass in <code>NULL</code> if you don't want
  1177. the failure code.
  1178. See op_open_callbacks() for a full list of failure
  1179. codes.
  1180. \param[in,out] _ap A list of the \ref url_options "optional flags" to
  1181. use.
  1182. This is a variable-length list of options terminated
  1183. with <code>NULL</code>.
  1184. \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1185. OP_WARN_UNUSED_RESULT OggOpusFile *op_vtest_url(const char *_url,
  1186. int *_error,va_list _ap) OP_ARG_NONNULL(1);
  1187. /**Partially open a stream from a URL.
  1188. \note If you use this function, you must link against <tt>libopusurl</tt>.
  1189. \see op_test_callbacks
  1190. \param _url The URL to open.
  1191. Currently only the <file:>, <http:>, and <https:>
  1192. schemes are supported.
  1193. Both <http:> and <https:> may be disabled at compile
  1194. time, in which case opening such URLs will always fail.
  1195. Currently this only supports URIs.
  1196. IRIs should be converted to UTF-8 and URL-escaped, with
  1197. internationalized domain names encoded in punycode,
  1198. before passing them to this function.
  1199. \param[out] _error Returns 0 on success, or a failure code on error.
  1200. You may pass in <code>NULL</code> if you don't want the
  1201. failure code.
  1202. See op_open_callbacks() for a full list of failure
  1203. codes.
  1204. \param ... The \ref url_options "optional flags" to use.
  1205. This is a variable-length list of options terminated
  1206. with <code>NULL</code>.
  1207. \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
  1208. OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
  1209. int *_error,...) OP_ARG_NONNULL(1);
  1210. /**Partially open a stream using the given set of callbacks to access it.
  1211. This tests for Opusness and loads the headers for the first link.
  1212. It does not seek (although it tests for seekability).
  1213. You can query a partially open stream for the few pieces of basic
  1214. information returned by op_serialno(), op_channel_count(), op_head(), and
  1215. op_tags() (but only for the first link).
  1216. You may also determine if it is seekable via a call to op_seekable().
  1217. You cannot read audio from the stream, seek, get the size or duration,
  1218. get information from links other than the first one, or even get the total
  1219. number of links until you finish opening the stream with op_test_open().
  1220. If you do not need to do any of these things, you can dispose of it with
  1221. op_free() instead.
  1222. This function is provided mostly to simplify porting existing code that used
  1223. <tt>libvorbisfile</tt>.
  1224. For new code, you are likely better off using op_test() instead, which
  1225. is less resource-intensive, requires less data to succeed, and imposes a
  1226. hard limit on the amount of data it examines (important for unseekable
  1227. streams, where all such data must be buffered until you are sure of the
  1228. stream type).
  1229. \param _stream The stream to read from (e.g., a <code>FILE *</code>).
  1230. This value will be passed verbatim as the first
  1231. argument to all of the callbacks.
  1232. \param _cb The callbacks with which to access the stream.
  1233. \ref op_read_func "read()" must be implemented.
  1234. \ref op_seek_func "seek()" and \ref op_tell_func
  1235. "tell()" may be <code>NULL</code>, or may always
  1236. return -1 to indicate a stream is unseekable, but if
  1237. \ref op_seek_func "seek()" is implemented and
  1238. succeeds on a particular stream, then \ref
  1239. op_tell_func "tell()" must also.
  1240. \ref op_close_func "close()" may be <code>NULL</code>,
  1241. but if it is not, it will be called when the \c
  1242. OggOpusFile is destroyed by op_free().
  1243. It will not be called if op_open_callbacks() fails
  1244. with an error.
  1245. \param _initial_data An initial buffer of data from the start of the
  1246. stream.
  1247. Applications can read some number of bytes from the
  1248. start of the stream to help identify this as an Opus
  1249. stream, and then provide them here to allow the
  1250. stream to be tested more thoroughly, even if it is
  1251. unseekable.
  1252. \param _initial_bytes The number of bytes in \a _initial_data.
  1253. If the stream is seekable, its current position (as
  1254. reported by
  1255. \ref op_tell_func "tell()" at the start of this
  1256. function) must be equal to \a _initial_bytes.
  1257. Otherwise, seeking to absolute positions will
  1258. generate inconsistent results.
  1259. \param[out] _error Returns 0 on success, or a failure code on error.
  1260. You may pass in <code>NULL</code> if you don't want
  1261. the failure code.
  1262. See op_open_callbacks() for a full list of failure
  1263. codes.
  1264. \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.
  1265. <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
  1266. if the call fails.
  1267. The calling application is responsible for closing the stream if
  1268. this call returns an error.*/
  1269. OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
  1270. const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  1271. size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
  1272. /**Finish opening a stream partially opened with op_test_callbacks() or one of
  1273. the associated convenience functions.
  1274. If this function fails, you are still responsible for freeing the
  1275. \c OggOpusFile with op_free().
  1276. \param _of The \c OggOpusFile to finish opening.
  1277. \return 0 on success, or a negative value on error.
  1278. \retval #OP_EREAD An underlying read, seek, or tell operation failed
  1279. when it should have succeeded.
  1280. \retval #OP_EFAULT There was a memory allocation failure, or an
  1281. internal library error.
  1282. \retval #OP_EIMPL The stream used a feature that is not implemented,
  1283. such as an unsupported channel family.
  1284. \retval #OP_EINVAL The stream was not partially opened with
  1285. op_test_callbacks() or one of the associated
  1286. convenience functions.
  1287. \retval #OP_ENOTFORMAT The stream contained a link that did not have any
  1288. logical Opus streams in it.
  1289. \retval #OP_EBADHEADER A required header packet was not properly
  1290. formatted, contained illegal values, or was
  1291. missing altogether.
  1292. \retval #OP_EVERSION An ID header contained an unrecognized version
  1293. number.
  1294. \retval #OP_EBADLINK We failed to find data we had seen before after
  1295. seeking.
  1296. \retval #OP_EBADTIMESTAMP The first or last timestamp in a link failed basic
  1297. validity checks.*/
  1298. int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
  1299. /**Release all memory used by an \c OggOpusFile.
  1300. \param _of The \c OggOpusFile to free.*/
  1301. void op_free(OggOpusFile *_of);
  1302. /**@}*/
  1303. /**@}*/
  1304. /**\defgroup stream_info Stream Information*/
  1305. /**@{*/
  1306. /**\name Functions for obtaining information about streams
  1307. These functions allow you to get basic information about a stream, including
  1308. seekability, the number of links (for chained streams), plus the size,
  1309. duration, bitrate, header parameters, and meta information for each link
  1310. (or, where available, the stream as a whole).
  1311. Some of these (size, duration) are only available for seekable streams.
  1312. You can also query the current stream position, link, and playback time,
  1313. and instantaneous bitrate during playback.
  1314. Some of these functions may be used successfully on the partially open
  1315. streams returned by op_test_callbacks() or one of the associated
  1316. convenience functions.
  1317. Their documention will indicate so explicitly.*/
  1318. /**@{*/
  1319. /**Returns whether or not the stream being read is seekable.
  1320. This is true if
  1321. <ol>
  1322. <li>The \ref op_seek_func "seek()" and \ref op_tell_func "tell()"
  1323. callbacks are both non-<code>NULL</code>,</li>
  1324. <li>The \ref op_seek_func "seek()" callback was successfully executed at
  1325. least once, and</li>
  1326. <li>The \ref op_tell_func "tell()" callback was successfully able to report
  1327. the position indicator afterwards.</li>
  1328. </ol>
  1329. This function may be called on partially-opened streams.
  1330. \param _of The \c OggOpusFile whose seekable status is to be returned.
  1331. \return A non-zero value if seekable, and 0 if unseekable.*/
  1332. int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
  1333. /**Returns the number of links in this chained stream.
  1334. This function may be called on partially-opened streams, but it will always
  1335. return 1.
  1336. The actual number of links is not known until the stream is fully opened.
  1337. \param _of The \c OggOpusFile from which to retrieve the link count.
  1338. \return For fully-open seekable streams, this returns the total number of
  1339. links in the whole stream, which will be at least 1.
  1340. For partially-open or unseekable streams, this always returns 1.*/
  1341. int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
  1342. /**Get the serial number of the given link in a (possibly-chained) Ogg Opus
  1343. stream.
  1344. This function may be called on partially-opened streams, but it will always
  1345. return the serial number of the Opus stream in the first link.
  1346. \param _of The \c OggOpusFile from which to retrieve the serial number.
  1347. \param _li The index of the link whose serial number should be retrieved.
  1348. Use a negative number to get the serial number of the current
  1349. link.
  1350. \return The serial number of the given link.
  1351. If \a _li is greater than the total number of links, this returns
  1352. the serial number of the last link.
  1353. If the stream is not seekable, this always returns the serial number
  1354. of the current link.*/
  1355. opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1356. /**Get the channel count of the given link in a (possibly-chained) Ogg Opus
  1357. stream.
  1358. This is equivalent to <code>op_head(_of,_li)->channel_count</code>, but
  1359. is provided for convenience.
  1360. This function may be called on partially-opened streams, but it will always
  1361. return the channel count of the Opus stream in the first link.
  1362. \param _of The \c OggOpusFile from which to retrieve the channel count.
  1363. \param _li The index of the link whose channel count should be retrieved.
  1364. Use a negative number to get the channel count of the current
  1365. link.
  1366. \return The channel count of the given link.
  1367. If \a _li is greater than the total number of links, this returns
  1368. the channel count of the last link.
  1369. If the stream is not seekable, this always returns the channel count
  1370. of the current link.*/
  1371. int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1372. /**Get the total (compressed) size of the stream, or of an individual link in
  1373. a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
  1374. overhead.
  1375. \warning If the Opus stream (or link) is concurrently multiplexed with other
  1376. logical streams (e.g., video), this returns the size of the entire stream
  1377. (or link), not just the number of bytes in the first logical Opus stream.
  1378. Returning the latter would require scanning the entire file.
  1379. \param _of The \c OggOpusFile from which to retrieve the compressed size.
  1380. \param _li The index of the link whose compressed size should be computed.
  1381. Use a negative number to get the compressed size of the entire
  1382. stream.
  1383. \return The compressed size of the entire stream if \a _li is negative, the
  1384. compressed size of link \a _li if it is non-negative, or a negative
  1385. value on error.
  1386. The compressed size of the entire stream may be smaller than that
  1387. of the underlying stream if trailing garbage was detected in the
  1388. file.
  1389. \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
  1390. \a _li wasn't less than the total number of links in
  1391. the stream, or the stream was only partially open.*/
  1392. opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1393. /**Get the total PCM length (number of samples at 48 kHz) of the stream, or of
  1394. an individual link in a (possibly-chained) Ogg Opus stream.
  1395. Users looking for <code>op_time_total()</code> should use op_pcm_total()
  1396. instead.
  1397. Because timestamps in Opus are fixed at 48 kHz, there is no need for a
  1398. separate function to convert this to seconds (and leaving it out avoids
  1399. introducing floating point to the API, for those that wish to avoid it).
  1400. \param _of The \c OggOpusFile from which to retrieve the PCM offset.
  1401. \param _li The index of the link whose PCM length should be computed.
  1402. Use a negative number to get the PCM length of the entire stream.
  1403. \return The PCM length of the entire stream if \a _li is negative, the PCM
  1404. length of link \a _li if it is non-negative, or a negative value on
  1405. error.
  1406. \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
  1407. \a _li wasn't less than the total number of links in
  1408. the stream, or the stream was only partially open.*/
  1409. ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1410. /**Get the ID header information for the given link in a (possibly chained) Ogg
  1411. Opus stream.
  1412. This function may be called on partially-opened streams, but it will always
  1413. return the ID header information of the Opus stream in the first link.
  1414. \param _of The \c OggOpusFile from which to retrieve the ID header
  1415. information.
  1416. \param _li The index of the link whose ID header information should be
  1417. retrieved.
  1418. Use a negative number to get the ID header information of the
  1419. current link.
  1420. For an unseekable stream, \a _li is ignored, and the ID header
  1421. information for the current link is always returned, if
  1422. available.
  1423. \return The contents of the ID header for the given link.*/
  1424. const OpusHead *op_head(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1425. /**Get the comment header information for the given link in a (possibly
  1426. chained) Ogg Opus stream.
  1427. This function may be called on partially-opened streams, but it will always
  1428. return the tags from the Opus stream in the first link.
  1429. \param _of The \c OggOpusFile from which to retrieve the comment header
  1430. information.
  1431. \param _li The index of the link whose comment header information should be
  1432. retrieved.
  1433. Use a negative number to get the comment header information of
  1434. the current link.
  1435. For an unseekable stream, \a _li is ignored, and the comment
  1436. header information for the current link is always returned, if
  1437. available.
  1438. \return The contents of the comment header for the given link, or
  1439. <code>NULL</code> if this is an unseekable stream that encountered
  1440. an invalid link.*/
  1441. const OpusTags *op_tags(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1442. /**Retrieve the index of the current link.
  1443. This is the link that produced the data most recently read by
  1444. op_read_float() or its associated functions, or, after a seek, the link
  1445. that the seek target landed in.
  1446. Reading more data may advance the link index (even on the first read after a
  1447. seek).
  1448. \param _of The \c OggOpusFile from which to retrieve the current link index.
  1449. \return The index of the current link on success, or a negative value on
  1450. failure.
  1451. For seekable streams, this is a number between 0 (inclusive) and the
  1452. value returned by op_link_count() (exclusive).
  1453. For unseekable streams, this value starts at 0 and increments by one
  1454. each time a new link is encountered (even though op_link_count()
  1455. always returns 1).
  1456. \retval #OP_EINVAL The stream was only partially open.*/
  1457. int op_current_link(const OggOpusFile *_of) OP_ARG_NONNULL(1);
  1458. /**Computes the bitrate of the stream, or of an individual link in a
  1459. (possibly-chained) Ogg Opus stream.
  1460. The stream must be seekable to compute the bitrate.
  1461. For unseekable streams, use op_bitrate_instant() to get periodic estimates.
  1462. \warning If the Opus stream (or link) is concurrently multiplexed with other
  1463. logical streams (e.g., video), this uses the size of the entire stream (or
  1464. link) to compute the bitrate, not just the number of bytes in the first
  1465. logical Opus stream.
  1466. Returning the latter requires scanning the entire file, but this may be done
  1467. by decoding the whole file and calling op_bitrate_instant() once at the
  1468. end.
  1469. Install a trivial decoding callback with op_set_decode_callback() if you
  1470. wish to skip actual decoding during this process.
  1471. \param _of The \c OggOpusFile from which to retrieve the bitrate.
  1472. \param _li The index of the link whose bitrate should be computed.
  1473. Use a negative number to get the bitrate of the whole stream.
  1474. \return The bitrate on success, or a negative value on error.
  1475. \retval #OP_EINVAL The stream was only partially open, the stream was not
  1476. seekable, or \a _li was larger than the number of
  1477. links.*/
  1478. opus_int32 op_bitrate(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
  1479. /**Compute the instantaneous bitrate, measured as the ratio of bits to playable
  1480. samples decoded since a) the last call to op_bitrate_instant(), b) the last
  1481. seek, or c) the start of playback, whichever was most recent.
  1482. This will spike somewhat after a seek or at the start/end of a chain
  1483. boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
  1484. decoded but not played.
  1485. \param _of The \c OggOpusFile from which to retrieve the bitrate.
  1486. \return The bitrate, in bits per second, or a negative value on error.
  1487. \retval #OP_FALSE No data has been decoded since any of the events
  1488. described above.
  1489. \retval #OP_EINVAL The stream was only partially open.*/
  1490. opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
  1491. /**Obtain the current value of the position indicator for \a _of.
  1492. \param _of The \c OggOpusFile from which to retrieve the position indicator.
  1493. \return The byte position that is currently being read from.
  1494. \retval #OP_EINVAL The stream was only partially open.*/
  1495. opus_int64 op_raw_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
  1496. /**Obtain the PCM offset of the next sample to be read.
  1497. If the stream is not properly timestamped, this might not increment by the
  1498. proper amount between reads, or even return monotonically increasing
  1499. values.
  1500. \param _of The \c OggOpusFile from which to retrieve the PCM offset.
  1501. \return The PCM offset of the next sample to be read.
  1502. \retval #OP_EINVAL The stream was only partially open.*/
  1503. ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
  1504. /**@}*/
  1505. /**@}*/
  1506. /**\defgroup stream_seeking Seeking*/
  1507. /**@{*/
  1508. /**\name Functions for seeking in Opus streams
  1509. These functions let you seek in Opus streams, if the underlying stream
  1510. support it.
  1511. Seeking is implemented for all built-in stream I/O routines, though some
  1512. individual streams may not be seekable (pipes, live HTTP streams, or HTTP
  1513. streams from a server that does not support <code>Range</code> requests).
  1514. op_raw_seek() is the fastest: it is guaranteed to perform at most one
  1515. physical seek, but, since the target is a byte position, makes no guarantee
  1516. how close to a given time it will come.
  1517. op_pcm_seek() provides sample-accurate seeking.
  1518. The number of physical seeks it requires is still quite small (often 1 or
  1519. 2, even in highly variable bitrate streams).
  1520. Seeking in Opus requires decoding some pre-roll amount before playback to
  1521. allow the internal state to converge (as if recovering from packet loss).
  1522. This is handled internally by <tt>libopusfile</tt>, but means there is
  1523. little extra overhead for decoding up to the exact position requested
  1524. (since it must decode some amount of audio anyway).
  1525. It also means that decoding after seeking may not return exactly the same
  1526. values as would be obtained by decoding the stream straight through.
  1527. However, such differences are expected to be smaller than the loss
  1528. introduced by Opus's lossy compression.*/
  1529. /**@{*/
  1530. /**Seek to a byte offset relative to the <b>compressed</b> data.
  1531. This also scans packets to update the PCM cursor.
  1532. It will cross a logical bitstream boundary, but only if it can't get any
  1533. packets out of the tail of the link to which it seeks.
  1534. \param _of The \c OggOpusFile in which to seek.
  1535. \param _byte_offset The byte position to seek to.
  1536. This must be between 0 and #op_raw_total(\a _of,\c -1)
  1537. (inclusive).
  1538. \return 0 on success, or a negative error code on failure.
  1539. \retval #OP_EREAD The underlying seek operation failed.
  1540. \retval #OP_EINVAL The stream was only partially open, or the target was
  1541. outside the valid range for the stream.
  1542. \retval #OP_ENOSEEK This stream is not seekable.
  1543. \retval #OP_EBADLINK Failed to initialize a decoder for a stream for an
  1544. unknown reason.*/
  1545. int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
  1546. /**Seek to the specified PCM offset, such that decoding will begin at exactly
  1547. the requested position.
  1548. \param _of The \c OggOpusFile in which to seek.
  1549. \param _pcm_offset The PCM offset to seek to.
  1550. This is in samples at 48 kHz relative to the start of the
  1551. stream.
  1552. \return 0 on success, or a negative value on error.
  1553. \retval #OP_EREAD An underlying read or seek operation failed.
  1554. \retval #OP_EINVAL The stream was only partially open, or the target was
  1555. outside the valid range for the stream.
  1556. \retval #OP_ENOSEEK This stream is not seekable.
  1557. \retval #OP_EBADLINK We failed to find data we had seen before, or the
  1558. bitstream structure was sufficiently malformed that
  1559. seeking to the target destination was impossible.*/
  1560. int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
  1561. /**@}*/
  1562. /**@}*/
  1563. /**\defgroup stream_decoding Decoding*/
  1564. /**@{*/
  1565. /**\name Functions for decoding audio data
  1566. These functions retrieve actual decoded audio data from the stream.
  1567. The general functions, op_read() and op_read_float() return 16-bit or
  1568. floating-point output, both using native endian ordering.
  1569. The number of channels returned can change from link to link in a chained
  1570. stream.
  1571. There are special functions, op_read_stereo() and op_read_float_stereo(),
  1572. which always output two channels, to simplify applications which do not
  1573. wish to handle multichannel audio.
  1574. These downmix multichannel files to two channels, so they can always return
  1575. samples in the same format for every link in a chained file.
  1576. If the rest of your audio processing chain can handle floating point, the
  1577. floating-point routines should be preferred, as they prevent clipping and
  1578. other issues which might be avoided entirely if, e.g., you scale down the
  1579. volume at some other stage.
  1580. However, if you intend to consume 16-bit samples directly, the conversion in
  1581. <tt>libopusfile</tt> provides noise-shaping dithering and, if compiled
  1582. against <tt>libopus</tt>&nbsp;1.1 or later, soft-clipping prevention.
  1583. <tt>libopusfile</tt> can also be configured at compile time to use the
  1584. fixed-point <tt>libopus</tt> API.
  1585. If so, <tt>libopusfile</tt>'s floating-point API may also be disabled.
  1586. In that configuration, nothing in <tt>libopusfile</tt> will use any
  1587. floating-point operations, to simplify support on devices without an
  1588. adequate FPU.
  1589. \warning HTTPS streams may be be vulnerable to truncation attacks if you do
  1590. not check the error return code from op_read_float() or its associated
  1591. functions.
  1592. If the remote peer does not close the connection gracefully (with a TLS
  1593. "close notify" message), these functions will return #OP_EREAD instead of 0
  1594. when they reach the end of the file.
  1595. If you are reading from an <https:> URL (particularly if seeking is not
  1596. supported), you should make sure to check for this error and warn the user
  1597. appropriately.*/
  1598. /**@{*/
  1599. /**Indicates that the decoding callback should produce signed 16-bit
  1600. native-endian output samples.*/
  1601. #define OP_DEC_FORMAT_SHORT (7008)
  1602. /**Indicates that the decoding callback should produce 32-bit native-endian
  1603. float samples.*/
  1604. #define OP_DEC_FORMAT_FLOAT (7040)
  1605. /**Indicates that the decoding callback did not decode anything, and that
  1606. <tt>libopusfile</tt> should decode normally instead.*/
  1607. #define OP_DEC_USE_DEFAULT (6720)
  1608. /**Called to decode an Opus packet.
  1609. This should invoke the functional equivalent of opus_multistream_decode() or
  1610. opus_multistream_decode_float(), except that it returns 0 on success
  1611. instead of the number of decoded samples (which is known a priori).
  1612. \param _ctx The application-provided callback context.
  1613. \param _decoder The decoder to use to decode the packet.
  1614. \param[out] _pcm The buffer to decode into.
  1615. This will always have enough room for \a _nchannels of
  1616. \a _nsamples samples, which should be placed into this
  1617. buffer interleaved.
  1618. \param _op The packet to decode.
  1619. This will always have its granule position set to a valid
  1620. value.
  1621. \param _nsamples The number of samples expected from the packet.
  1622. \param _nchannels The number of channels expected from the packet.
  1623. \param _format The desired sample output format.
  1624. This is either #OP_DEC_FORMAT_SHORT or
  1625. #OP_DEC_FORMAT_FLOAT.
  1626. \param _li The index of the link from which this packet was decoded.
  1627. \return A non-negative value on success, or a negative value on error.
  1628. Any error codes should be the same as those returned by
  1629. opus_multistream_decode() or opus_multistream_decode_float().
  1630. Success codes are as follows:
  1631. \retval 0 Decoding was successful.
  1632. The application has filled the buffer with
  1633. exactly <code>\a _nsamples*\a
  1634. _nchannels</code> samples in the requested
  1635. format.
  1636. \retval #OP_DEC_USE_DEFAULT No decoding was done.
  1637. <tt>libopusfile</tt> should do the decoding
  1638. by itself instead.*/
  1639. typedef int (*op_decode_cb_func)(void *_ctx,OpusMSDecoder *_decoder,void *_pcm,
  1640. const ogg_packet *_op,int _nsamples,int _nchannels,int _format,int _li);
  1641. /**Sets the packet decode callback function.
  1642. If set, this is called once for each packet that needs to be decoded.
  1643. This can be used by advanced applications to do additional processing on the
  1644. compressed or uncompressed data.
  1645. For example, an application might save the final entropy coder state for
  1646. debugging and testing purposes, or it might apply additional filters
  1647. before the downmixing, dithering, or soft-clipping performed by
  1648. <tt>libopusfile</tt>, so long as these filters do not introduce any
  1649. latency.
  1650. A call to this function is no guarantee that the audio will eventually be
  1651. delivered to the application.
  1652. <tt>libopusfile</tt> may discard some or all of the decoded audio data
  1653. (i.e., at the beginning or end of a link, or after a seek), however the
  1654. callback is still required to provide all of it.
  1655. \param _of The \c OggOpusFile on which to set the decode callback.
  1656. \param _decode_cb The callback function to call.
  1657. This may be <code>NULL</code> to disable calling the
  1658. callback.
  1659. \param _ctx The application-provided context pointer to pass to the
  1660. callback on each call.*/
  1661. void op_set_decode_callback(OggOpusFile *_of,
  1662. op_decode_cb_func _decode_cb,void *_ctx) OP_ARG_NONNULL(1);
  1663. /**Gain offset type that indicates that the provided offset is relative to the
  1664. header gain.
  1665. This is the default.*/
  1666. #define OP_HEADER_GAIN (0)
  1667. /**Gain offset type that indicates that the provided offset is relative to the
  1668. R128_ALBUM_GAIN value (if any), in addition to the header gain.*/
  1669. #define OP_ALBUM_GAIN (3007)
  1670. /**Gain offset type that indicates that the provided offset is relative to the
  1671. R128_TRACK_GAIN value (if any), in addition to the header gain.*/
  1672. #define OP_TRACK_GAIN (3008)
  1673. /**Gain offset type that indicates that the provided offset should be used as
  1674. the gain directly, without applying any the header or track gains.*/
  1675. #define OP_ABSOLUTE_GAIN (3009)
  1676. /**Sets the gain to be used for decoded output.
  1677. By default, the gain in the header is applied with no additional offset.
  1678. The total gain (including header gain and/or track gain, if applicable, and
  1679. this offset), will be clamped to [-32768,32767]/256 dB.
  1680. This is more than enough to saturate or underflow 16-bit PCM.
  1681. \note The new gain will not be applied to any already buffered, decoded
  1682. output.
  1683. This means you cannot change it sample-by-sample, as at best it will be
  1684. updated packet-by-packet.
  1685. It is meant for setting a target volume level, rather than applying smooth
  1686. fades, etc.
  1687. \param _of The \c OggOpusFile on which to set the gain offset.
  1688. \param _gain_type One of #OP_HEADER_GAIN, #OP_ALBUM_GAIN,
  1689. #OP_TRACK_GAIN, or #OP_ABSOLUTE_GAIN.
  1690. \param _gain_offset_q8 The gain offset to apply, in 1/256ths of a dB.
  1691. \return 0 on success or a negative value on error.
  1692. \retval #OP_EINVAL The \a _gain_type was unrecognized.*/
  1693. int op_set_gain_offset(OggOpusFile *_of,
  1694. int _gain_type,opus_int32 _gain_offset_q8) OP_ARG_NONNULL(1);
  1695. /**Sets whether or not dithering is enabled for 16-bit decoding.
  1696. By default, when <tt>libopusfile</tt> is compiled to use floating-point
  1697. internally, calling op_read() or op_read_stereo() will first decode to
  1698. float, and then convert to fixed-point using noise-shaping dithering.
  1699. This flag can be used to disable that dithering.
  1700. When the application uses op_read_float() or op_read_float_stereo(), or when
  1701. the library has been compiled to decode directly to fixed point, this flag
  1702. has no effect.
  1703. \param _of The \c OggOpusFile on which to enable or disable dithering.
  1704. \param _enabled A non-zero value to enable dithering, or 0 to disable it.*/
  1705. void op_set_dither_enabled(OggOpusFile *_of,int _enabled) OP_ARG_NONNULL(1);
  1706. /**Reads more samples from the stream.
  1707. \note Although \a _buf_size must indicate the total number of values that
  1708. can be stored in \a _pcm, the return value is the number of samples
  1709. <em>per channel</em>.
  1710. This is done because
  1711. <ol>
  1712. <li>The channel count cannot be known a priori (reading more samples might
  1713. advance us into the next link, with a different channel count), so
  1714. \a _buf_size cannot also be in units of samples per channel,</li>
  1715. <li>Returning the samples per channel matches the <code>libopus</code> API
  1716. as closely as we're able,</li>
  1717. <li>Returning the total number of values instead of samples per channel
  1718. would mean the caller would need a division to compute the samples per
  1719. channel, and might worry about the possibility of getting back samples
  1720. for some channels and not others, and</li>
  1721. <li>This approach is relatively fool-proof: if an application passes too
  1722. small a value to \a _buf_size, they will simply get fewer samples back,
  1723. and if they assume the return value is the total number of values, then
  1724. they will simply read too few (rather than reading too many and going
  1725. off the end of the buffer).</li>
  1726. </ol>
  1727. \param _of The \c OggOpusFile from which to read.
  1728. \param[out] _pcm A buffer in which to store the output PCM samples, as
  1729. signed native-endian 16-bit values at 48&nbsp;kHz
  1730. with a nominal range of <code>[-32768,32767)</code>.
  1731. Multiple channels are interleaved using the
  1732. <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
  1733. channel ordering</a>.
  1734. This must have room for at least \a _buf_size values.
  1735. \param _buf_size The number of values that can be stored in \a _pcm.
  1736. It is recommended that this be large enough for at
  1737. least 120 ms of data at 48 kHz per channel (5760
  1738. values per channel).
  1739. Smaller buffers will simply return less data, possibly
  1740. consuming more memory to buffer the data internally.
  1741. <tt>libopusfile</tt> may return less data than
  1742. requested.
  1743. If so, there is no guarantee that the remaining data
  1744. in \a _pcm will be unmodified.
  1745. \param[out] _li The index of the link this data was decoded from.
  1746. You may pass <code>NULL</code> if you do not need this
  1747. information.
  1748. If this function fails (returning a negative value),
  1749. this parameter is left unset.
  1750. \return The number of samples read per channel on success, or a negative
  1751. value on failure.
  1752. The channel count can be retrieved on success by calling
  1753. <code>op_head(_of,*_li)</code>.
  1754. The number of samples returned may be 0 if the buffer was too small
  1755. to store even a single sample for all channels, or if end-of-file
  1756. was reached.
  1757. The list of possible failure codes follows.
  1758. Most of them can only be returned by unseekable, chained streams
  1759. that encounter a new link.
  1760. \retval #OP_HOLE There was a hole in the data, and some samples
  1761. may have been skipped.
  1762. Call this function again to continue decoding
  1763. past the hole.
  1764. \retval #OP_EREAD An underlying read operation failed.
  1765. This may signal a truncation attack from an
  1766. <https:> source.
  1767. \retval #OP_EFAULT An internal memory allocation failed.
  1768. \retval #OP_EIMPL An unseekable stream encountered a new link that
  1769. used a feature that is not implemented, such as
  1770. an unsupported channel family.
  1771. \retval #OP_EINVAL The stream was only partially open.
  1772. \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
  1773. did not have any logical Opus streams in it.
  1774. \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
  1775. required header packet that was not properly
  1776. formatted, contained illegal values, or was
  1777. missing altogether.
  1778. \retval #OP_EVERSION An unseekable stream encountered a new link with
  1779. an ID header that contained an unrecognized
  1780. version number.
  1781. \retval #OP_EBADPACKET Failed to properly decode the next packet.
  1782. \retval #OP_EBADLINK We failed to find data we had seen before.
  1783. \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
  1784. a starting timestamp that failed basic validity
  1785. checks.*/
  1786. OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
  1787. opus_int16 *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
  1788. /**Reads more samples from the stream.
  1789. \note Although \a _buf_size must indicate the total number of values that
  1790. can be stored in \a _pcm, the return value is the number of samples
  1791. <em>per channel</em>.
  1792. <ol>
  1793. <li>The channel count cannot be known a priori (reading more samples might
  1794. advance us into the next link, with a different channel count), so
  1795. \a _buf_size cannot also be in units of samples per channel,</li>
  1796. <li>Returning the samples per channel matches the <code>libopus</code> API
  1797. as closely as we're able,</li>
  1798. <li>Returning the total number of values instead of samples per channel
  1799. would mean the caller would need a division to compute the samples per
  1800. channel, and might worry about the possibility of getting back samples
  1801. for some channels and not others, and</li>
  1802. <li>This approach is relatively fool-proof: if an application passes too
  1803. small a value to \a _buf_size, they will simply get fewer samples back,
  1804. and if they assume the return value is the total number of values, then
  1805. they will simply read too few (rather than reading too many and going
  1806. off the end of the buffer).</li>
  1807. </ol>
  1808. \param _of The \c OggOpusFile from which to read.
  1809. \param[out] _pcm A buffer in which to store the output PCM samples as
  1810. signed floats at 48&nbsp;kHz with a nominal range of
  1811. <code>[-1.0,1.0]</code>.
  1812. Multiple channels are interleaved using the
  1813. <a href="https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-810004.3.9">Vorbis
  1814. channel ordering</a>.
  1815. This must have room for at least \a _buf_size floats.
  1816. \param _buf_size The number of floats that can be stored in \a _pcm.
  1817. It is recommended that this be large enough for at
  1818. least 120 ms of data at 48 kHz per channel (5760
  1819. samples per channel).
  1820. Smaller buffers will simply return less data, possibly
  1821. consuming more memory to buffer the data internally.
  1822. If less than \a _buf_size values are returned,
  1823. <tt>libopusfile</tt> makes no guarantee that the
  1824. remaining data in \a _pcm will be unmodified.
  1825. \param[out] _li The index of the link this data was decoded from.
  1826. You may pass <code>NULL</code> if you do not need this
  1827. information.
  1828. If this function fails (returning a negative value),
  1829. this parameter is left unset.
  1830. \return The number of samples read per channel on success, or a negative
  1831. value on failure.
  1832. The channel count can be retrieved on success by calling
  1833. <code>op_head(_of,*_li)</code>.
  1834. The number of samples returned may be 0 if the buffer was too small
  1835. to store even a single sample for all channels, or if end-of-file
  1836. was reached.
  1837. The list of possible failure codes follows.
  1838. Most of them can only be returned by unseekable, chained streams
  1839. that encounter a new link.
  1840. \retval #OP_HOLE There was a hole in the data, and some samples
  1841. may have been skipped.
  1842. Call this function again to continue decoding
  1843. past the hole.
  1844. \retval #OP_EREAD An underlying read operation failed.
  1845. This may signal a truncation attack from an
  1846. <https:> source.
  1847. \retval #OP_EFAULT An internal memory allocation failed.
  1848. \retval #OP_EIMPL An unseekable stream encountered a new link that
  1849. used a feature that is not implemented, such as
  1850. an unsupported channel family.
  1851. \retval #OP_EINVAL The stream was only partially open.
  1852. \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
  1853. did not have any logical Opus streams in it.
  1854. \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
  1855. required header packet that was not properly
  1856. formatted, contained illegal values, or was
  1857. missing altogether.
  1858. \retval #OP_EVERSION An unseekable stream encountered a new link with
  1859. an ID header that contained an unrecognized
  1860. version number.
  1861. \retval #OP_EBADPACKET Failed to properly decode the next packet.
  1862. \retval #OP_EBADLINK We failed to find data we had seen before.
  1863. \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
  1864. a starting timestamp that failed basic validity
  1865. checks.*/
  1866. OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
  1867. float *_pcm,int _buf_size,int *_li) OP_ARG_NONNULL(1);
  1868. /**Reads more samples from the stream and downmixes to stereo, if necessary.
  1869. This function is intended for simple players that want a uniform output
  1870. format, even if the channel count changes between links in a chained
  1871. stream.
  1872. \note \a _buf_size indicates the total number of values that can be stored
  1873. in \a _pcm, while the return value is the number of samples <em>per
  1874. channel</em>, even though the channel count is known, for consistency with
  1875. op_read().
  1876. \param _of The \c OggOpusFile from which to read.
  1877. \param[out] _pcm A buffer in which to store the output PCM samples, as
  1878. signed native-endian 16-bit values at 48&nbsp;kHz
  1879. with a nominal range of <code>[-32768,32767)</code>.
  1880. The left and right channels are interleaved in the
  1881. buffer.
  1882. This must have room for at least \a _buf_size values.
  1883. \param _buf_size The number of values that can be stored in \a _pcm.
  1884. It is recommended that this be large enough for at
  1885. least 120 ms of data at 48 kHz per channel (11520
  1886. values total).
  1887. Smaller buffers will simply return less data, possibly
  1888. consuming more memory to buffer the data internally.
  1889. If less than \a _buf_size values are returned,
  1890. <tt>libopusfile</tt> makes no guarantee that the
  1891. remaining data in \a _pcm will be unmodified.
  1892. \return The number of samples read per channel on success, or a negative
  1893. value on failure.
  1894. The number of samples returned may be 0 if the buffer was too small
  1895. to store even a single sample for both channels, or if end-of-file
  1896. was reached.
  1897. The list of possible failure codes follows.
  1898. Most of them can only be returned by unseekable, chained streams
  1899. that encounter a new link.
  1900. \retval #OP_HOLE There was a hole in the data, and some samples
  1901. may have been skipped.
  1902. Call this function again to continue decoding
  1903. past the hole.
  1904. \retval #OP_EREAD An underlying read operation failed.
  1905. This may signal a truncation attack from an
  1906. <https:> source.
  1907. \retval #OP_EFAULT An internal memory allocation failed.
  1908. \retval #OP_EIMPL An unseekable stream encountered a new link that
  1909. used a feature that is not implemented, such as
  1910. an unsupported channel family.
  1911. \retval #OP_EINVAL The stream was only partially open.
  1912. \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
  1913. did not have any logical Opus streams in it.
  1914. \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
  1915. required header packet that was not properly
  1916. formatted, contained illegal values, or was
  1917. missing altogether.
  1918. \retval #OP_EVERSION An unseekable stream encountered a new link with
  1919. an ID header that contained an unrecognized
  1920. version number.
  1921. \retval #OP_EBADPACKET Failed to properly decode the next packet.
  1922. \retval #OP_EBADLINK We failed to find data we had seen before.
  1923. \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
  1924. a starting timestamp that failed basic validity
  1925. checks.*/
  1926. OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
  1927. opus_int16 *_pcm,int _buf_size) OP_ARG_NONNULL(1);
  1928. /**Reads more samples from the stream and downmixes to stereo, if necessary.
  1929. This function is intended for simple players that want a uniform output
  1930. format, even if the channel count changes between links in a chained
  1931. stream.
  1932. \note \a _buf_size indicates the total number of values that can be stored
  1933. in \a _pcm, while the return value is the number of samples <em>per
  1934. channel</em>, even though the channel count is known, for consistency with
  1935. op_read_float().
  1936. \param _of The \c OggOpusFile from which to read.
  1937. \param[out] _pcm A buffer in which to store the output PCM samples, as
  1938. signed floats at 48&nbsp;kHz with a nominal range of
  1939. <code>[-1.0,1.0]</code>.
  1940. The left and right channels are interleaved in the
  1941. buffer.
  1942. This must have room for at least \a _buf_size values.
  1943. \param _buf_size The number of values that can be stored in \a _pcm.
  1944. It is recommended that this be large enough for at
  1945. least 120 ms of data at 48 kHz per channel (11520
  1946. values total).
  1947. Smaller buffers will simply return less data, possibly
  1948. consuming more memory to buffer the data internally.
  1949. If less than \a _buf_size values are returned,
  1950. <tt>libopusfile</tt> makes no guarantee that the
  1951. remaining data in \a _pcm will be unmodified.
  1952. \return The number of samples read per channel on success, or a negative
  1953. value on failure.
  1954. The number of samples returned may be 0 if the buffer was too small
  1955. to store even a single sample for both channels, or if end-of-file
  1956. was reached.
  1957. The list of possible failure codes follows.
  1958. Most of them can only be returned by unseekable, chained streams
  1959. that encounter a new link.
  1960. \retval #OP_HOLE There was a hole in the data, and some samples
  1961. may have been skipped.
  1962. Call this function again to continue decoding
  1963. past the hole.
  1964. \retval #OP_EREAD An underlying read operation failed.
  1965. This may signal a truncation attack from an
  1966. <https:> source.
  1967. \retval #OP_EFAULT An internal memory allocation failed.
  1968. \retval #OP_EIMPL An unseekable stream encountered a new link that
  1969. used a feature that is not implemented, such as
  1970. an unsupported channel family.
  1971. \retval #OP_EINVAL The stream was only partially open.
  1972. \retval #OP_ENOTFORMAT An unseekable stream encountered a new link that
  1973. that did not have any logical Opus streams in it.
  1974. \retval #OP_EBADHEADER An unseekable stream encountered a new link with a
  1975. required header packet that was not properly
  1976. formatted, contained illegal values, or was
  1977. missing altogether.
  1978. \retval #OP_EVERSION An unseekable stream encountered a new link with
  1979. an ID header that contained an unrecognized
  1980. version number.
  1981. \retval #OP_EBADPACKET Failed to properly decode the next packet.
  1982. \retval #OP_EBADLINK We failed to find data we had seen before.
  1983. \retval #OP_EBADTIMESTAMP An unseekable stream encountered a new link with
  1984. a starting timestamp that failed basic validity
  1985. checks.*/
  1986. OP_WARN_UNUSED_RESULT int op_read_float_stereo(OggOpusFile *_of,
  1987. float *_pcm,int _buf_size) OP_ARG_NONNULL(1);
  1988. /**@}*/
  1989. /**@}*/
  1990. # if OP_GNUC_PREREQ(4,0)
  1991. # pragma GCC visibility pop
  1992. # endif
  1993. # if defined(__cplusplus)
  1994. }
  1995. # endif
  1996. #endif