stream_decoder.h 70 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584
  1. /* libFLAC - Free Lossless Audio Codec library
  2. * Copyright (C) 2000-2009 Josh Coalson
  3. * Copyright (C) 2011-2022 Xiph.Org Foundation
  4. *
  5. * Redistribution and use in source and binary forms, with or without
  6. * modification, are permitted provided that the following conditions
  7. * are met:
  8. *
  9. * - Redistributions of source code must retain the above copyright
  10. * notice, this list of conditions and the following disclaimer.
  11. *
  12. * - Redistributions in binary form must reproduce the above copyright
  13. * notice, this list of conditions and the following disclaimer in the
  14. * documentation and/or other materials provided with the distribution.
  15. *
  16. * - Neither the name of the Xiph.org Foundation nor the names of its
  17. * contributors may be used to endorse or promote products derived from
  18. * this software without specific prior written permission.
  19. *
  20. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21. * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22. * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23. * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
  24. * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25. * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26. * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  27. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  28. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31. */
  32. #ifndef FLAC__STREAM_DECODER_H
  33. #define FLAC__STREAM_DECODER_H
  34. #include <stdio.h> /* for FILE */
  35. #include "export.h"
  36. #include "format.h"
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40. /** \file include/FLAC/stream_decoder.h
  41. *
  42. * \brief
  43. * This module contains the functions which implement the stream
  44. * decoder.
  45. *
  46. * See the detailed documentation in the
  47. * \link flac_stream_decoder stream decoder \endlink module.
  48. */
  49. /** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
  50. * \ingroup flac
  51. *
  52. * \brief
  53. * This module describes the decoder layers provided by libFLAC.
  54. *
  55. * The stream decoder can be used to decode complete streams either from
  56. * the client via callbacks, or directly from a file, depending on how
  57. * it is initialized. When decoding via callbacks, the client provides
  58. * callbacks for reading FLAC data and writing decoded samples, and
  59. * handling metadata and errors. If the client also supplies seek-related
  60. * callback, the decoder function for sample-accurate seeking within the
  61. * FLAC input is also available. When decoding from a file, the client
  62. * needs only supply a filename or open \c FILE* and write/metadata/error
  63. * callbacks; the rest of the callbacks are supplied internally. For more
  64. * info see the \link flac_stream_decoder stream decoder \endlink module.
  65. */
  66. /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
  67. * \ingroup flac_decoder
  68. *
  69. * \brief
  70. * This module contains the functions which implement the stream
  71. * decoder.
  72. *
  73. * The stream decoder can decode native FLAC, and optionally Ogg FLAC
  74. * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
  75. *
  76. * The basic usage of this decoder is as follows:
  77. * - The program creates an instance of a decoder using
  78. * FLAC__stream_decoder_new().
  79. * - The program overrides the default settings using
  80. * FLAC__stream_decoder_set_*() functions.
  81. * - The program initializes the instance to validate the settings and
  82. * prepare for decoding using
  83. * - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE()
  84. * or FLAC__stream_decoder_init_file() for native FLAC,
  85. * - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE()
  86. * or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC
  87. * - The program calls the FLAC__stream_decoder_process_*() functions
  88. * to decode data, which subsequently calls the callbacks.
  89. * - The program finishes the decoding with FLAC__stream_decoder_finish(),
  90. * which flushes the input and output and resets the decoder to the
  91. * uninitialized state.
  92. * - The instance may be used again or deleted with
  93. * FLAC__stream_decoder_delete().
  94. *
  95. * In more detail, the program will create a new instance by calling
  96. * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
  97. * functions to override the default decoder options, and call
  98. * one of the FLAC__stream_decoder_init_*() functions.
  99. *
  100. * There are three initialization functions for native FLAC, one for
  101. * setting up the decoder to decode FLAC data from the client via
  102. * callbacks, and two for decoding directly from a FLAC file.
  103. *
  104. * For decoding via callbacks, use FLAC__stream_decoder_init_stream().
  105. * You must also supply several callbacks for handling I/O. Some (like
  106. * seeking) are optional, depending on the capabilities of the input.
  107. *
  108. * For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
  109. * or FLAC__stream_decoder_init_file(). Then you must only supply an open
  110. * \c FILE* or filename and fewer callbacks; the decoder will handle
  111. * the other callbacks internally.
  112. *
  113. * There are three similarly-named init functions for decoding from Ogg
  114. * FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  115. * library has been built with Ogg support.
  116. *
  117. * Once the decoder is initialized, your program will call one of several
  118. * functions to start the decoding process:
  119. *
  120. * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
  121. * most one metadata block or audio frame and return, calling either the
  122. * metadata callback or write callback, respectively, once. If the decoder
  123. * loses sync it will return with only the error callback being called.
  124. * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
  125. * to process the stream from the current location and stop upon reaching
  126. * the first audio frame. The client will get one metadata, write, or error
  127. * callback per metadata block, audio frame, or sync error, respectively.
  128. * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
  129. * to process the stream from the current location until the read callback
  130. * returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
  131. * FLAC__STREAM_DECODER_READ_STATUS_ABORT. The client will get one metadata,
  132. * write, or error callback per metadata block, audio frame, or sync error,
  133. * respectively.
  134. *
  135. * When the decoder has finished decoding (normally or through an abort),
  136. * the instance is finished by calling FLAC__stream_decoder_finish(), which
  137. * ensures the decoder is in the correct state and frees memory. Then the
  138. * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  139. * again to decode another stream.
  140. *
  141. * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
  142. * At any point after the stream decoder has been initialized, the client can
  143. * call this function to seek to an exact sample within the stream.
  144. * Subsequently, the first time the write callback is called it will be
  145. * passed a (possibly partial) block starting at that sample.
  146. *
  147. * If the client cannot seek via the callback interface provided, but still
  148. * has another way of seeking, it can flush the decoder using
  149. * FLAC__stream_decoder_flush() and start feeding data from the new position
  150. * through the read callback.
  151. *
  152. * The stream decoder also provides MD5 signature checking. If this is
  153. * turned on before initialization, FLAC__stream_decoder_finish() will
  154. * report when the decoded MD5 signature does not match the one stored
  155. * in the STREAMINFO block. MD5 checking is automatically turned off
  156. * (until the next FLAC__stream_decoder_reset()) if there is no signature
  157. * in the STREAMINFO block or when a seek is attempted.
  158. *
  159. * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  160. * attention. By default, the decoder only calls the metadata_callback for
  161. * the STREAMINFO block. These functions allow you to tell the decoder
  162. * explicitly which blocks to parse and return via the metadata_callback
  163. * and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(),
  164. * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
  165. * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
  166. * which blocks to return. Remember that metadata blocks can potentially
  167. * be big (for example, cover art) so filtering out the ones you don't
  168. * use can reduce the memory requirements of the decoder. Also note the
  169. * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
  170. * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
  171. * filtering APPLICATION blocks based on the application ID.
  172. *
  173. * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  174. * they still can legally be filtered from the metadata_callback.
  175. *
  176. * \note
  177. * The "set" functions may only be called when the decoder is in the
  178. * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
  179. * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
  180. * before FLAC__stream_decoder_init_*(). If this is the case they will
  181. * return \c true, otherwise \c false.
  182. *
  183. * \note
  184. * FLAC__stream_decoder_finish() resets all settings to the constructor
  185. * defaults, including the callbacks.
  186. *
  187. * \{
  188. */
  189. /** State values for a FLAC__StreamDecoder
  190. *
  191. * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  192. */
  193. typedef enum {
  194. FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
  195. /**< The decoder is ready to search for metadata. */
  196. FLAC__STREAM_DECODER_READ_METADATA,
  197. /**< The decoder is ready to or is in the process of reading metadata. */
  198. FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
  199. /**< The decoder is ready to or is in the process of searching for the
  200. * frame sync code.
  201. */
  202. FLAC__STREAM_DECODER_READ_FRAME,
  203. /**< The decoder is ready to or is in the process of reading a frame. */
  204. FLAC__STREAM_DECODER_END_OF_STREAM,
  205. /**< The decoder has reached the end of the stream. */
  206. FLAC__STREAM_DECODER_OGG_ERROR,
  207. /**< An error occurred in the underlying Ogg layer. */
  208. FLAC__STREAM_DECODER_SEEK_ERROR,
  209. /**< An error occurred while seeking. The decoder must be flushed
  210. * with FLAC__stream_decoder_flush() or reset with
  211. * FLAC__stream_decoder_reset() before decoding can continue.
  212. */
  213. FLAC__STREAM_DECODER_ABORTED,
  214. /**< The decoder was aborted by the read or write callback. */
  215. FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  216. /**< An error occurred allocating memory. The decoder is in an invalid
  217. * state and can no longer be used.
  218. */
  219. FLAC__STREAM_DECODER_UNINITIALIZED
  220. /**< The decoder is in the uninitialized state; one of the
  221. * FLAC__stream_decoder_init_*() functions must be called before samples
  222. * can be processed.
  223. */
  224. } FLAC__StreamDecoderState;
  225. /** Maps a FLAC__StreamDecoderState to a C string.
  226. *
  227. * Using a FLAC__StreamDecoderState as the index to this array
  228. * will give the string equivalent. The contents should not be modified.
  229. */
  230. extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
  231. /** Possible return values for the FLAC__stream_decoder_init_*() functions.
  232. */
  233. typedef enum {
  234. FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
  235. /**< Initialization was successful. */
  236. FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  237. /**< The library was not compiled with support for the given container
  238. * format.
  239. */
  240. FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
  241. /**< A required callback was not supplied. */
  242. FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
  243. /**< An error occurred allocating memory. */
  244. FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
  245. /**< fopen() failed in FLAC__stream_decoder_init_file() or
  246. * FLAC__stream_decoder_init_ogg_file(). */
  247. FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
  248. /**< FLAC__stream_decoder_init_*() was called when the decoder was
  249. * already initialized, usually because
  250. * FLAC__stream_decoder_finish() was not called.
  251. */
  252. } FLAC__StreamDecoderInitStatus;
  253. /** Maps a FLAC__StreamDecoderInitStatus to a C string.
  254. *
  255. * Using a FLAC__StreamDecoderInitStatus as the index to this array
  256. * will give the string equivalent. The contents should not be modified.
  257. */
  258. extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
  259. /** Return values for the FLAC__StreamDecoder read callback.
  260. */
  261. typedef enum {
  262. FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
  263. /**< The read was OK and decoding can continue. */
  264. FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
  265. /**< The read was attempted while at the end of the stream. Note that
  266. * the client must only return this value when the read callback was
  267. * called when already at the end of the stream. Otherwise, if the read
  268. * itself moves to the end of the stream, the client should still return
  269. * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
  270. * the next read callback it should return
  271. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
  272. * of \c 0.
  273. */
  274. FLAC__STREAM_DECODER_READ_STATUS_ABORT
  275. /**< An unrecoverable error occurred. The decoder will return from the process call. */
  276. } FLAC__StreamDecoderReadStatus;
  277. /** Maps a FLAC__StreamDecoderReadStatus to a C string.
  278. *
  279. * Using a FLAC__StreamDecoderReadStatus as the index to this array
  280. * will give the string equivalent. The contents should not be modified.
  281. */
  282. extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
  283. /** Return values for the FLAC__StreamDecoder seek callback.
  284. */
  285. typedef enum {
  286. FLAC__STREAM_DECODER_SEEK_STATUS_OK,
  287. /**< The seek was OK and decoding can continue. */
  288. FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
  289. /**< An unrecoverable error occurred. The decoder will return from the process call. */
  290. FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  291. /**< Client does not support seeking. */
  292. } FLAC__StreamDecoderSeekStatus;
  293. /** Maps a FLAC__StreamDecoderSeekStatus to a C string.
  294. *
  295. * Using a FLAC__StreamDecoderSeekStatus as the index to this array
  296. * will give the string equivalent. The contents should not be modified.
  297. */
  298. extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
  299. /** Return values for the FLAC__StreamDecoder tell callback.
  300. */
  301. typedef enum {
  302. FLAC__STREAM_DECODER_TELL_STATUS_OK,
  303. /**< The tell was OK and decoding can continue. */
  304. FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
  305. /**< An unrecoverable error occurred. The decoder will return from the process call. */
  306. FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  307. /**< Client does not support telling the position. */
  308. } FLAC__StreamDecoderTellStatus;
  309. /** Maps a FLAC__StreamDecoderTellStatus to a C string.
  310. *
  311. * Using a FLAC__StreamDecoderTellStatus as the index to this array
  312. * will give the string equivalent. The contents should not be modified.
  313. */
  314. extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
  315. /** Return values for the FLAC__StreamDecoder length callback.
  316. */
  317. typedef enum {
  318. FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
  319. /**< The length call was OK and decoding can continue. */
  320. FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
  321. /**< An unrecoverable error occurred. The decoder will return from the process call. */
  322. FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  323. /**< Client does not support reporting the length. */
  324. } FLAC__StreamDecoderLengthStatus;
  325. /** Maps a FLAC__StreamDecoderLengthStatus to a C string.
  326. *
  327. * Using a FLAC__StreamDecoderLengthStatus as the index to this array
  328. * will give the string equivalent. The contents should not be modified.
  329. */
  330. extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
  331. /** Return values for the FLAC__StreamDecoder write callback.
  332. */
  333. typedef enum {
  334. FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
  335. /**< The write was OK and decoding can continue. */
  336. FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
  337. /**< An unrecoverable error occurred. The decoder will return from the process call. */
  338. } FLAC__StreamDecoderWriteStatus;
  339. /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
  340. *
  341. * Using a FLAC__StreamDecoderWriteStatus as the index to this array
  342. * will give the string equivalent. The contents should not be modified.
  343. */
  344. extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
  345. /** Possible values passed back to the FLAC__StreamDecoder error callback.
  346. * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
  347. * all. The rest could be caused by bad sync (false synchronization on
  348. * data that is not the start of a frame) or corrupted data. The error
  349. * itself is the decoder's best guess at what happened assuming a correct
  350. * sync. For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
  351. * could be caused by a correct sync on the start of a frame, but some
  352. * data in the frame header was corrupted. Or it could be the result of
  353. * syncing on a point the stream that looked like the starting of a frame
  354. * but was not. \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
  355. * could be because the decoder encountered a valid frame made by a future
  356. * version of the encoder which it cannot parse, or because of a false
  357. * sync making it appear as though an encountered frame was generated by
  358. * a future encoder. \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA is
  359. * caused by finding data that doesn't fit a metadata block (too large
  360. * or too small) or finding inconsistencies in the metadata, for example
  361. * a PICTURE block with an image that exceeds the size of the metadata
  362. * block.
  363. */
  364. typedef enum {
  365. FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
  366. /**< An error in the stream caused the decoder to lose synchronization. */
  367. FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
  368. /**< The decoder encountered a corrupted frame header. */
  369. FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
  370. /**< The frame's data did not match the CRC in the footer. */
  371. FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM,
  372. /**< The decoder encountered reserved fields in use in the stream. */
  373. FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA
  374. /**< The decoder encountered a corrupted metadata block. */
  375. } FLAC__StreamDecoderErrorStatus;
  376. /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
  377. *
  378. * Using a FLAC__StreamDecoderErrorStatus as the index to this array
  379. * will give the string equivalent. The contents should not be modified.
  380. */
  381. extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
  382. /***********************************************************************
  383. *
  384. * class FLAC__StreamDecoder
  385. *
  386. ***********************************************************************/
  387. struct FLAC__StreamDecoderProtected;
  388. struct FLAC__StreamDecoderPrivate;
  389. /** The opaque structure definition for the stream decoder type.
  390. * See the \link flac_stream_decoder stream decoder module \endlink
  391. * for a detailed description.
  392. */
  393. typedef struct {
  394. struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  395. struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  396. } FLAC__StreamDecoder;
  397. /** Signature for the read callback.
  398. *
  399. * A function pointer matching this signature must be passed to
  400. * FLAC__stream_decoder_init*_stream(). The supplied function will be
  401. * called when the decoder needs more input data. The address of the
  402. * buffer to be filled is supplied, along with the number of bytes the
  403. * buffer can hold. The callback may choose to supply less data and
  404. * modify the byte count but must be careful not to overflow the buffer.
  405. * The callback then returns a status code chosen from
  406. * FLAC__StreamDecoderReadStatus.
  407. *
  408. * Here is an example of a read callback for stdio streams:
  409. * \code
  410. * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  411. * {
  412. * FILE *file = ((MyClientData*)client_data)->file;
  413. * if(*bytes > 0) {
  414. * *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  415. * if(ferror(file))
  416. * return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  417. * else if(*bytes == 0)
  418. * return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
  419. * else
  420. * return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
  421. * }
  422. * else
  423. * return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
  424. * }
  425. * \endcode
  426. *
  427. * \note In general, FLAC__StreamDecoder functions which change the
  428. * state should not be called on the \a decoder while in the callback.
  429. *
  430. * \param decoder The decoder instance calling the callback.
  431. * \param buffer A pointer to a location for the callee to store
  432. * data to be decoded.
  433. * \param bytes A pointer to the size of the buffer. On entry
  434. * to the callback, it contains the maximum number
  435. * of bytes that may be stored in \a buffer. The
  436. * callee must set it to the actual number of bytes
  437. * stored (0 in case of error or end-of-stream) before
  438. * returning.
  439. * \param client_data The callee's client data set through
  440. * FLAC__stream_decoder_init_*().
  441. * \retval FLAC__StreamDecoderReadStatus
  442. * The callee's return status. Note that the callback should return
  443. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if
  444. * zero bytes were read and there is no more data to be read.
  445. */
  446. typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  447. /** Signature for the seek callback.
  448. *
  449. * A function pointer matching this signature may be passed to
  450. * FLAC__stream_decoder_init*_stream(). The supplied function will be
  451. * called when the decoder needs to seek the input stream. The decoder
  452. * will pass the absolute byte offset to seek to, 0 meaning the
  453. * beginning of the stream.
  454. *
  455. * Here is an example of a seek callback for stdio streams:
  456. * \code
  457. * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  458. * {
  459. * FILE *file = ((MyClientData*)client_data)->file;
  460. * if(file == stdin)
  461. * return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
  462. * else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  463. * return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
  464. * else
  465. * return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
  466. * }
  467. * \endcode
  468. *
  469. * \note In general, FLAC__StreamDecoder functions which change the
  470. * state should not be called on the \a decoder while in the callback.
  471. *
  472. * \param decoder The decoder instance calling the callback.
  473. * \param absolute_byte_offset The offset from the beginning of the stream
  474. * to seek to.
  475. * \param client_data The callee's client data set through
  476. * FLAC__stream_decoder_init_*().
  477. * \retval FLAC__StreamDecoderSeekStatus
  478. * The callee's return status.
  479. */
  480. typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  481. /** Signature for the tell callback.
  482. *
  483. * A function pointer matching this signature may be passed to
  484. * FLAC__stream_decoder_init*_stream(). The supplied function will be
  485. * called when the decoder wants to know the current position of the
  486. * stream. The callback should return the byte offset from the
  487. * beginning of the stream.
  488. *
  489. * Here is an example of a tell callback for stdio streams:
  490. * \code
  491. * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  492. * {
  493. * FILE *file = ((MyClientData*)client_data)->file;
  494. * off_t pos;
  495. * if(file == stdin)
  496. * return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
  497. * else if((pos = ftello(file)) < 0)
  498. * return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
  499. * else {
  500. * *absolute_byte_offset = (FLAC__uint64)pos;
  501. * return FLAC__STREAM_DECODER_TELL_STATUS_OK;
  502. * }
  503. * }
  504. * \endcode
  505. *
  506. * \note In general, FLAC__StreamDecoder functions which change the
  507. * state should not be called on the \a decoder while in the callback.
  508. *
  509. * \param decoder The decoder instance calling the callback.
  510. * \param absolute_byte_offset A pointer to storage for the current offset
  511. * from the beginning of the stream.
  512. * \param client_data The callee's client data set through
  513. * FLAC__stream_decoder_init_*().
  514. * \retval FLAC__StreamDecoderTellStatus
  515. * The callee's return status.
  516. */
  517. typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  518. /** Signature for the length callback.
  519. *
  520. * A function pointer matching this signature may be passed to
  521. * FLAC__stream_decoder_init*_stream(). The supplied function will be
  522. * called when the decoder wants to know the total length of the stream
  523. * in bytes.
  524. *
  525. * Here is an example of a length callback for stdio streams:
  526. * \code
  527. * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
  528. * {
  529. * FILE *file = ((MyClientData*)client_data)->file;
  530. * struct stat filestats;
  531. *
  532. * if(file == stdin)
  533. * return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
  534. * else if(fstat(fileno(file), &filestats) != 0)
  535. * return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
  536. * else {
  537. * *stream_length = (FLAC__uint64)filestats.st_size;
  538. * return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
  539. * }
  540. * }
  541. * \endcode
  542. *
  543. * \note In general, FLAC__StreamDecoder functions which change the
  544. * state should not be called on the \a decoder while in the callback.
  545. *
  546. * \param decoder The decoder instance calling the callback.
  547. * \param stream_length A pointer to storage for the length of the stream
  548. * in bytes.
  549. * \param client_data The callee's client data set through
  550. * FLAC__stream_decoder_init_*().
  551. * \retval FLAC__StreamDecoderLengthStatus
  552. * The callee's return status.
  553. */
  554. typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
  555. /** Signature for the EOF callback.
  556. *
  557. * A function pointer matching this signature may be passed to
  558. * FLAC__stream_decoder_init*_stream(). The supplied function will be
  559. * called when the decoder needs to know if the end of the stream has
  560. * been reached.
  561. *
  562. * Here is an example of a EOF callback for stdio streams:
  563. * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data)
  564. * \code
  565. * {
  566. * FILE *file = ((MyClientData*)client_data)->file;
  567. * return feof(file)? true : false;
  568. * }
  569. * \endcode
  570. *
  571. * \note In general, FLAC__StreamDecoder functions which change the
  572. * state should not be called on the \a decoder while in the callback.
  573. *
  574. * \param decoder The decoder instance calling the callback.
  575. * \param client_data The callee's client data set through
  576. * FLAC__stream_decoder_init_*().
  577. * \retval FLAC__bool
  578. * \c true if the currently at the end of the stream, else \c false.
  579. */
  580. typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
  581. /** Signature for the write callback.
  582. *
  583. * A function pointer matching this signature must be passed to one of
  584. * the FLAC__stream_decoder_init_*() functions.
  585. * The supplied function will be called when the decoder has decoded a
  586. * single audio frame. The decoder will pass the frame metadata as well
  587. * as an array of pointers (one for each channel) pointing to the
  588. * decoded audio.
  589. *
  590. * \note In general, FLAC__StreamDecoder functions which change the
  591. * state should not be called on the \a decoder while in the callback.
  592. *
  593. * \param decoder The decoder instance calling the callback.
  594. * \param frame The description of the decoded frame. See
  595. * FLAC__Frame.
  596. * \param buffer An array of pointers to decoded channels of data.
  597. * Each pointer will point to an array of signed
  598. * samples of length \a frame->header.blocksize.
  599. * Channels will be ordered according to the FLAC
  600. * specification; see the documentation for the
  601. * <A HREF="https://xiph.org/flac/format.html#frame_header">frame header</A>.
  602. * \param client_data The callee's client data set through
  603. * FLAC__stream_decoder_init_*().
  604. * \retval FLAC__StreamDecoderWriteStatus
  605. * The callee's return status.
  606. */
  607. typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  608. /** Signature for the metadata callback.
  609. *
  610. * A function pointer matching this signature must be passed to one of
  611. * the FLAC__stream_decoder_init_*() functions.
  612. * The supplied function will be called when the decoder has decoded a
  613. * metadata block. In a valid FLAC file there will always be one
  614. * \c STREAMINFO block, followed by zero or more other metadata blocks.
  615. * These will be supplied by the decoder in the same order as they
  616. * appear in the stream and always before the first audio frame (i.e.
  617. * write callback). The metadata block that is passed in must not be
  618. * modified, and it doesn't live beyond the callback, so you should make
  619. * a copy of it with FLAC__metadata_object_clone() if you will need it
  620. * elsewhere. Since metadata blocks can potentially be large, by
  621. * default the decoder only calls the metadata callback for the
  622. * \c STREAMINFO block; you can instruct the decoder to pass or filter
  623. * other blocks with FLAC__stream_decoder_set_metadata_*() calls.
  624. *
  625. * \note In general, FLAC__StreamDecoder functions which change the
  626. * state should not be called on the \a decoder while in the callback.
  627. *
  628. * \param decoder The decoder instance calling the callback.
  629. * \param metadata The decoded metadata block.
  630. * \param client_data The callee's client data set through
  631. * FLAC__stream_decoder_init_*().
  632. */
  633. typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  634. /** Signature for the error callback.
  635. *
  636. * A function pointer matching this signature must be passed to one of
  637. * the FLAC__stream_decoder_init_*() functions.
  638. * The supplied function will be called whenever an error occurs during
  639. * decoding.
  640. *
  641. * \note In general, FLAC__StreamDecoder functions which change the
  642. * state should not be called on the \a decoder while in the callback.
  643. *
  644. * \param decoder The decoder instance calling the callback.
  645. * \param status The error encountered by the decoder.
  646. * \param client_data The callee's client data set through
  647. * FLAC__stream_decoder_init_*().
  648. */
  649. typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  650. /***********************************************************************
  651. *
  652. * Class constructor/destructor
  653. *
  654. ***********************************************************************/
  655. /** Create a new stream decoder instance. The instance is created with
  656. * default settings; see the individual FLAC__stream_decoder_set_*()
  657. * functions for each setting's default.
  658. *
  659. * \retval FLAC__StreamDecoder*
  660. * \c NULL if there was an error allocating memory, else the new instance.
  661. */
  662. FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void);
  663. /** Free a decoder instance. Deletes the object pointed to by \a decoder.
  664. *
  665. * \param decoder A pointer to an existing decoder.
  666. * \assert
  667. * \code decoder != NULL \endcode
  668. */
  669. FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  670. /***********************************************************************
  671. *
  672. * Public class method prototypes
  673. *
  674. ***********************************************************************/
  675. /** Set the serial number for the FLAC stream within the Ogg container.
  676. * The default behavior is to use the serial number of the first Ogg
  677. * page. Setting a serial number here will explicitly specify which
  678. * stream is to be decoded.
  679. *
  680. * \note
  681. * This does not need to be set for native FLAC decoding.
  682. *
  683. * \default \c use serial number of first page
  684. * \param decoder A decoder instance to set.
  685. * \param serial_number See above.
  686. * \assert
  687. * \code decoder != NULL \endcode
  688. * \retval FLAC__bool
  689. * \c false if the decoder is already initialized, else \c true.
  690. */
  691. FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
  692. /** Set the "MD5 signature checking" flag. If \c true, the decoder will
  693. * compute the MD5 signature of the unencoded audio data while decoding
  694. * and compare it to the signature from the STREAMINFO block, if it
  695. * exists, during FLAC__stream_decoder_finish().
  696. *
  697. * MD5 signature checking will be turned off (until the next
  698. * FLAC__stream_decoder_reset()) if there is no signature in the
  699. * STREAMINFO block or when a seek is attempted.
  700. *
  701. * Clients that do not use the MD5 check should leave this off to speed
  702. * up decoding.
  703. *
  704. * \default \c false
  705. * \param decoder A decoder instance to set.
  706. * \param value Flag value (see above).
  707. * \assert
  708. * \code decoder != NULL \endcode
  709. * \retval FLAC__bool
  710. * \c false if the decoder is already initialized, else \c true.
  711. */
  712. FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
  713. /** Direct the decoder to pass on all metadata blocks of type \a type.
  714. *
  715. * \default By default, only the \c STREAMINFO block is returned via the
  716. * metadata callback.
  717. * \param decoder A decoder instance to set.
  718. * \param type See above.
  719. * \assert
  720. * \code decoder != NULL \endcode
  721. * \a type is valid
  722. * \retval FLAC__bool
  723. * \c false if the decoder is already initialized, else \c true.
  724. */
  725. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  726. /** Direct the decoder to pass on all APPLICATION metadata blocks of the
  727. * given \a id.
  728. *
  729. * \default By default, only the \c STREAMINFO block is returned via the
  730. * metadata callback.
  731. * \param decoder A decoder instance to set.
  732. * \param id See above.
  733. * \assert
  734. * \code decoder != NULL \endcode
  735. * \code id != NULL \endcode
  736. * \retval FLAC__bool
  737. * \c false if the decoder is already initialized, else \c true.
  738. */
  739. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  740. /** Direct the decoder to pass on all metadata blocks of any type.
  741. *
  742. * \default By default, only the \c STREAMINFO block is returned via the
  743. * metadata callback.
  744. * \param decoder A decoder instance to set.
  745. * \assert
  746. * \code decoder != NULL \endcode
  747. * \retval FLAC__bool
  748. * \c false if the decoder is already initialized, else \c true.
  749. */
  750. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
  751. /** Direct the decoder to filter out all metadata blocks of type \a type.
  752. *
  753. * \default By default, only the \c STREAMINFO block is returned via the
  754. * metadata callback.
  755. * \param decoder A decoder instance to set.
  756. * \param type See above.
  757. * \assert
  758. * \code decoder != NULL \endcode
  759. * \a type is valid
  760. * \retval FLAC__bool
  761. * \c false if the decoder is already initialized, else \c true.
  762. */
  763. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  764. /** Direct the decoder to filter out all APPLICATION metadata blocks of
  765. * the given \a id.
  766. *
  767. * \default By default, only the \c STREAMINFO block is returned via the
  768. * metadata callback.
  769. * \param decoder A decoder instance to set.
  770. * \param id See above.
  771. * \assert
  772. * \code decoder != NULL \endcode
  773. * \code id != NULL \endcode
  774. * \retval FLAC__bool
  775. * \c false if the decoder is already initialized, else \c true.
  776. */
  777. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  778. /** Direct the decoder to filter out all metadata blocks of any type.
  779. *
  780. * \default By default, only the \c STREAMINFO block is returned via the
  781. * metadata callback.
  782. * \param decoder A decoder instance to set.
  783. * \assert
  784. * \code decoder != NULL \endcode
  785. * \retval FLAC__bool
  786. * \c false if the decoder is already initialized, else \c true.
  787. */
  788. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
  789. /** Get the current decoder state.
  790. *
  791. * \param decoder A decoder instance to query.
  792. * \assert
  793. * \code decoder != NULL \endcode
  794. * \retval FLAC__StreamDecoderState
  795. * The current decoder state.
  796. */
  797. FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
  798. /** Get the current decoder state as a C string.
  799. *
  800. * \param decoder A decoder instance to query.
  801. * \assert
  802. * \code decoder != NULL \endcode
  803. * \retval const char *
  804. * The decoder state as a C string. Do not modify the contents.
  805. */
  806. FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder);
  807. /** Get the "MD5 signature checking" flag.
  808. * This is the value of the setting, not whether or not the decoder is
  809. * currently checking the MD5 (remember, it can be turned off automatically
  810. * by a seek). When the decoder is reset the flag will be restored to the
  811. * value returned by this function.
  812. *
  813. * \param decoder A decoder instance to query.
  814. * \assert
  815. * \code decoder != NULL \endcode
  816. * \retval FLAC__bool
  817. * See above.
  818. */
  819. FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
  820. /** Get the total number of samples in the stream being decoded.
  821. * Will only be valid after decoding has started and will contain the
  822. * value from the \c STREAMINFO block. A value of \c 0 means "unknown".
  823. *
  824. * \param decoder A decoder instance to query.
  825. * \assert
  826. * \code decoder != NULL \endcode
  827. * \retval uint32_t
  828. * See above.
  829. */
  830. FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder);
  831. /** Get the current number of channels in the stream being decoded.
  832. * Will only be valid after decoding has started and will contain the
  833. * value from the most recently decoded frame header.
  834. *
  835. * \param decoder A decoder instance to query.
  836. * \assert
  837. * \code decoder != NULL \endcode
  838. * \retval uint32_t
  839. * See above.
  840. */
  841. FLAC_API uint32_t FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
  842. /** Get the current channel assignment in the stream being decoded.
  843. * Will only be valid after decoding has started and will contain the
  844. * value from the most recently decoded frame header.
  845. *
  846. * \param decoder A decoder instance to query.
  847. * \assert
  848. * \code decoder != NULL \endcode
  849. * \retval FLAC__ChannelAssignment
  850. * See above.
  851. */
  852. FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
  853. /** Get the current sample resolution in the stream being decoded.
  854. * Will only be valid after decoding has started and will contain the
  855. * value from the most recently decoded frame header.
  856. *
  857. * \param decoder A decoder instance to query.
  858. * \assert
  859. * \code decoder != NULL \endcode
  860. * \retval uint32_t
  861. * See above.
  862. */
  863. FLAC_API uint32_t FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
  864. /** Get the current sample rate in Hz of the stream being decoded.
  865. * Will only be valid after decoding has started and will contain the
  866. * value from the most recently decoded frame header.
  867. *
  868. * \param decoder A decoder instance to query.
  869. * \assert
  870. * \code decoder != NULL \endcode
  871. * \retval uint32_t
  872. * See above.
  873. */
  874. FLAC_API uint32_t FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
  875. /** Get the current blocksize of the stream being decoded.
  876. * Will only be valid after decoding has started and will contain the
  877. * value from the most recently decoded frame header.
  878. *
  879. * \param decoder A decoder instance to query.
  880. * \assert
  881. * \code decoder != NULL \endcode
  882. * \retval uint32_t
  883. * See above.
  884. */
  885. FLAC_API uint32_t FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
  886. /** Returns the decoder's current read position within the stream.
  887. * The position is the byte offset from the start of the stream.
  888. * Bytes before this position have been fully decoded. Note that
  889. * there may still be undecoded bytes in the decoder's read FIFO.
  890. * The returned position is correct even after a seek.
  891. *
  892. * \warning This function currently only works for native FLAC,
  893. * not Ogg FLAC streams.
  894. *
  895. * \param decoder A decoder instance to query.
  896. * \param position Address at which to return the desired position.
  897. * \assert
  898. * \code decoder != NULL \endcode
  899. * \code position != NULL \endcode
  900. * \retval FLAC__bool
  901. * \c true if successful, \c false if the stream is not native FLAC,
  902. * or there was an error from the 'tell' callback or it returned
  903. * \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
  904. */
  905. FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
  906. /** Return client_data from decoder.
  907. * The data pointed to by the pointer should not be modified.
  908. *
  909. * \param decoder A decoder instance.
  910. * \retval const void *
  911. * The callee's client data set through FLAC__stream_decoder_init_*().
  912. * Do not modify the contents.
  913. */
  914. FLAC_API const void *FLAC__stream_decoder_get_client_data(FLAC__StreamDecoder *decoder);
  915. /** Initialize the decoder instance to decode native FLAC streams.
  916. *
  917. * This flavor of initialization sets up the decoder to decode from a
  918. * native FLAC stream. I/O is performed via callbacks to the client.
  919. * For decoding from a plain file via filename or open FILE*,
  920. * FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE()
  921. * provide a simpler interface.
  922. *
  923. * This function should be called after FLAC__stream_decoder_new() and
  924. * FLAC__stream_decoder_set_*() but before any of the
  925. * FLAC__stream_decoder_process_*() functions. Will set and return the
  926. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  927. * if initialization succeeded.
  928. *
  929. * \param decoder An uninitialized decoder instance.
  930. * \param read_callback See FLAC__StreamDecoderReadCallback. This
  931. * pointer must not be \c NULL.
  932. * \param seek_callback See FLAC__StreamDecoderSeekCallback. This
  933. * pointer may be \c NULL if seeking is not
  934. * supported. If \a seek_callback is not \c NULL then a
  935. * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
  936. * Alternatively, a dummy seek callback that just
  937. * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  938. * may also be supplied, all though this is slightly
  939. * less efficient for the decoder.
  940. * \param tell_callback See FLAC__StreamDecoderTellCallback. This
  941. * pointer may be \c NULL if not supported by the client. If
  942. * \a seek_callback is not \c NULL then a
  943. * \a tell_callback must also be supplied.
  944. * Alternatively, a dummy tell callback that just
  945. * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  946. * may also be supplied, all though this is slightly
  947. * less efficient for the decoder.
  948. * \param length_callback See FLAC__StreamDecoderLengthCallback. This
  949. * pointer may be \c NULL if not supported by the client. If
  950. * \a seek_callback is not \c NULL then a
  951. * \a length_callback must also be supplied.
  952. * Alternatively, a dummy length callback that just
  953. * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  954. * may also be supplied, all though this is slightly
  955. * less efficient for the decoder.
  956. * \param eof_callback See FLAC__StreamDecoderEofCallback. This
  957. * pointer may be \c NULL if not supported by the client. If
  958. * \a seek_callback is not \c NULL then a
  959. * \a eof_callback must also be supplied.
  960. * Alternatively, a dummy length callback that just
  961. * returns \c false
  962. * may also be supplied, all though this is slightly
  963. * less efficient for the decoder.
  964. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  965. * pointer must not be \c NULL.
  966. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  967. * pointer may be \c NULL if the callback is not
  968. * desired.
  969. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  970. * pointer must not be \c NULL.
  971. * \param client_data This value will be supplied to callbacks in their
  972. * \a client_data argument.
  973. * \assert
  974. * \code decoder != NULL \endcode
  975. * \retval FLAC__StreamDecoderInitStatus
  976. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  977. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  978. */
  979. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
  980. FLAC__StreamDecoder *decoder,
  981. FLAC__StreamDecoderReadCallback read_callback,
  982. FLAC__StreamDecoderSeekCallback seek_callback,
  983. FLAC__StreamDecoderTellCallback tell_callback,
  984. FLAC__StreamDecoderLengthCallback length_callback,
  985. FLAC__StreamDecoderEofCallback eof_callback,
  986. FLAC__StreamDecoderWriteCallback write_callback,
  987. FLAC__StreamDecoderMetadataCallback metadata_callback,
  988. FLAC__StreamDecoderErrorCallback error_callback,
  989. void *client_data
  990. );
  991. /** Initialize the decoder instance to decode Ogg FLAC streams.
  992. *
  993. * This flavor of initialization sets up the decoder to decode from a
  994. * FLAC stream in an Ogg container. I/O is performed via callbacks to the
  995. * client. For decoding from a plain file via filename or open FILE*,
  996. * FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE()
  997. * provide a simpler interface.
  998. *
  999. * This function should be called after FLAC__stream_decoder_new() and
  1000. * FLAC__stream_decoder_set_*() but before any of the
  1001. * FLAC__stream_decoder_process_*() functions. Will set and return the
  1002. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  1003. * if initialization succeeded.
  1004. *
  1005. * \note Support for Ogg FLAC in the library is optional. If this
  1006. * library has been built without support for Ogg FLAC, this function
  1007. * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
  1008. *
  1009. * \param decoder An uninitialized decoder instance.
  1010. * \param read_callback See FLAC__StreamDecoderReadCallback. This
  1011. * pointer must not be \c NULL.
  1012. * \param seek_callback See FLAC__StreamDecoderSeekCallback. This
  1013. * pointer may be \c NULL if seeking is not
  1014. * supported. If \a seek_callback is not \c NULL then a
  1015. * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
  1016. * Alternatively, a dummy seek callback that just
  1017. * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
  1018. * may also be supplied, all though this is slightly
  1019. * less efficient for the decoder.
  1020. * \param tell_callback See FLAC__StreamDecoderTellCallback. This
  1021. * pointer may be \c NULL if not supported by the client. If
  1022. * \a seek_callback is not \c NULL then a
  1023. * \a tell_callback must also be supplied.
  1024. * Alternatively, a dummy tell callback that just
  1025. * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
  1026. * may also be supplied, all though this is slightly
  1027. * less efficient for the decoder.
  1028. * \param length_callback See FLAC__StreamDecoderLengthCallback. This
  1029. * pointer may be \c NULL if not supported by the client. If
  1030. * \a seek_callback is not \c NULL then a
  1031. * \a length_callback must also be supplied.
  1032. * Alternatively, a dummy length callback that just
  1033. * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
  1034. * may also be supplied, all though this is slightly
  1035. * less efficient for the decoder.
  1036. * \param eof_callback See FLAC__StreamDecoderEofCallback. This
  1037. * pointer may be \c NULL if not supported by the client. If
  1038. * \a seek_callback is not \c NULL then a
  1039. * \a eof_callback must also be supplied.
  1040. * Alternatively, a dummy length callback that just
  1041. * returns \c false
  1042. * may also be supplied, all though this is slightly
  1043. * less efficient for the decoder.
  1044. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  1045. * pointer must not be \c NULL.
  1046. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  1047. * pointer may be \c NULL if the callback is not
  1048. * desired.
  1049. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  1050. * pointer must not be \c NULL.
  1051. * \param client_data This value will be supplied to callbacks in their
  1052. * \a client_data argument.
  1053. * \assert
  1054. * \code decoder != NULL \endcode
  1055. * \retval FLAC__StreamDecoderInitStatus
  1056. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  1057. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  1058. */
  1059. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream(
  1060. FLAC__StreamDecoder *decoder,
  1061. FLAC__StreamDecoderReadCallback read_callback,
  1062. FLAC__StreamDecoderSeekCallback seek_callback,
  1063. FLAC__StreamDecoderTellCallback tell_callback,
  1064. FLAC__StreamDecoderLengthCallback length_callback,
  1065. FLAC__StreamDecoderEofCallback eof_callback,
  1066. FLAC__StreamDecoderWriteCallback write_callback,
  1067. FLAC__StreamDecoderMetadataCallback metadata_callback,
  1068. FLAC__StreamDecoderErrorCallback error_callback,
  1069. void *client_data
  1070. );
  1071. /** Initialize the decoder instance to decode native FLAC files.
  1072. *
  1073. * This flavor of initialization sets up the decoder to decode from a
  1074. * plain native FLAC file. For non-stdio streams, you must use
  1075. * FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
  1076. *
  1077. * This function should be called after FLAC__stream_decoder_new() and
  1078. * FLAC__stream_decoder_set_*() but before any of the
  1079. * FLAC__stream_decoder_process_*() functions. Will set and return the
  1080. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  1081. * if initialization succeeded.
  1082. *
  1083. * \param decoder An uninitialized decoder instance.
  1084. * \param file An open FLAC file. The file should have been
  1085. * opened with mode \c "rb" and rewound. The file
  1086. * becomes owned by the decoder and should not be
  1087. * manipulated by the client while decoding.
  1088. * Unless \a file is \c stdin, it will be closed
  1089. * when FLAC__stream_decoder_finish() is called.
  1090. * Note however that seeking will not work when
  1091. * decoding from \c stdin since it is not seekable.
  1092. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  1093. * pointer must not be \c NULL.
  1094. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  1095. * pointer may be \c NULL if the callback is not
  1096. * desired.
  1097. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  1098. * pointer must not be \c NULL.
  1099. * \param client_data This value will be supplied to callbacks in their
  1100. * \a client_data argument.
  1101. * \assert
  1102. * \code decoder != NULL \endcode
  1103. * \code file != NULL \endcode
  1104. * \retval FLAC__StreamDecoderInitStatus
  1105. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  1106. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  1107. */
  1108. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
  1109. FLAC__StreamDecoder *decoder,
  1110. FILE *file,
  1111. FLAC__StreamDecoderWriteCallback write_callback,
  1112. FLAC__StreamDecoderMetadataCallback metadata_callback,
  1113. FLAC__StreamDecoderErrorCallback error_callback,
  1114. void *client_data
  1115. );
  1116. /** Initialize the decoder instance to decode Ogg FLAC files.
  1117. *
  1118. * This flavor of initialization sets up the decoder to decode from a
  1119. * plain Ogg FLAC file. For non-stdio streams, you must use
  1120. * FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.
  1121. *
  1122. * This function should be called after FLAC__stream_decoder_new() and
  1123. * FLAC__stream_decoder_set_*() but before any of the
  1124. * FLAC__stream_decoder_process_*() functions. Will set and return the
  1125. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  1126. * if initialization succeeded.
  1127. *
  1128. * \note Support for Ogg FLAC in the library is optional. If this
  1129. * library has been built without support for Ogg FLAC, this function
  1130. * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
  1131. *
  1132. * \param decoder An uninitialized decoder instance.
  1133. * \param file An open FLAC file. The file should have been
  1134. * opened with mode \c "rb" and rewound. The file
  1135. * becomes owned by the decoder and should not be
  1136. * manipulated by the client while decoding.
  1137. * Unless \a file is \c stdin, it will be closed
  1138. * when FLAC__stream_decoder_finish() is called.
  1139. * Note however that seeking will not work when
  1140. * decoding from \c stdin since it is not seekable.
  1141. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  1142. * pointer must not be \c NULL.
  1143. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  1144. * pointer may be \c NULL if the callback is not
  1145. * desired.
  1146. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  1147. * pointer must not be \c NULL.
  1148. * \param client_data This value will be supplied to callbacks in their
  1149. * \a client_data argument.
  1150. * \assert
  1151. * \code decoder != NULL \endcode
  1152. * \code file != NULL \endcode
  1153. * \retval FLAC__StreamDecoderInitStatus
  1154. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  1155. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  1156. */
  1157. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE(
  1158. FLAC__StreamDecoder *decoder,
  1159. FILE *file,
  1160. FLAC__StreamDecoderWriteCallback write_callback,
  1161. FLAC__StreamDecoderMetadataCallback metadata_callback,
  1162. FLAC__StreamDecoderErrorCallback error_callback,
  1163. void *client_data
  1164. );
  1165. /** Initialize the decoder instance to decode native FLAC files.
  1166. *
  1167. * This flavor of initialization sets up the decoder to decode from a plain
  1168. * native FLAC file. If POSIX fopen() semantics are not sufficient, you must
  1169. * use FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
  1170. * and provide callbacks for the I/O.
  1171. *
  1172. * On Windows, filename must be a UTF-8 encoded filename, which libFLAC
  1173. * internally translates to an appropriate representation to use with
  1174. * _wfopen. On all other systems, filename is passed to fopen without
  1175. * any translation.
  1176. *
  1177. * This function should be called after FLAC__stream_decoder_new() and
  1178. * FLAC__stream_decoder_set_*() but before any of the
  1179. * FLAC__stream_decoder_process_*() functions. Will set and return the
  1180. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  1181. * if initialization succeeded.
  1182. *
  1183. * \param decoder An uninitialized decoder instance.
  1184. * \param filename The name of the file to decode from. The file will
  1185. * be opened with fopen(). Use \c NULL to decode from
  1186. * \c stdin. Note that \c stdin is not seekable.
  1187. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  1188. * pointer must not be \c NULL.
  1189. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  1190. * pointer may be \c NULL if the callback is not
  1191. * desired.
  1192. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  1193. * pointer must not be \c NULL.
  1194. * \param client_data This value will be supplied to callbacks in their
  1195. * \a client_data argument.
  1196. * \assert
  1197. * \code decoder != NULL \endcode
  1198. * \retval FLAC__StreamDecoderInitStatus
  1199. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  1200. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  1201. */
  1202. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
  1203. FLAC__StreamDecoder *decoder,
  1204. const char *filename,
  1205. FLAC__StreamDecoderWriteCallback write_callback,
  1206. FLAC__StreamDecoderMetadataCallback metadata_callback,
  1207. FLAC__StreamDecoderErrorCallback error_callback,
  1208. void *client_data
  1209. );
  1210. /** Initialize the decoder instance to decode Ogg FLAC files.
  1211. *
  1212. * This flavor of initialization sets up the decoder to decode from a plain
  1213. * Ogg FLAC file. If POSIX fopen() semantics are not sufficient, you must use
  1214. * FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream()
  1215. * and provide callbacks for the I/O.
  1216. *
  1217. * On Windows, filename must be a UTF-8 encoded filename, which libFLAC
  1218. * internally translates to an appropriate representation to use with
  1219. * _wfopen. On all other systems, filename is passed to fopen without
  1220. * any translation.
  1221. *
  1222. * This function should be called after FLAC__stream_decoder_new() and
  1223. * FLAC__stream_decoder_set_*() but before any of the
  1224. * FLAC__stream_decoder_process_*() functions. Will set and return the
  1225. * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  1226. * if initialization succeeded.
  1227. *
  1228. * \note Support for Ogg FLAC in the library is optional. If this
  1229. * library has been built without support for Ogg FLAC, this function
  1230. * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
  1231. *
  1232. * \param decoder An uninitialized decoder instance.
  1233. * \param filename The name of the file to decode from. The file will
  1234. * be opened with fopen(). Use \c NULL to decode from
  1235. * \c stdin. Note that \c stdin is not seekable.
  1236. * \param write_callback See FLAC__StreamDecoderWriteCallback. This
  1237. * pointer must not be \c NULL.
  1238. * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
  1239. * pointer may be \c NULL if the callback is not
  1240. * desired.
  1241. * \param error_callback See FLAC__StreamDecoderErrorCallback. This
  1242. * pointer must not be \c NULL.
  1243. * \param client_data This value will be supplied to callbacks in their
  1244. * \a client_data argument.
  1245. * \assert
  1246. * \code decoder != NULL \endcode
  1247. * \retval FLAC__StreamDecoderInitStatus
  1248. * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
  1249. * see FLAC__StreamDecoderInitStatus for the meanings of other return values.
  1250. */
  1251. FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file(
  1252. FLAC__StreamDecoder *decoder,
  1253. const char *filename,
  1254. FLAC__StreamDecoderWriteCallback write_callback,
  1255. FLAC__StreamDecoderMetadataCallback metadata_callback,
  1256. FLAC__StreamDecoderErrorCallback error_callback,
  1257. void *client_data
  1258. );
  1259. /** Finish the decoding process.
  1260. * Flushes the decoding buffer, releases resources, resets the decoder
  1261. * settings to their defaults, and returns the decoder state to
  1262. * FLAC__STREAM_DECODER_UNINITIALIZED.
  1263. *
  1264. * In the event of a prematurely-terminated decode, it is not strictly
  1265. * necessary to call this immediately before FLAC__stream_decoder_delete()
  1266. * but it is good practice to match every FLAC__stream_decoder_init_*()
  1267. * with a FLAC__stream_decoder_finish().
  1268. *
  1269. * \param decoder An uninitialized decoder instance.
  1270. * \assert
  1271. * \code decoder != NULL \endcode
  1272. * \retval FLAC__bool
  1273. * \c false if MD5 checking is on AND a STREAMINFO block was available
  1274. * AND the MD5 signature in the STREAMINFO block was non-zero AND the
  1275. * signature does not match the one computed by the decoder; else
  1276. * \c true.
  1277. */
  1278. FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
  1279. /** Flush the stream input.
  1280. * The decoder's input buffer will be cleared and the state set to
  1281. * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn
  1282. * off MD5 checking.
  1283. *
  1284. * \param decoder A decoder instance.
  1285. * \assert
  1286. * \code decoder != NULL \endcode
  1287. * \retval FLAC__bool
  1288. * \c true if successful, else \c false if a memory allocation
  1289. * error occurs (in which case the state will be set to
  1290. * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
  1291. */
  1292. FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
  1293. /** Reset the decoding process.
  1294. * The decoder's input buffer will be cleared and the state set to
  1295. * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to
  1296. * FLAC__stream_decoder_finish() except that the settings are
  1297. * preserved; there is no need to call FLAC__stream_decoder_init_*()
  1298. * before decoding again. MD5 checking will be restored to its original
  1299. * setting.
  1300. *
  1301. * If the decoder is seekable, or was initialized with
  1302. * FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(),
  1303. * the decoder will also attempt to seek to the beginning of the file.
  1304. * If this rewind fails, this function will return \c false. It follows
  1305. * that FLAC__stream_decoder_reset() cannot be used when decoding from
  1306. * \c stdin.
  1307. *
  1308. * If the decoder was initialized with FLAC__stream_encoder_init*_stream()
  1309. * and is not seekable (i.e. no seek callback was provided or the seek
  1310. * callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
  1311. * is the duty of the client to start feeding data from the beginning of
  1312. * the stream on the next FLAC__stream_decoder_process_*() call.
  1313. *
  1314. * \param decoder A decoder instance.
  1315. * \assert
  1316. * \code decoder != NULL \endcode
  1317. * \retval FLAC__bool
  1318. * \c true if successful, else \c false if a memory allocation occurs
  1319. * (in which case the state will be set to
  1320. * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
  1321. * occurs (the state will be unchanged).
  1322. */
  1323. FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
  1324. /** Decode one metadata block or audio frame.
  1325. * This version instructs the decoder to decode a either a single metadata
  1326. * block or a single frame and stop, unless the callbacks return a fatal
  1327. * error or the read callback returns
  1328. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
  1329. *
  1330. * As the decoder needs more input it will call the read callback.
  1331. * Depending on what was decoded, the metadata or write callback will be
  1332. * called with the decoded metadata block or audio frame.
  1333. *
  1334. * Unless there is a fatal read error or end of stream, this function
  1335. * will return once one whole frame is decoded. In other words, if the
  1336. * stream is not synchronized or points to a corrupt frame header, the
  1337. * decoder will continue to try and resync until it gets to a valid
  1338. * frame, then decode one frame, then return. If the decoder points to
  1339. * a frame whose frame CRC in the frame footer does not match the
  1340. * computed frame CRC, this function will issue a
  1341. * FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
  1342. * error callback, and return, having decoded one complete, although
  1343. * corrupt, frame. (Such corrupted frames are sent as silence of the
  1344. * correct length to the write callback.)
  1345. *
  1346. * \param decoder An initialized decoder instance.
  1347. * \assert
  1348. * \code decoder != NULL \endcode
  1349. * \retval FLAC__bool
  1350. * \c false if any fatal read, write, or memory allocation error
  1351. * occurred (meaning decoding must stop), else \c true; for more
  1352. * information about the decoder, check the decoder state with
  1353. * FLAC__stream_decoder_get_state().
  1354. */
  1355. FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
  1356. /** Decode until the end of the metadata.
  1357. * This version instructs the decoder to decode from the current position
  1358. * and continue until all the metadata has been read, or until the
  1359. * callbacks return a fatal error or the read callback returns
  1360. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
  1361. *
  1362. * As the decoder needs more input it will call the read callback.
  1363. * As each metadata block is decoded, the metadata callback will be called
  1364. * with the decoded metadata.
  1365. *
  1366. * \param decoder An initialized decoder instance.
  1367. * \assert
  1368. * \code decoder != NULL \endcode
  1369. * \retval FLAC__bool
  1370. * \c false if any fatal read, write, or memory allocation error
  1371. * occurred (meaning decoding must stop), else \c true; for more
  1372. * information about the decoder, check the decoder state with
  1373. * FLAC__stream_decoder_get_state().
  1374. */
  1375. FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
  1376. /** Decode until the end of the stream.
  1377. * This version instructs the decoder to decode from the current position
  1378. * and continue until the end of stream (the read callback returns
  1379. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
  1380. * callbacks return a fatal error.
  1381. *
  1382. * As the decoder needs more input it will call the read callback.
  1383. * As each metadata block and frame is decoded, the metadata or write
  1384. * callback will be called with the decoded metadata or frame.
  1385. *
  1386. * \param decoder An initialized decoder instance.
  1387. * \assert
  1388. * \code decoder != NULL \endcode
  1389. * \retval FLAC__bool
  1390. * \c false if any fatal read, write, or memory allocation error
  1391. * occurred (meaning decoding must stop), else \c true; for more
  1392. * information about the decoder, check the decoder state with
  1393. * FLAC__stream_decoder_get_state().
  1394. */
  1395. FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
  1396. /** Skip one audio frame.
  1397. * This version instructs the decoder to 'skip' a single frame and stop,
  1398. * unless the callbacks return a fatal error or the read callback returns
  1399. * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
  1400. *
  1401. * The decoding flow is the same as what occurs when
  1402. * FLAC__stream_decoder_process_single() is called to process an audio
  1403. * frame, except that this function does not decode the parsed data into
  1404. * PCM or call the write callback. The integrity of the frame is still
  1405. * checked the same way as in the other process functions.
  1406. *
  1407. * This function will return once one whole frame is skipped, in the
  1408. * same way that FLAC__stream_decoder_process_single() will return once
  1409. * one whole frame is decoded.
  1410. *
  1411. * This function can be used in more quickly determining FLAC frame
  1412. * boundaries when decoding of the actual data is not needed, for
  1413. * example when an application is separating a FLAC stream into frames
  1414. * for editing or storing in a container. To do this, the application
  1415. * can use FLAC__stream_decoder_skip_single_frame() to quickly advance
  1416. * to the next frame, then use
  1417. * FLAC__stream_decoder_get_decode_position() to find the new frame
  1418. * boundary.
  1419. *
  1420. * This function should only be called when the stream has advanced
  1421. * past all the metadata, otherwise it will return \c false.
  1422. *
  1423. * \param decoder An initialized decoder instance not in a metadata
  1424. * state.
  1425. * \assert
  1426. * \code decoder != NULL \endcode
  1427. * \retval FLAC__bool
  1428. * \c false if any fatal read, write, or memory allocation error
  1429. * occurred (meaning decoding must stop), or if the decoder
  1430. * is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
  1431. * FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
  1432. * information about the decoder, check the decoder state with
  1433. * FLAC__stream_decoder_get_state().
  1434. */
  1435. FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
  1436. /** Flush the input and seek to an absolute sample.
  1437. * Decoding will resume at the given sample. Note that because of
  1438. * this, the next write callback may contain a partial block. The
  1439. * client must support seeking the input or this function will fail
  1440. * and return \c false. Furthermore, if the decoder state is
  1441. * \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
  1442. * with FLAC__stream_decoder_flush() or reset with
  1443. * FLAC__stream_decoder_reset() before decoding can continue.
  1444. *
  1445. * \param decoder A decoder instance.
  1446. * \param sample The target sample number to seek to.
  1447. * \assert
  1448. * \code decoder != NULL \endcode
  1449. * \retval FLAC__bool
  1450. * \c true if successful, else \c false.
  1451. */
  1452. FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
  1453. /* \} */
  1454. #ifdef __cplusplus
  1455. }
  1456. #endif
  1457. #endif