stream_encoder.h 83 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837
  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_ENCODER_H
  33. #define FLAC__STREAM_ENCODER_H
  34. #include <stdio.h> /* for FILE */
  35. #include "export.h"
  36. #include "format.h"
  37. #include "stream_decoder.h"
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41. /** \file include/FLAC/stream_encoder.h
  42. *
  43. * \brief
  44. * This module contains the functions which implement the stream
  45. * encoder.
  46. *
  47. * See the detailed documentation in the
  48. * \link flac_stream_encoder stream encoder \endlink module.
  49. */
  50. /** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
  51. * \ingroup flac
  52. *
  53. * \brief
  54. * This module describes the encoder layers provided by libFLAC.
  55. *
  56. * The stream encoder can be used to encode complete streams either to the
  57. * client via callbacks, or directly to a file, depending on how it is
  58. * initialized. When encoding via callbacks, the client provides a write
  59. * callback which will be called whenever FLAC data is ready to be written.
  60. * If the client also supplies a seek callback, the encoder will also
  61. * automatically handle the writing back of metadata discovered while
  62. * encoding, like stream info, seek points offsets, etc. When encoding to
  63. * a file, the client needs only supply a filename or open \c FILE* and an
  64. * optional progress callback for periodic notification of progress; the
  65. * write and seek callbacks are supplied internally. For more info see the
  66. * \link flac_stream_encoder stream encoder \endlink module.
  67. */
  68. /** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
  69. * \ingroup flac_encoder
  70. *
  71. * \brief
  72. * This module contains the functions which implement the stream
  73. * encoder.
  74. *
  75. * The stream encoder can encode to native FLAC, and optionally Ogg FLAC
  76. * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.
  77. *
  78. * The basic usage of this encoder is as follows:
  79. * - The program creates an instance of an encoder using
  80. * FLAC__stream_encoder_new().
  81. * - The program overrides the default settings using
  82. * FLAC__stream_encoder_set_*() functions. At a minimum, the following
  83. * functions should be called:
  84. * - FLAC__stream_encoder_set_channels()
  85. * - FLAC__stream_encoder_set_bits_per_sample()
  86. * - FLAC__stream_encoder_set_sample_rate()
  87. * - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC)
  88. * - FLAC__stream_encoder_set_total_samples_estimate() (if known)
  89. * - If the application wants to control the compression level or set its own
  90. * metadata, then the following should also be called:
  91. * - FLAC__stream_encoder_set_compression_level()
  92. * - FLAC__stream_encoder_set_verify()
  93. * - FLAC__stream_encoder_set_metadata()
  94. * - The rest of the set functions should only be called if the client needs
  95. * exact control over how the audio is compressed; thorough understanding
  96. * of the FLAC format is necessary to achieve good results.
  97. * - The program initializes the instance to validate the settings and
  98. * prepare for encoding using
  99. * - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE()
  100. * or FLAC__stream_encoder_init_file() for native FLAC
  101. * - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE()
  102. * or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC
  103. * - The program calls FLAC__stream_encoder_process() or
  104. * FLAC__stream_encoder_process_interleaved() to encode data, which
  105. * subsequently calls the callbacks when there is encoder data ready
  106. * to be written.
  107. * - The program finishes the encoding with FLAC__stream_encoder_finish(),
  108. * which causes the encoder to encode any data still in its input pipe,
  109. * update the metadata with the final encoding statistics if output
  110. * seeking is possible, and finally reset the encoder to the
  111. * uninitialized state.
  112. * - The instance may be used again or deleted with
  113. * FLAC__stream_encoder_delete().
  114. *
  115. * In more detail, the stream encoder functions similarly to the
  116. * \link flac_stream_decoder stream decoder \endlink, but has fewer
  117. * callbacks and more options. Typically the client will create a new
  118. * instance by calling FLAC__stream_encoder_new(), then set the necessary
  119. * parameters with FLAC__stream_encoder_set_*(), and initialize it by
  120. * calling one of the FLAC__stream_encoder_init_*() functions.
  121. *
  122. * Unlike the decoders, the stream encoder has many options that can
  123. * affect the speed and compression ratio. When setting these parameters
  124. * you should have some basic knowledge of the format (see the
  125. * <A HREF="https://xiph.org/flac/documentation_format_overview.html">user-level documentation</A>
  126. * or the <A HREF="https://xiph.org/flac/format.html">formal description</A>). The
  127. * FLAC__stream_encoder_set_*() functions themselves do not validate the
  128. * values as many are interdependent. The FLAC__stream_encoder_init_*()
  129. * functions will do this, so make sure to pay attention to the state
  130. * returned by FLAC__stream_encoder_init_*() to make sure that it is
  131. * FLAC__STREAM_ENCODER_INIT_STATUS_OK. Any parameters that are not set
  132. * before FLAC__stream_encoder_init_*() will take on the defaults from
  133. * the constructor.
  134. *
  135. * There are three initialization functions for native FLAC, one for
  136. * setting up the encoder to encode FLAC data to the client via
  137. * callbacks, and two for encoding directly to a file.
  138. *
  139. * For encoding via callbacks, use FLAC__stream_encoder_init_stream().
  140. * You must also supply a write callback which will be called anytime
  141. * there is raw encoded data to write. If the client can seek the output
  142. * it is best to also supply seek and tell callbacks, as this allows the
  143. * encoder to go back after encoding is finished to write back
  144. * information that was collected while encoding, like seek point offsets,
  145. * frame sizes, etc.
  146. *
  147. * For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
  148. * or FLAC__stream_encoder_init_file(). Then you must only supply a
  149. * filename or open \c FILE*; the encoder will handle all the callbacks
  150. * internally. You may also supply a progress callback for periodic
  151. * notification of the encoding progress.
  152. *
  153. * There are three similarly-named init functions for encoding to Ogg
  154. * FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the
  155. * library has been built with Ogg support.
  156. *
  157. * The call to FLAC__stream_encoder_init_*() currently will also immediately
  158. * call the write callback several times, once with the \c fLaC signature,
  159. * and once for each encoded metadata block. Note that for Ogg FLAC
  160. * encoding you will usually get at least twice the number of callbacks than
  161. * with native FLAC, one for the Ogg page header and one for the page body.
  162. *
  163. * After initializing the instance, the client may feed audio data to the
  164. * encoder in one of two ways:
  165. *
  166. * - Channel separate, through FLAC__stream_encoder_process() - The client
  167. * will pass an array of pointers to buffers, one for each channel, to
  168. * the encoder, each of the same length. The samples need not be
  169. * block-aligned, but each channel should have the same number of samples.
  170. * - Channel interleaved, through
  171. * FLAC__stream_encoder_process_interleaved() - The client will pass a single
  172. * pointer to data that is channel-interleaved (i.e. channel0_sample0,
  173. * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  174. * Again, the samples need not be block-aligned but they must be
  175. * sample-aligned, i.e. the first value should be channel0_sample0 and
  176. * the last value channelN_sampleM.
  177. *
  178. * Note that for either process call, each sample in the buffers should be a
  179. * signed integer, right-justified to the resolution set by
  180. * FLAC__stream_encoder_set_bits_per_sample(). For example, if the resolution
  181. * is 16 bits per sample, the samples should all be in the range [-32768,32767].
  182. *
  183. * When the client is finished encoding data, it calls
  184. * FLAC__stream_encoder_finish(), which causes the encoder to encode any
  185. * data still in its input pipe, and call the metadata callback with the
  186. * final encoding statistics. Then the instance may be deleted with
  187. * FLAC__stream_encoder_delete() or initialized again to encode another
  188. * stream.
  189. *
  190. * For programs that write their own metadata, but that do not know the
  191. * actual metadata until after encoding, it is advantageous to instruct
  192. * the encoder to write a PADDING block of the correct size, so that
  193. * instead of rewriting the whole stream after encoding, the program can
  194. * just overwrite the PADDING block. If only the maximum size of the
  195. * metadata is known, the program can write a slightly larger padding
  196. * block, then split it after encoding.
  197. *
  198. * Make sure you understand how lengths are calculated. All FLAC metadata
  199. * blocks have a 4 byte header which contains the type and length. This
  200. * length does not include the 4 bytes of the header. See the format page
  201. * for the specification of metadata blocks and their lengths.
  202. *
  203. * \note
  204. * If you are writing the FLAC data to a file via callbacks, make sure it
  205. * is open for update (e.g. mode "w+" for stdio streams). This is because
  206. * after the first encoding pass, the encoder will try to seek back to the
  207. * beginning of the stream, to the STREAMINFO block, to write some data
  208. * there. (If using FLAC__stream_encoder_init*_file() or
  209. * FLAC__stream_encoder_init*_FILE(), the file is managed internally.)
  210. *
  211. * \note
  212. * The "set" functions may only be called when the encoder is in the
  213. * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
  214. * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
  215. * before FLAC__stream_encoder_init_*(). If this is the case they will
  216. * return \c true, otherwise \c false.
  217. *
  218. * \note
  219. * FLAC__stream_encoder_finish() resets all settings to the constructor
  220. * defaults.
  221. *
  222. * \{
  223. */
  224. /** State values for a FLAC__StreamEncoder.
  225. *
  226. * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
  227. *
  228. * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
  229. * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
  230. * must be deleted with FLAC__stream_encoder_delete().
  231. */
  232. typedef enum {
  233. FLAC__STREAM_ENCODER_OK = 0,
  234. /**< The encoder is in the normal OK state and samples can be processed. */
  235. FLAC__STREAM_ENCODER_UNINITIALIZED,
  236. /**< The encoder is in the uninitialized state; one of the
  237. * FLAC__stream_encoder_init_*() functions must be called before samples
  238. * can be processed.
  239. */
  240. FLAC__STREAM_ENCODER_OGG_ERROR,
  241. /**< An error occurred in the underlying Ogg layer. */
  242. FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
  243. /**< An error occurred in the underlying verify stream decoder;
  244. * check FLAC__stream_encoder_get_verify_decoder_state().
  245. */
  246. FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA,
  247. /**< The verify decoder detected a mismatch between the original
  248. * audio signal and the decoded audio signal.
  249. */
  250. FLAC__STREAM_ENCODER_CLIENT_ERROR,
  251. /**< One of the callbacks returned a fatal error. */
  252. FLAC__STREAM_ENCODER_IO_ERROR,
  253. /**< An I/O error occurred while opening/reading/writing a file.
  254. * Check \c errno.
  255. */
  256. FLAC__STREAM_ENCODER_FRAMING_ERROR,
  257. /**< An error occurred while writing the stream; usually, the
  258. * write_callback returned an error.
  259. */
  260. FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
  261. /**< Memory allocation failed. */
  262. } FLAC__StreamEncoderState;
  263. /** Maps a FLAC__StreamEncoderState to a C string.
  264. *
  265. * Using a FLAC__StreamEncoderState as the index to this array
  266. * will give the string equivalent. The contents should not be modified.
  267. */
  268. extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
  269. /** Possible return values for the FLAC__stream_encoder_init_*() functions.
  270. */
  271. typedef enum {
  272. FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
  273. /**< Initialization was successful. */
  274. FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
  275. /**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
  276. FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
  277. /**< The library was not compiled with support for the given container
  278. * format.
  279. */
  280. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
  281. /**< A required callback was not supplied. */
  282. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
  283. /**< The encoder has an invalid setting for number of channels. */
  284. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
  285. /**< The encoder has an invalid setting for bits-per-sample.
  286. * FLAC supports 4-32 bps.
  287. */
  288. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
  289. /**< The encoder has an invalid setting for the input sample rate. */
  290. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
  291. /**< The encoder has an invalid setting for the block size. */
  292. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
  293. /**< The encoder has an invalid setting for the maximum LPC order. */
  294. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
  295. /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
  296. FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
  297. /**< The specified block size is less than the maximum LPC order. */
  298. FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
  299. /**< The encoder is bound to the <A HREF="https://xiph.org/flac/format.html#subset">Subset</A> but other settings violate it. */
  300. FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
  301. /**< The metadata input to the encoder is invalid, in one of the following ways:
  302. * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
  303. * - One of the metadata blocks contains an undefined type
  304. * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
  305. * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
  306. * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
  307. */
  308. FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
  309. /**< FLAC__stream_encoder_init_*() was called when the encoder was
  310. * already initialized, usually because
  311. * FLAC__stream_encoder_finish() was not called.
  312. */
  313. } FLAC__StreamEncoderInitStatus;
  314. /** Maps a FLAC__StreamEncoderInitStatus to a C string.
  315. *
  316. * Using a FLAC__StreamEncoderInitStatus as the index to this array
  317. * will give the string equivalent. The contents should not be modified.
  318. */
  319. extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
  320. /** Return values for the FLAC__StreamEncoder read callback.
  321. */
  322. typedef enum {
  323. FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
  324. /**< The read was OK and decoding can continue. */
  325. FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
  326. /**< The read was attempted at the end of the stream. */
  327. FLAC__STREAM_ENCODER_READ_STATUS_ABORT,
  328. /**< An unrecoverable error occurred. */
  329. FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
  330. /**< Client does not support reading back from the output. */
  331. } FLAC__StreamEncoderReadStatus;
  332. /** Maps a FLAC__StreamEncoderReadStatus to a C string.
  333. *
  334. * Using a FLAC__StreamEncoderReadStatus as the index to this array
  335. * will give the string equivalent. The contents should not be modified.
  336. */
  337. extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[];
  338. /** Return values for the FLAC__StreamEncoder write callback.
  339. */
  340. typedef enum {
  341. FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0,
  342. /**< The write was OK and encoding can continue. */
  343. FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR
  344. /**< An unrecoverable error occurred. The encoder will return from the process call. */
  345. } FLAC__StreamEncoderWriteStatus;
  346. /** Maps a FLAC__StreamEncoderWriteStatus to a C string.
  347. *
  348. * Using a FLAC__StreamEncoderWriteStatus as the index to this array
  349. * will give the string equivalent. The contents should not be modified.
  350. */
  351. extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
  352. /** Return values for the FLAC__StreamEncoder seek callback.
  353. */
  354. typedef enum {
  355. FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
  356. /**< The seek was OK and encoding can continue. */
  357. FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
  358. /**< An unrecoverable error occurred. */
  359. FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  360. /**< Client does not support seeking. */
  361. } FLAC__StreamEncoderSeekStatus;
  362. /** Maps a FLAC__StreamEncoderSeekStatus to a C string.
  363. *
  364. * Using a FLAC__StreamEncoderSeekStatus as the index to this array
  365. * will give the string equivalent. The contents should not be modified.
  366. */
  367. extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
  368. /** Return values for the FLAC__StreamEncoder tell callback.
  369. */
  370. typedef enum {
  371. FLAC__STREAM_ENCODER_TELL_STATUS_OK,
  372. /**< The tell was OK and encoding can continue. */
  373. FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
  374. /**< An unrecoverable error occurred. */
  375. FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  376. /**< Client does not support seeking. */
  377. } FLAC__StreamEncoderTellStatus;
  378. /** Maps a FLAC__StreamEncoderTellStatus to a C string.
  379. *
  380. * Using a FLAC__StreamEncoderTellStatus as the index to this array
  381. * will give the string equivalent. The contents should not be modified.
  382. */
  383. extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
  384. /***********************************************************************
  385. *
  386. * class FLAC__StreamEncoder
  387. *
  388. ***********************************************************************/
  389. struct FLAC__StreamEncoderProtected;
  390. struct FLAC__StreamEncoderPrivate;
  391. /** The opaque structure definition for the stream encoder type.
  392. * See the \link flac_stream_encoder stream encoder module \endlink
  393. * for a detailed description.
  394. */
  395. typedef struct {
  396. struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  397. struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
  398. } FLAC__StreamEncoder;
  399. /** Signature for the read callback.
  400. *
  401. * A function pointer matching this signature must be passed to
  402. * FLAC__stream_encoder_init_ogg_stream() if seeking is supported.
  403. * The supplied function will be called when the encoder needs to read back
  404. * encoded data. This happens during the metadata callback, when the encoder
  405. * has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
  406. * while encoding. The address of the buffer to be filled is supplied, along
  407. * with the number of bytes the buffer can hold. The callback may choose to
  408. * supply less data and modify the byte count but must be careful not to
  409. * overflow the buffer. The callback then returns a status code chosen from
  410. * FLAC__StreamEncoderReadStatus.
  411. *
  412. * Here is an example of a read callback for stdio streams:
  413. * \code
  414. * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
  415. * {
  416. * FILE *file = ((MyClientData*)client_data)->file;
  417. * if(*bytes > 0) {
  418. * *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
  419. * if(ferror(file))
  420. * return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  421. * else if(*bytes == 0)
  422. * return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM;
  423. * else
  424. * return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE;
  425. * }
  426. * else
  427. * return FLAC__STREAM_ENCODER_READ_STATUS_ABORT;
  428. * }
  429. * \endcode
  430. *
  431. * \note In general, FLAC__StreamEncoder functions which change the
  432. * state should not be called on the \a encoder while in the callback.
  433. *
  434. * \param encoder The encoder instance calling the callback.
  435. * \param buffer A pointer to a location for the callee to store
  436. * data to be encoded.
  437. * \param bytes A pointer to the size of the buffer. On entry
  438. * to the callback, it contains the maximum number
  439. * of bytes that may be stored in \a buffer. The
  440. * callee must set it to the actual number of bytes
  441. * stored (0 in case of error or end-of-stream) before
  442. * returning.
  443. * \param client_data The callee's client data set through
  444. * FLAC__stream_encoder_set_client_data().
  445. * \retval FLAC__StreamEncoderReadStatus
  446. * The callee's return status.
  447. */
  448. typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data);
  449. /** Signature for the write callback.
  450. *
  451. * A function pointer matching this signature must be passed to
  452. * FLAC__stream_encoder_init*_stream(). The supplied function will be called
  453. * by the encoder anytime there is raw encoded data ready to write. It may
  454. * include metadata mixed with encoded audio frames and the data is not
  455. * guaranteed to be aligned on frame or metadata block boundaries.
  456. *
  457. * The only duty of the callback is to write out the \a bytes worth of data
  458. * in \a buffer to the current position in the output stream. The arguments
  459. * \a samples and \a current_frame are purely informational. If \a samples
  460. * is greater than \c 0, then \a current_frame will hold the current frame
  461. * number that is being written; otherwise it indicates that the write
  462. * callback is being called to write metadata.
  463. *
  464. * \note
  465. * Unlike when writing to native FLAC, when writing to Ogg FLAC the
  466. * write callback will be called twice when writing each audio
  467. * frame; once for the page header, and once for the page body.
  468. * When writing the page header, the \a samples argument to the
  469. * write callback will be \c 0.
  470. *
  471. * \note In general, FLAC__StreamEncoder functions which change the
  472. * state should not be called on the \a encoder while in the callback.
  473. *
  474. * \param encoder The encoder instance calling the callback.
  475. * \param buffer An array of encoded data of length \a bytes.
  476. * \param bytes The byte length of \a buffer.
  477. * \param samples The number of samples encoded by \a buffer.
  478. * \c 0 has a special meaning; see above.
  479. * \param current_frame The number of the current frame being encoded.
  480. * \param client_data The callee's client data set through
  481. * FLAC__stream_encoder_init_*().
  482. * \retval FLAC__StreamEncoderWriteStatus
  483. * The callee's return status.
  484. */
  485. typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, uint32_t samples, uint32_t current_frame, void *client_data);
  486. /** Signature for the seek callback.
  487. *
  488. * A function pointer matching this signature may be passed to
  489. * FLAC__stream_encoder_init*_stream(). The supplied function will be called
  490. * when the encoder needs to seek the output stream. The encoder will pass
  491. * the absolute byte offset to seek to, 0 meaning the beginning of the stream.
  492. *
  493. * Here is an example of a seek callback for stdio streams:
  494. * \code
  495. * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data)
  496. * {
  497. * FILE *file = ((MyClientData*)client_data)->file;
  498. * if(file == stdin)
  499. * return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED;
  500. * else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
  501. * return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR;
  502. * else
  503. * return FLAC__STREAM_ENCODER_SEEK_STATUS_OK;
  504. * }
  505. * \endcode
  506. *
  507. * \note In general, FLAC__StreamEncoder functions which change the
  508. * state should not be called on the \a encoder while in the callback.
  509. *
  510. * \param encoder The encoder instance calling the callback.
  511. * \param absolute_byte_offset The offset from the beginning of the stream
  512. * to seek to.
  513. * \param client_data The callee's client data set through
  514. * FLAC__stream_encoder_init_*().
  515. * \retval FLAC__StreamEncoderSeekStatus
  516. * The callee's return status.
  517. */
  518. typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
  519. /** Signature for the tell callback.
  520. *
  521. * A function pointer matching this signature may be passed to
  522. * FLAC__stream_encoder_init*_stream(). The supplied function will be called
  523. * when the encoder needs to know the current position of the output stream.
  524. *
  525. * \warning
  526. * The callback must return the true current byte offset of the output to
  527. * which the encoder is writing. If you are buffering the output, make
  528. * sure and take this into account. If you are writing directly to a
  529. * FILE* from your write callback, ftell() is sufficient. If you are
  530. * writing directly to a file descriptor from your write callback, you
  531. * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
  532. * these points to rewrite metadata after encoding.
  533. *
  534. * Here is an example of a tell callback for stdio streams:
  535. * \code
  536. * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
  537. * {
  538. * FILE *file = ((MyClientData*)client_data)->file;
  539. * off_t pos;
  540. * if(file == stdin)
  541. * return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED;
  542. * else if((pos = ftello(file)) < 0)
  543. * return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR;
  544. * else {
  545. * *absolute_byte_offset = (FLAC__uint64)pos;
  546. * return FLAC__STREAM_ENCODER_TELL_STATUS_OK;
  547. * }
  548. * }
  549. * \endcode
  550. *
  551. * \note In general, FLAC__StreamEncoder functions which change the
  552. * state should not be called on the \a encoder while in the callback.
  553. *
  554. * \param encoder The encoder instance calling the callback.
  555. * \param absolute_byte_offset The address at which to store the current
  556. * position of the output.
  557. * \param client_data The callee's client data set through
  558. * FLAC__stream_encoder_init_*().
  559. * \retval FLAC__StreamEncoderTellStatus
  560. * The callee's return status.
  561. */
  562. typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
  563. /** Signature for the metadata callback.
  564. *
  565. * A function pointer matching this signature may be passed to
  566. * FLAC__stream_encoder_init*_stream(). The supplied function will be called
  567. * once at the end of encoding with the populated STREAMINFO structure. This
  568. * is so the client can seek back to the beginning of the file and write the
  569. * STREAMINFO block with the correct statistics after encoding (like
  570. * minimum/maximum frame size and total samples).
  571. *
  572. * \note In general, FLAC__StreamEncoder functions which change the
  573. * state should not be called on the \a encoder while in the callback.
  574. *
  575. * \param encoder The encoder instance calling the callback.
  576. * \param metadata The final populated STREAMINFO block.
  577. * \param client_data The callee's client data set through
  578. * FLAC__stream_encoder_init_*().
  579. */
  580. typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
  581. /** Signature for the progress callback.
  582. *
  583. * A function pointer matching this signature may be passed to
  584. * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE().
  585. * The supplied function will be called when the encoder has finished
  586. * writing a frame. The \c total_frames_estimate argument to the
  587. * callback will be based on the value from
  588. * FLAC__stream_encoder_set_total_samples_estimate().
  589. *
  590. * \note In general, FLAC__StreamEncoder functions which change the
  591. * state should not be called on the \a encoder while in the callback.
  592. *
  593. * \param encoder The encoder instance calling the callback.
  594. * \param bytes_written Bytes written so far.
  595. * \param samples_written Samples written so far.
  596. * \param frames_written Frames written so far.
  597. * \param total_frames_estimate The estimate of the total number of
  598. * frames to be written.
  599. * \param client_data The callee's client data set through
  600. * FLAC__stream_encoder_init_*().
  601. */
  602. typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, uint32_t frames_written, uint32_t total_frames_estimate, void *client_data);
  603. /***********************************************************************
  604. *
  605. * Class constructor/destructor
  606. *
  607. ***********************************************************************/
  608. /** Create a new stream encoder instance. The instance is created with
  609. * default settings; see the individual FLAC__stream_encoder_set_*()
  610. * functions for each setting's default.
  611. *
  612. * \retval FLAC__StreamEncoder*
  613. * \c NULL if there was an error allocating memory, else the new instance.
  614. */
  615. FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void);
  616. /** Free an encoder instance. Deletes the object pointed to by \a encoder.
  617. *
  618. * \param encoder A pointer to an existing encoder.
  619. * \assert
  620. * \code encoder != NULL \endcode
  621. */
  622. FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder);
  623. /***********************************************************************
  624. *
  625. * Public class method prototypes
  626. *
  627. ***********************************************************************/
  628. /** Set the serial number for the FLAC stream to use in the Ogg container.
  629. *
  630. * \note
  631. * This does not need to be set for native FLAC encoding.
  632. *
  633. * \note
  634. * It is recommended to set a serial number explicitly as the default of '0'
  635. * may collide with other streams.
  636. *
  637. * \default \c 0
  638. * \param encoder An encoder instance to set.
  639. * \param serial_number See above.
  640. * \assert
  641. * \code encoder != NULL \endcode
  642. * \retval FLAC__bool
  643. * \c false if the encoder is already initialized, else \c true.
  644. */
  645. FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number);
  646. /** Set the "verify" flag. If \c true, the encoder will verify it's own
  647. * encoded output by feeding it through an internal decoder and comparing
  648. * the original signal against the decoded signal. If a mismatch occurs,
  649. * the process call will return \c false. Note that this will slow the
  650. * encoding process by the extra time required for decoding and comparison.
  651. *
  652. * \default \c false
  653. * \param encoder An encoder instance to set.
  654. * \param value Flag value (see above).
  655. * \assert
  656. * \code encoder != NULL \endcode
  657. * \retval FLAC__bool
  658. * \c false if the encoder is already initialized, else \c true.
  659. */
  660. FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value);
  661. /** Set the <A HREF="https://xiph.org/flac/format.html#subset">Subset</A> flag. If \c true,
  662. * the encoder will comply with the Subset and will check the
  663. * settings during FLAC__stream_encoder_init_*() to see if all settings
  664. * comply. If \c false, the settings may take advantage of the full
  665. * range that the format allows.
  666. *
  667. * Make sure you know what it entails before setting this to \c false.
  668. *
  669. * \default \c true
  670. * \param encoder An encoder instance to set.
  671. * \param value Flag value (see above).
  672. * \assert
  673. * \code encoder != NULL \endcode
  674. * \retval FLAC__bool
  675. * \c false if the encoder is already initialized, else \c true.
  676. */
  677. FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value);
  678. /** Set the number of channels to be encoded.
  679. *
  680. * \default \c 2
  681. * \param encoder An encoder instance to set.
  682. * \param value See above.
  683. * \assert
  684. * \code encoder != NULL \endcode
  685. * \retval FLAC__bool
  686. * \c false if the encoder is already initialized, else \c true.
  687. */
  688. FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, uint32_t value);
  689. /** Set the sample resolution of the input to be encoded.
  690. *
  691. * \warning
  692. * Do not feed the encoder data that is wider than the value you
  693. * set here or you will generate an invalid stream.
  694. *
  695. * \default \c 16
  696. * \param encoder An encoder instance to set.
  697. * \param value See above.
  698. * \assert
  699. * \code encoder != NULL \endcode
  700. * \retval FLAC__bool
  701. * \c false if the encoder is already initialized, else \c true.
  702. */
  703. FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, uint32_t value);
  704. /** Set the sample rate (in Hz) of the input to be encoded.
  705. *
  706. * \default \c 44100
  707. * \param encoder An encoder instance to set.
  708. * \param value See above.
  709. * \assert
  710. * \code encoder != NULL \endcode
  711. * \retval FLAC__bool
  712. * \c false if the encoder is already initialized, else \c true.
  713. */
  714. FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, uint32_t value);
  715. /** Set the compression level
  716. *
  717. * The compression level is roughly proportional to the amount of effort
  718. * the encoder expends to compress the file. A higher level usually
  719. * means more computation but higher compression. The default level is
  720. * suitable for most applications.
  721. *
  722. * Currently the levels range from \c 0 (fastest, least compression) to
  723. * \c 8 (slowest, most compression). A value larger than \c 8 will be
  724. * treated as \c 8.
  725. *
  726. * This function automatically calls the following other \c _set_
  727. * functions with appropriate values, so the client does not need to
  728. * unless it specifically wants to override them:
  729. * - FLAC__stream_encoder_set_do_mid_side_stereo()
  730. * - FLAC__stream_encoder_set_loose_mid_side_stereo()
  731. * - FLAC__stream_encoder_set_apodization()
  732. * - FLAC__stream_encoder_set_max_lpc_order()
  733. * - FLAC__stream_encoder_set_qlp_coeff_precision()
  734. * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
  735. * - FLAC__stream_encoder_set_do_escape_coding()
  736. * - FLAC__stream_encoder_set_do_exhaustive_model_search()
  737. * - FLAC__stream_encoder_set_min_residual_partition_order()
  738. * - FLAC__stream_encoder_set_max_residual_partition_order()
  739. * - FLAC__stream_encoder_set_rice_parameter_search_dist()
  740. *
  741. * The actual values set for each level are:
  742. * <table>
  743. * <tr>
  744. * <td><b>level</b></td>
  745. * <td>do mid-side stereo</td>
  746. * <td>loose mid-side stereo</td>
  747. * <td>apodization</td>
  748. * <td>max lpc order</td>
  749. * <td>qlp coeff precision</td>
  750. * <td>qlp coeff prec search</td>
  751. * <td>escape coding</td>
  752. * <td>exhaustive model search</td>
  753. * <td>min residual partition order</td>
  754. * <td>max residual partition order</td>
  755. * <td>rice parameter search dist</td>
  756. * </tr>
  757. * <tr> <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
  758. * <tr> <td><b>1</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
  759. * <tr> <td><b>2</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr>
  760. * <tr> <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td> <td>6</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
  761. * <tr> <td><b>4</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr>
  762. * <tr> <td><b>5</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr>
  763. * <tr> <td><b>6</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
  764. * <tr> <td><b>7</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
  765. * <tr> <td><b>8</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr>
  766. * </table>
  767. *
  768. * \default \c 5
  769. * \param encoder An encoder instance to set.
  770. * \param value See above.
  771. * \assert
  772. * \code encoder != NULL \endcode
  773. * \retval FLAC__bool
  774. * \c false if the encoder is already initialized, else \c true.
  775. */
  776. FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, uint32_t value);
  777. /** Set the blocksize to use while encoding.
  778. *
  779. * The number of samples to use per frame. Use \c 0 to let the encoder
  780. * estimate a blocksize; this is usually best.
  781. *
  782. * \default \c 0
  783. * \param encoder An encoder instance to set.
  784. * \param value See above.
  785. * \assert
  786. * \code encoder != NULL \endcode
  787. * \retval FLAC__bool
  788. * \c false if the encoder is already initialized, else \c true.
  789. */
  790. FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, uint32_t value);
  791. /** Set to \c true to enable mid-side encoding on stereo input. The
  792. * number of channels must be 2 for this to have any effect. Set to
  793. * \c false to use only independent channel coding.
  794. *
  795. * \default \c true
  796. * \param encoder An encoder instance to set.
  797. * \param value Flag value (see above).
  798. * \assert
  799. * \code encoder != NULL \endcode
  800. * \retval FLAC__bool
  801. * \c false if the encoder is already initialized, else \c true.
  802. */
  803. FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  804. /** Set to \c true to enable adaptive switching between mid-side and
  805. * left-right encoding on stereo input. Set to \c false to use
  806. * exhaustive searching. Setting this to \c true requires
  807. * FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
  808. * \c true in order to have any effect.
  809. *
  810. * \default \c false
  811. * \param encoder An encoder instance to set.
  812. * \param value Flag value (see above).
  813. * \assert
  814. * \code encoder != NULL \endcode
  815. * \retval FLAC__bool
  816. * \c false if the encoder is already initialized, else \c true.
  817. */
  818. FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value);
  819. /** Sets the apodization function(s) the encoder will use when windowing
  820. * audio data for LPC analysis.
  821. *
  822. * The \a specification is a plain ASCII string which specifies exactly
  823. * which functions to use. There may be more than one (up to 32),
  824. * separated by \c ';' characters. Some functions take one or more
  825. * comma-separated arguments in parentheses.
  826. *
  827. * The available functions are \c bartlett, \c bartlett_hann,
  828. * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop,
  829. * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall,
  830. * \c rectangle, \c triangle, \c tukey(P), \c partial_tukey(n[/ov[/P]]),
  831. * \c punchout_tukey(n[/ov[/P]]), \c subdivide_tukey(n[/P]), \c welch.
  832. *
  833. * For \c gauss(STDDEV), STDDEV specifies the standard deviation
  834. * (0<STDDEV<=0.5).
  835. *
  836. * For \c tukey(P), P specifies the fraction of the window that is
  837. * tapered (0<=P<=1). P=0 corresponds to \c rectangle and P=1
  838. * corresponds to \c hann.
  839. *
  840. * Specifying \c partial_tukey or \c punchout_tukey works a little
  841. * different. These do not specify a single apodization function, but
  842. * a series of them with some overlap. partial_tukey specifies a series
  843. * of small windows (all treated separately) while punchout_tukey
  844. * specifies a series of windows that have a hole in them. In this way,
  845. * the predictor is constructed with only a part of the block, which
  846. * helps in case a block consists of dissimilar parts.
  847. *
  848. * The three parameters that can be specified for the functions are
  849. * n, ov and P. n is the number of functions to add, ov is the overlap
  850. * of the windows in case of partial_tukey and the overlap in the gaps
  851. * in case of punchout_tukey. P is the fraction of the window that is
  852. * tapered, like with a regular tukey window. The function can be
  853. * specified with only a number, a number and an overlap, or a number
  854. * an overlap and a P, for example, partial_tukey(3), partial_tukey(3/0.3)
  855. * and partial_tukey(3/0.3/0.5) are all valid. ov should be smaller than 1
  856. * and can be negative.
  857. *
  858. * subdivide_tukey(n) is a more efficient reimplementation of
  859. * partial_tukey and punchout_tukey taken together, recycling as much data
  860. * as possible. It combines all possible non-redundant partial_tukey(n)
  861. * and punchout_tukey(n) up to the n specified. Specifying
  862. * subdivide_tukey(3) is equivalent to specifying tukey, partial_tukey(2),
  863. * partial_tukey(3) and punchout_tukey(3), specifying subdivide_tukey(5)
  864. * equivalently adds partial_tukey(4), punchout_tukey(4), partial_tukey(5)
  865. * and punchout_tukey(5). To be able to reuse data as much as possible,
  866. * the tukey taper is taken equal for all windows, and the P specified is
  867. * applied for the smallest used window. In other words,
  868. * subdivide_tukey(2/0.5) results in a taper equal to that of tukey(0.25)
  869. * and subdivide_tukey(5) in a taper equal to that of tukey(0.1). The
  870. * default P for subdivide_tukey when none is specified is 0.5.
  871. *
  872. * Example specifications are \c "blackman" or
  873. * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"
  874. *
  875. * Any function that is specified erroneously is silently dropped. Up
  876. * to 32 functions are kept, the rest are dropped. If the specification
  877. * is empty the encoder defaults to \c "tukey(0.5)".
  878. *
  879. * When more than one function is specified, then for every subframe the
  880. * encoder will try each of them separately and choose the window that
  881. * results in the smallest compressed subframe.
  882. *
  883. * Note that each function specified causes the encoder to occupy a
  884. * floating point array in which to store the window. Also note that the
  885. * values of P, STDDEV and ov are locale-specific, so if the comma
  886. * separator specified by the locale is a comma, a comma should be used.
  887. * A locale-independent way is to specify using scientific notation,
  888. * e.g. 5e-1 instad of 0.5 or 0,5.
  889. *
  890. * \default \c "tukey(0.5)"
  891. * \param encoder An encoder instance to set.
  892. * \param specification See above.
  893. * \assert
  894. * \code encoder != NULL \endcode
  895. * \code specification != NULL \endcode
  896. * \retval FLAC__bool
  897. * \c false if the encoder is already initialized, else \c true.
  898. */
  899. FLAC_API FLAC__bool FLAC__stream_encoder_set_apodization(FLAC__StreamEncoder *encoder, const char *specification);
  900. /** Set the maximum LPC order, or \c 0 to use only the fixed predictors.
  901. *
  902. * \default \c 8
  903. * \param encoder An encoder instance to set.
  904. * \param value See above.
  905. * \assert
  906. * \code encoder != NULL \endcode
  907. * \retval FLAC__bool
  908. * \c false if the encoder is already initialized, else \c true.
  909. */
  910. FLAC_API FLAC__bool FLAC__stream_encoder_set_max_lpc_order(FLAC__StreamEncoder *encoder, uint32_t value);
  911. /** Set the precision, in bits, of the quantized linear predictor
  912. * coefficients, or \c 0 to let the encoder select it based on the
  913. * blocksize.
  914. *
  915. * \default \c 0
  916. * \param encoder An encoder instance to set.
  917. * \param value See above.
  918. * \assert
  919. * \code encoder != NULL \endcode
  920. * \retval FLAC__bool
  921. * \c false if the encoder is already initialized, else \c true.
  922. */
  923. FLAC_API FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision(FLAC__StreamEncoder *encoder, uint32_t value);
  924. /** Set to \c false to use only the specified quantized linear predictor
  925. * coefficient precision, or \c true to search neighboring precision
  926. * values and use the best one.
  927. *
  928. * \default \c false
  929. * \param encoder An encoder instance to set.
  930. * \param value See above.
  931. * \assert
  932. * \code encoder != NULL \endcode
  933. * \retval FLAC__bool
  934. * \c false if the encoder is already initialized, else \c true.
  935. */
  936. FLAC_API FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
  937. /** Deprecated. Setting this value has no effect.
  938. *
  939. * \default \c false
  940. * \param encoder An encoder instance to set.
  941. * \param value See above.
  942. * \assert
  943. * \code encoder != NULL \endcode
  944. * \retval FLAC__bool
  945. * \c false if the encoder is already initialized, else \c true.
  946. */
  947. FLAC_API FLAC__bool FLAC__stream_encoder_set_do_escape_coding(FLAC__StreamEncoder *encoder, FLAC__bool value);
  948. /** Set to \c false to let the encoder estimate the best model order
  949. * based on the residual signal energy, or \c true to force the
  950. * encoder to evaluate all order models and select the best.
  951. *
  952. * \default \c false
  953. * \param encoder An encoder instance to set.
  954. * \param value See above.
  955. * \assert
  956. * \code encoder != NULL \endcode
  957. * \retval FLAC__bool
  958. * \c false if the encoder is already initialized, else \c true.
  959. */
  960. FLAC_API FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search(FLAC__StreamEncoder *encoder, FLAC__bool value);
  961. /** Set the minimum partition order to search when coding the residual.
  962. * This is used in tandem with
  963. * FLAC__stream_encoder_set_max_residual_partition_order().
  964. *
  965. * The partition order determines the context size in the residual.
  966. * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
  967. *
  968. * Set both min and max values to \c 0 to force a single context,
  969. * whose Rice parameter is based on the residual signal variance.
  970. * Otherwise, set a min and max order, and the encoder will search
  971. * all orders, using the mean of each context for its Rice parameter,
  972. * and use the best.
  973. *
  974. * \default \c 0
  975. * \param encoder An encoder instance to set.
  976. * \param value See above.
  977. * \assert
  978. * \code encoder != NULL \endcode
  979. * \retval FLAC__bool
  980. * \c false if the encoder is already initialized, else \c true.
  981. */
  982. FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, uint32_t value);
  983. /** Set the maximum partition order to search when coding the residual.
  984. * This is used in tandem with
  985. * FLAC__stream_encoder_set_min_residual_partition_order().
  986. *
  987. * The partition order determines the context size in the residual.
  988. * The context size will be approximately <tt>blocksize / (2 ^ order)</tt>.
  989. *
  990. * Set both min and max values to \c 0 to force a single context,
  991. * whose Rice parameter is based on the residual signal variance.
  992. * Otherwise, set a min and max order, and the encoder will search
  993. * all orders, using the mean of each context for its Rice parameter,
  994. * and use the best.
  995. *
  996. * \default \c 5
  997. * \param encoder An encoder instance to set.
  998. * \param value See above.
  999. * \assert
  1000. * \code encoder != NULL \endcode
  1001. * \retval FLAC__bool
  1002. * \c false if the encoder is already initialized, else \c true.
  1003. */
  1004. FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, uint32_t value);
  1005. /** Deprecated. Setting this value has no effect.
  1006. *
  1007. * \default \c 0
  1008. * \param encoder An encoder instance to set.
  1009. * \param value See above.
  1010. * \assert
  1011. * \code encoder != NULL \endcode
  1012. * \retval FLAC__bool
  1013. * \c false if the encoder is already initialized, else \c true.
  1014. */
  1015. FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, uint32_t value);
  1016. /** Set an estimate of the total samples that will be encoded.
  1017. * This is merely an estimate and may be set to \c 0 if unknown.
  1018. * This value will be written to the STREAMINFO block before encoding,
  1019. * and can remove the need for the caller to rewrite the value later
  1020. * if the value is known before encoding.
  1021. *
  1022. * \default \c 0
  1023. * \param encoder An encoder instance to set.
  1024. * \param value See above.
  1025. * \assert
  1026. * \code encoder != NULL \endcode
  1027. * \retval FLAC__bool
  1028. * \c false if the encoder is already initialized, else \c true.
  1029. */
  1030. FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value);
  1031. /** Set the metadata blocks to be emitted to the stream before encoding.
  1032. * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
  1033. * array of pointers to metadata blocks. The array is non-const since
  1034. * the encoder may need to change the \a is_last flag inside them, and
  1035. * in some cases update seek point offsets. Otherwise, the encoder will
  1036. * not modify or free the blocks. It is up to the caller to free the
  1037. * metadata blocks after encoding finishes.
  1038. *
  1039. * \note
  1040. * The encoder stores only copies of the pointers in the \a metadata array;
  1041. * the metadata blocks themselves must survive at least until after
  1042. * FLAC__stream_encoder_finish() returns. Do not free the blocks until then.
  1043. *
  1044. * \note
  1045. * The STREAMINFO block is always written and no STREAMINFO block may
  1046. * occur in the supplied array.
  1047. *
  1048. * \note
  1049. * By default the encoder does not create a SEEKTABLE. If one is supplied
  1050. * in the \a metadata array, but the client has specified that it does not
  1051. * support seeking, then the SEEKTABLE will be written verbatim. However
  1052. * by itself this is not very useful as the client will not know the stream
  1053. * offsets for the seekpoints ahead of time. In order to get a proper
  1054. * seektable the client must support seeking. See next note.
  1055. *
  1056. * \note
  1057. * SEEKTABLE blocks are handled specially. Since you will not know
  1058. * the values for the seek point stream offsets, you should pass in
  1059. * a SEEKTABLE 'template', that is, a SEEKTABLE object with the
  1060. * required sample numbers (or placeholder points), with \c 0 for the
  1061. * \a frame_samples and \a stream_offset fields for each point. If the
  1062. * client has specified that it supports seeking by providing a seek
  1063. * callback to FLAC__stream_encoder_init_stream() or both seek AND read
  1064. * callback to FLAC__stream_encoder_init_ogg_stream() (or by using
  1065. * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()),
  1066. * then while it is encoding the encoder will fill the stream offsets in
  1067. * for you and when encoding is finished, it will seek back and write the
  1068. * real values into the SEEKTABLE block in the stream. There are helper
  1069. * routines for manipulating seektable template blocks; see metadata.h:
  1070. * FLAC__metadata_object_seektable_template_*(). If the client does
  1071. * not support seeking, the SEEKTABLE will have inaccurate offsets which
  1072. * will slow down or remove the ability to seek in the FLAC stream.
  1073. *
  1074. * \note
  1075. * The encoder instance \b will modify the first \c SEEKTABLE block
  1076. * as it transforms the template to a valid seektable while encoding,
  1077. * but it is still up to the caller to free all metadata blocks after
  1078. * encoding.
  1079. *
  1080. * \note
  1081. * A VORBIS_COMMENT block may be supplied. The vendor string in it
  1082. * will be ignored. libFLAC will use it's own vendor string. libFLAC
  1083. * will not modify the passed-in VORBIS_COMMENT's vendor string, it
  1084. * will simply write it's own into the stream. If no VORBIS_COMMENT
  1085. * block is present in the \a metadata array, libFLAC will write an
  1086. * empty one, containing only the vendor string.
  1087. *
  1088. * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
  1089. * the second metadata block of the stream. The encoder already supplies
  1090. * the STREAMINFO block automatically. If \a metadata does not contain a
  1091. * VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
  1092. * \a metadata does contain a VORBIS_COMMENT block and it is not the
  1093. * first, the init function will reorder \a metadata by moving the
  1094. * VORBIS_COMMENT block to the front; the relative ordering of the other
  1095. * blocks will remain as they were.
  1096. *
  1097. * \note The Ogg FLAC mapping limits the number of metadata blocks per
  1098. * stream to \c 65535. If \a num_blocks exceeds this the function will
  1099. * return \c false.
  1100. *
  1101. * \default \c NULL, 0
  1102. * \param encoder An encoder instance to set.
  1103. * \param metadata See above.
  1104. * \param num_blocks See above.
  1105. * \assert
  1106. * \code encoder != NULL \endcode
  1107. * \retval FLAC__bool
  1108. * \c false if the encoder is already initialized, else \c true.
  1109. * \c false if the encoder is already initialized, or if
  1110. * \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true.
  1111. */
  1112. FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, uint32_t num_blocks);
  1113. /** Set to \c true to make the encoder not output frames which contain
  1114. * only constant subframes. This is beneficial for streaming
  1115. * applications: very small frames can cause problems with buffering
  1116. * as bitrates can drop as low 1kbit/s for CDDA audio encoded within
  1117. * subset. The minimum bitrate for a FLAC file encoded with this
  1118. * function used is raised to 1bit/sample (i.e. 48kbit/s for 48kHz
  1119. * material).
  1120. *
  1121. * \default \c false
  1122. * \param encoder An encoder instance to set.
  1123. * \param value Flag value (see above).
  1124. * \assert
  1125. * \code encoder != NULL \endcode
  1126. * \retval FLAC__bool
  1127. * \c false if the encoder is already initialized, else \c true.
  1128. */
  1129. FLAC_API FLAC__bool FLAC__stream_encoder_set_limit_min_bitrate(FLAC__StreamEncoder *encoder, FLAC__bool value);
  1130. /** Get the current encoder state.
  1131. *
  1132. * \param encoder An encoder instance to query.
  1133. * \assert
  1134. * \code encoder != NULL \endcode
  1135. * \retval FLAC__StreamEncoderState
  1136. * The current encoder state.
  1137. */
  1138. FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder);
  1139. /** Get the state of the verify stream decoder.
  1140. * Useful when the stream encoder state is
  1141. * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
  1142. *
  1143. * \param encoder An encoder instance to query.
  1144. * \assert
  1145. * \code encoder != NULL \endcode
  1146. * \retval FLAC__StreamDecoderState
  1147. * The verify stream decoder state.
  1148. */
  1149. FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder);
  1150. /** Get the current encoder state as a C string.
  1151. * This version automatically resolves
  1152. * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
  1153. * verify decoder's state.
  1154. *
  1155. * \param encoder A encoder instance to query.
  1156. * \assert
  1157. * \code encoder != NULL \endcode
  1158. * \retval const char *
  1159. * The encoder state as a C string. Do not modify the contents.
  1160. */
  1161. FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder);
  1162. /** Get relevant values about the nature of a verify decoder error.
  1163. * Useful when the stream encoder state is
  1164. * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should
  1165. * be addresses in which the stats will be returned, or NULL if value
  1166. * is not desired.
  1167. *
  1168. * \param encoder An encoder instance to query.
  1169. * \param absolute_sample The absolute sample number of the mismatch.
  1170. * \param frame_number The number of the frame in which the mismatch occurred.
  1171. * \param channel The channel in which the mismatch occurred.
  1172. * \param sample The number of the sample (relative to the frame) in
  1173. * which the mismatch occurred.
  1174. * \param expected The expected value for the sample in question.
  1175. * \param got The actual value returned by the decoder.
  1176. * \assert
  1177. * \code encoder != NULL \endcode
  1178. */
  1179. FLAC_API void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, uint32_t *frame_number, uint32_t *channel, uint32_t *sample, FLAC__int32 *expected, FLAC__int32 *got);
  1180. /** Get the "verify" flag.
  1181. *
  1182. * \param encoder An encoder instance to query.
  1183. * \assert
  1184. * \code encoder != NULL \endcode
  1185. * \retval FLAC__bool
  1186. * See FLAC__stream_encoder_set_verify().
  1187. */
  1188. FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder);
  1189. /** Get the <A HREF="https://xiph.org/flac/format.html#subset">Subset</A> flag.
  1190. *
  1191. * \param encoder An encoder instance to query.
  1192. * \assert
  1193. * \code encoder != NULL \endcode
  1194. * \retval FLAC__bool
  1195. * See FLAC__stream_encoder_set_streamable_subset().
  1196. */
  1197. FLAC_API FLAC__bool FLAC__stream_encoder_get_streamable_subset(const FLAC__StreamEncoder *encoder);
  1198. /** Get the number of input channels being processed.
  1199. *
  1200. * \param encoder An encoder instance to query.
  1201. * \assert
  1202. * \code encoder != NULL \endcode
  1203. * \retval uint32_t
  1204. * See FLAC__stream_encoder_set_channels().
  1205. */
  1206. FLAC_API uint32_t FLAC__stream_encoder_get_channels(const FLAC__StreamEncoder *encoder);
  1207. /** Get the input sample resolution setting.
  1208. *
  1209. * \param encoder An encoder instance to query.
  1210. * \assert
  1211. * \code encoder != NULL \endcode
  1212. * \retval uint32_t
  1213. * See FLAC__stream_encoder_set_bits_per_sample().
  1214. */
  1215. FLAC_API uint32_t FLAC__stream_encoder_get_bits_per_sample(const FLAC__StreamEncoder *encoder);
  1216. /** Get the input sample rate setting.
  1217. *
  1218. * \param encoder An encoder instance to query.
  1219. * \assert
  1220. * \code encoder != NULL \endcode
  1221. * \retval uint32_t
  1222. * See FLAC__stream_encoder_set_sample_rate().
  1223. */
  1224. FLAC_API uint32_t FLAC__stream_encoder_get_sample_rate(const FLAC__StreamEncoder *encoder);
  1225. /** Get the blocksize setting.
  1226. *
  1227. * \param encoder An encoder instance to query.
  1228. * \assert
  1229. * \code encoder != NULL \endcode
  1230. * \retval uint32_t
  1231. * See FLAC__stream_encoder_set_blocksize().
  1232. */
  1233. FLAC_API uint32_t FLAC__stream_encoder_get_blocksize(const FLAC__StreamEncoder *encoder);
  1234. /** Get the "mid/side stereo coding" flag.
  1235. *
  1236. * \param encoder An encoder instance to query.
  1237. * \assert
  1238. * \code encoder != NULL \endcode
  1239. * \retval FLAC__bool
  1240. * See FLAC__stream_encoder_get_do_mid_side_stereo().
  1241. */
  1242. FLAC_API FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo(const FLAC__StreamEncoder *encoder);
  1243. /** Get the "adaptive mid/side switching" flag.
  1244. *
  1245. * \param encoder An encoder instance to query.
  1246. * \assert
  1247. * \code encoder != NULL \endcode
  1248. * \retval FLAC__bool
  1249. * See FLAC__stream_encoder_set_loose_mid_side_stereo().
  1250. */
  1251. FLAC_API FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo(const FLAC__StreamEncoder *encoder);
  1252. /** Get the maximum LPC order setting.
  1253. *
  1254. * \param encoder An encoder instance to query.
  1255. * \assert
  1256. * \code encoder != NULL \endcode
  1257. * \retval uint32_t
  1258. * See FLAC__stream_encoder_set_max_lpc_order().
  1259. */
  1260. FLAC_API uint32_t FLAC__stream_encoder_get_max_lpc_order(const FLAC__StreamEncoder *encoder);
  1261. /** Get the quantized linear predictor coefficient precision setting.
  1262. *
  1263. * \param encoder An encoder instance to query.
  1264. * \assert
  1265. * \code encoder != NULL \endcode
  1266. * \retval uint32_t
  1267. * See FLAC__stream_encoder_set_qlp_coeff_precision().
  1268. */
  1269. FLAC_API uint32_t FLAC__stream_encoder_get_qlp_coeff_precision(const FLAC__StreamEncoder *encoder);
  1270. /** Get the qlp coefficient precision search flag.
  1271. *
  1272. * \param encoder An encoder instance to query.
  1273. * \assert
  1274. * \code encoder != NULL \endcode
  1275. * \retval FLAC__bool
  1276. * See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
  1277. */
  1278. FLAC_API FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__StreamEncoder *encoder);
  1279. /** Get the "escape coding" flag.
  1280. *
  1281. * \param encoder An encoder instance to query.
  1282. * \assert
  1283. * \code encoder != NULL \endcode
  1284. * \retval FLAC__bool
  1285. * See FLAC__stream_encoder_set_do_escape_coding().
  1286. */
  1287. FLAC_API FLAC__bool FLAC__stream_encoder_get_do_escape_coding(const FLAC__StreamEncoder *encoder);
  1288. /** Get the exhaustive model search flag.
  1289. *
  1290. * \param encoder An encoder instance to query.
  1291. * \assert
  1292. * \code encoder != NULL \endcode
  1293. * \retval FLAC__bool
  1294. * See FLAC__stream_encoder_set_do_exhaustive_model_search().
  1295. */
  1296. FLAC_API FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search(const FLAC__StreamEncoder *encoder);
  1297. /** Get the minimum residual partition order setting.
  1298. *
  1299. * \param encoder An encoder instance to query.
  1300. * \assert
  1301. * \code encoder != NULL \endcode
  1302. * \retval uint32_t
  1303. * See FLAC__stream_encoder_set_min_residual_partition_order().
  1304. */
  1305. FLAC_API uint32_t FLAC__stream_encoder_get_min_residual_partition_order(const FLAC__StreamEncoder *encoder);
  1306. /** Get maximum residual partition order setting.
  1307. *
  1308. * \param encoder An encoder instance to query.
  1309. * \assert
  1310. * \code encoder != NULL \endcode
  1311. * \retval uint32_t
  1312. * See FLAC__stream_encoder_set_max_residual_partition_order().
  1313. */
  1314. FLAC_API uint32_t FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
  1315. /** Get the Rice parameter search distance setting.
  1316. *
  1317. * \param encoder An encoder instance to query.
  1318. * \assert
  1319. * \code encoder != NULL \endcode
  1320. * \retval uint32_t
  1321. * See FLAC__stream_encoder_set_rice_parameter_search_dist().
  1322. */
  1323. FLAC_API uint32_t FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC__StreamEncoder *encoder);
  1324. /** Get the previously set estimate of the total samples to be encoded.
  1325. * The encoder merely mimics back the value given to
  1326. * FLAC__stream_encoder_set_total_samples_estimate() since it has no
  1327. * other way of knowing how many samples the client will encode.
  1328. *
  1329. * \param encoder An encoder instance to set.
  1330. * \assert
  1331. * \code encoder != NULL \endcode
  1332. * \retval FLAC__uint64
  1333. * See FLAC__stream_encoder_get_total_samples_estimate().
  1334. */
  1335. FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
  1336. /** Get the "limit_min_bitrate" flag.
  1337. *
  1338. * \param encoder An encoder instance to query.
  1339. * \assert
  1340. * \code encoder != NULL \endcode
  1341. * \retval FLAC__bool
  1342. * See FLAC__stream_encoder_set_limit_min_bitrate().
  1343. */
  1344. FLAC_API FLAC__bool FLAC__stream_encoder_get_limit_min_bitrate(const FLAC__StreamEncoder *encoder);
  1345. /** Initialize the encoder instance to encode native FLAC streams.
  1346. *
  1347. * This flavor of initialization sets up the encoder to encode to a
  1348. * native FLAC stream. I/O is performed via callbacks to the client.
  1349. * For encoding to a plain file via filename or open \c FILE*,
  1350. * FLAC__stream_encoder_init_file() and FLAC__stream_encoder_init_FILE()
  1351. * provide a simpler interface.
  1352. *
  1353. * This function should be called after FLAC__stream_encoder_new() and
  1354. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1355. * or FLAC__stream_encoder_process_interleaved().
  1356. * initialization succeeded.
  1357. *
  1358. * The call to FLAC__stream_encoder_init_stream() currently will also
  1359. * immediately call the write callback several times, once with the \c fLaC
  1360. * signature, and once for each encoded metadata block.
  1361. *
  1362. * \param encoder An uninitialized encoder instance.
  1363. * \param write_callback See FLAC__StreamEncoderWriteCallback. This
  1364. * pointer must not be \c NULL.
  1365. * \param seek_callback See FLAC__StreamEncoderSeekCallback. This
  1366. * pointer may be \c NULL if seeking is not
  1367. * supported. The encoder uses seeking to go back
  1368. * and write some some stream statistics to the
  1369. * STREAMINFO block; this is recommended but not
  1370. * necessary to create a valid FLAC stream. If
  1371. * \a seek_callback is not \c NULL then a
  1372. * \a tell_callback must also be supplied.
  1373. * Alternatively, a dummy seek callback that just
  1374. * returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  1375. * may also be supplied, all though this is slightly
  1376. * less efficient for the encoder.
  1377. * \param tell_callback See FLAC__StreamEncoderTellCallback. This
  1378. * pointer may be \c NULL if seeking is not
  1379. * supported. If \a seek_callback is \c NULL then
  1380. * this argument will be ignored. If
  1381. * \a seek_callback is not \c NULL then a
  1382. * \a tell_callback must also be supplied.
  1383. * Alternatively, a dummy tell callback that just
  1384. * returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  1385. * may also be supplied, all though this is slightly
  1386. * less efficient for the encoder.
  1387. * \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
  1388. * pointer may be \c NULL if the callback is not
  1389. * desired. If the client provides a seek callback,
  1390. * this function is not necessary as the encoder
  1391. * will automatically seek back and update the
  1392. * STREAMINFO block. It may also be \c NULL if the
  1393. * client does not support seeking, since it will
  1394. * have no way of going back to update the
  1395. * STREAMINFO. However the client can still supply
  1396. * a callback if it would like to know the details
  1397. * from the STREAMINFO.
  1398. * \param client_data This value will be supplied to callbacks in their
  1399. * \a client_data argument.
  1400. * \assert
  1401. * \code encoder != NULL \endcode
  1402. * \retval FLAC__StreamEncoderInitStatus
  1403. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1404. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1405. */
  1406. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
  1407. /** Initialize the encoder instance to encode Ogg FLAC streams.
  1408. *
  1409. * This flavor of initialization sets up the encoder to encode to a FLAC
  1410. * stream in an Ogg container. I/O is performed via callbacks to the
  1411. * client. For encoding to a plain file via filename or open \c FILE*,
  1412. * FLAC__stream_encoder_init_ogg_file() and FLAC__stream_encoder_init_ogg_FILE()
  1413. * provide a simpler interface.
  1414. *
  1415. * This function should be called after FLAC__stream_encoder_new() and
  1416. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1417. * or FLAC__stream_encoder_process_interleaved().
  1418. * initialization succeeded.
  1419. *
  1420. * The call to FLAC__stream_encoder_init_ogg_stream() currently will also
  1421. * immediately call the write callback several times to write the metadata
  1422. * packets.
  1423. *
  1424. * \param encoder An uninitialized encoder instance.
  1425. * \param read_callback See FLAC__StreamEncoderReadCallback. This
  1426. * pointer must not be \c NULL if \a seek_callback
  1427. * is non-NULL since they are both needed to be
  1428. * able to write data back to the Ogg FLAC stream
  1429. * in the post-encode phase.
  1430. * \param write_callback See FLAC__StreamEncoderWriteCallback. This
  1431. * pointer must not be \c NULL.
  1432. * \param seek_callback See FLAC__StreamEncoderSeekCallback. This
  1433. * pointer may be \c NULL if seeking is not
  1434. * supported. The encoder uses seeking to go back
  1435. * and write some some stream statistics to the
  1436. * STREAMINFO block; this is recommended but not
  1437. * necessary to create a valid FLAC stream. If
  1438. * \a seek_callback is not \c NULL then a
  1439. * \a tell_callback must also be supplied.
  1440. * Alternatively, a dummy seek callback that just
  1441. * returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
  1442. * may also be supplied, all though this is slightly
  1443. * less efficient for the encoder.
  1444. * \param tell_callback See FLAC__StreamEncoderTellCallback. This
  1445. * pointer may be \c NULL if seeking is not
  1446. * supported. If \a seek_callback is \c NULL then
  1447. * this argument will be ignored. If
  1448. * \a seek_callback is not \c NULL then a
  1449. * \a tell_callback must also be supplied.
  1450. * Alternatively, a dummy tell callback that just
  1451. * returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
  1452. * may also be supplied, all though this is slightly
  1453. * less efficient for the encoder.
  1454. * \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
  1455. * pointer may be \c NULL if the callback is not
  1456. * desired. If the client provides a seek callback,
  1457. * this function is not necessary as the encoder
  1458. * will automatically seek back and update the
  1459. * STREAMINFO block. It may also be \c NULL if the
  1460. * client does not support seeking, since it will
  1461. * have no way of going back to update the
  1462. * STREAMINFO. However the client can still supply
  1463. * a callback if it would like to know the details
  1464. * from the STREAMINFO.
  1465. * \param client_data This value will be supplied to callbacks in their
  1466. * \a client_data argument.
  1467. * \assert
  1468. * \code encoder != NULL \endcode
  1469. * \retval FLAC__StreamEncoderInitStatus
  1470. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1471. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1472. */
  1473. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderReadCallback read_callback, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
  1474. /** Initialize the encoder instance to encode native FLAC files.
  1475. *
  1476. * This flavor of initialization sets up the encoder to encode to a
  1477. * plain native FLAC file. For non-stdio streams, you must use
  1478. * FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
  1479. *
  1480. * This function should be called after FLAC__stream_encoder_new() and
  1481. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1482. * or FLAC__stream_encoder_process_interleaved().
  1483. * initialization succeeded.
  1484. *
  1485. * \param encoder An uninitialized encoder instance.
  1486. * \param file An open file. The file should have been opened
  1487. * with mode \c "w+b" and rewound. The file
  1488. * becomes owned by the encoder and should not be
  1489. * manipulated by the client while encoding.
  1490. * Unless \a file is \c stdout, it will be closed
  1491. * when FLAC__stream_encoder_finish() is called.
  1492. * Note however that a proper SEEKTABLE cannot be
  1493. * created when encoding to \c stdout since it is
  1494. * not seekable.
  1495. * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
  1496. * pointer may be \c NULL if the callback is not
  1497. * desired.
  1498. * \param client_data This value will be supplied to callbacks in their
  1499. * \a client_data argument.
  1500. * \assert
  1501. * \code encoder != NULL \endcode
  1502. * \code file != NULL \endcode
  1503. * \retval FLAC__StreamEncoderInitStatus
  1504. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1505. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1506. */
  1507. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1508. /** Initialize the encoder instance to encode Ogg FLAC files.
  1509. *
  1510. * This flavor of initialization sets up the encoder to encode to a
  1511. * plain Ogg FLAC file. For non-stdio streams, you must use
  1512. * FLAC__stream_encoder_init_ogg_stream() and provide callbacks for the I/O.
  1513. *
  1514. * This function should be called after FLAC__stream_encoder_new() and
  1515. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1516. * or FLAC__stream_encoder_process_interleaved().
  1517. * initialization succeeded.
  1518. *
  1519. * \param encoder An uninitialized encoder instance.
  1520. * \param file An open file. The file should have been opened
  1521. * with mode \c "w+b" and rewound. The file
  1522. * becomes owned by the encoder and should not be
  1523. * manipulated by the client while encoding.
  1524. * Unless \a file is \c stdout, it will be closed
  1525. * when FLAC__stream_encoder_finish() is called.
  1526. * Note however that a proper SEEKTABLE cannot be
  1527. * created when encoding to \c stdout since it is
  1528. * not seekable.
  1529. * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
  1530. * pointer may be \c NULL if the callback is not
  1531. * desired.
  1532. * \param client_data This value will be supplied to callbacks in their
  1533. * \a client_data argument.
  1534. * \assert
  1535. * \code encoder != NULL \endcode
  1536. * \code file != NULL \endcode
  1537. * \retval FLAC__StreamEncoderInitStatus
  1538. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1539. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1540. */
  1541. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1542. /** Initialize the encoder instance to encode native FLAC files.
  1543. *
  1544. * This flavor of initialization sets up the encoder to encode to a plain
  1545. * FLAC file. If POSIX fopen() semantics are not sufficient you must use
  1546. * FLAC__stream_encoder_init_FILE(), or FLAC__stream_encoder_init_stream()
  1547. * and provide callbacks for the I/O.
  1548. *
  1549. * On Windows, filename must be a UTF-8 encoded filename, which libFLAC
  1550. * internally translates to an appropriate representation to use with
  1551. * _wfopen. On all other systems, filename is passed to fopen without
  1552. * any translation.
  1553. *
  1554. * This function should be called after FLAC__stream_encoder_new() and
  1555. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1556. * or FLAC__stream_encoder_process_interleaved().
  1557. * initialization succeeded.
  1558. *
  1559. * \param encoder An uninitialized encoder instance.
  1560. * \param filename The name of the file to encode to. The file will
  1561. * be opened with fopen(). Use \c NULL to encode to
  1562. * \c stdout. Note however that a proper SEEKTABLE
  1563. * cannot be created when encoding to \c stdout since
  1564. * it is not seekable.
  1565. * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
  1566. * pointer may be \c NULL if the callback is not
  1567. * desired.
  1568. * \param client_data This value will be supplied to callbacks in their
  1569. * \a client_data argument.
  1570. * \assert
  1571. * \code encoder != NULL \endcode
  1572. * \retval FLAC__StreamEncoderInitStatus
  1573. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1574. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1575. */
  1576. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1577. /** Initialize the encoder instance to encode Ogg FLAC files.
  1578. *
  1579. * This flavor of initialization sets up the encoder to encode to a plain
  1580. * Ogg FLAC file. If POSIX fopen() semantics are not sufficient, you must use
  1581. * FLAC__stream_encoder_init_ogg_FILE(), or FLAC__stream_encoder_init_ogg_stream()
  1582. * and provide callbacks for the I/O.
  1583. *
  1584. * On Windows, filename must be a UTF-8 encoded filename, which libFLAC
  1585. * internally translates to an appropriate representation to use with
  1586. * _wfopen. On all other systems, filename is passed to fopen without
  1587. * any translation.
  1588. *
  1589. * This function should be called after FLAC__stream_encoder_new() and
  1590. * FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
  1591. * or FLAC__stream_encoder_process_interleaved().
  1592. * initialization succeeded.
  1593. *
  1594. * \param encoder An uninitialized encoder instance.
  1595. * \param filename The name of the file to encode to. The file will
  1596. * be opened with fopen(). Use \c NULL to encode to
  1597. * \c stdout. Note however that a proper SEEKTABLE
  1598. * cannot be created when encoding to \c stdout since
  1599. * it is not seekable.
  1600. * \param progress_callback See FLAC__StreamEncoderProgressCallback. This
  1601. * pointer may be \c NULL if the callback is not
  1602. * desired.
  1603. * \param client_data This value will be supplied to callbacks in their
  1604. * \a client_data argument.
  1605. * \assert
  1606. * \code encoder != NULL \endcode
  1607. * \retval FLAC__StreamEncoderInitStatus
  1608. * \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
  1609. * see FLAC__StreamEncoderInitStatus for the meanings of other return values.
  1610. */
  1611. FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_ogg_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
  1612. /** Finish the encoding process.
  1613. * Flushes the encoding buffer, releases resources, resets the encoder
  1614. * settings to their defaults, and returns the encoder state to
  1615. * FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
  1616. * one or more write callbacks before returning, and will generate
  1617. * a metadata callback.
  1618. *
  1619. * Note that in the course of processing the last frame, errors can
  1620. * occur, so the caller should be sure to check the return value to
  1621. * ensure the file was encoded properly.
  1622. *
  1623. * In the event of a prematurely-terminated encode, it is not strictly
  1624. * necessary to call this immediately before FLAC__stream_encoder_delete()
  1625. * but it is good practice to match every FLAC__stream_encoder_init_*()
  1626. * with a FLAC__stream_encoder_finish().
  1627. *
  1628. * \param encoder An uninitialized encoder instance.
  1629. * \assert
  1630. * \code encoder != NULL \endcode
  1631. * \retval FLAC__bool
  1632. * \c false if an error occurred processing the last frame; or if verify
  1633. * mode is set (see FLAC__stream_encoder_set_verify()), there was a
  1634. * verify mismatch; else \c true. If \c false, caller should check the
  1635. * state with FLAC__stream_encoder_get_state() for more information
  1636. * about the error.
  1637. */
  1638. FLAC_API FLAC__bool FLAC__stream_encoder_finish(FLAC__StreamEncoder *encoder);
  1639. /** Submit data for encoding.
  1640. * This version allows you to supply the input data via an array of
  1641. * pointers, each pointer pointing to an array of \a samples samples
  1642. * representing one channel. The samples need not be block-aligned,
  1643. * but each channel should have the same number of samples. Each sample
  1644. * should be a signed integer, right-justified to the resolution set by
  1645. * FLAC__stream_encoder_set_bits_per_sample(). For example, if the
  1646. * resolution is 16 bits per sample, the samples should all be in the
  1647. * range [-32768,32767].
  1648. *
  1649. * For applications where channel order is important, channels must
  1650. * follow the order as described in the
  1651. * <A HREF="https://xiph.org/flac/format.html#frame_header">frame header</A>.
  1652. *
  1653. * \param encoder An initialized encoder instance in the OK state.
  1654. * \param buffer An array of pointers to each channel's signal.
  1655. * \param samples The number of samples in one channel.
  1656. * \assert
  1657. * \code encoder != NULL \endcode
  1658. * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
  1659. * \retval FLAC__bool
  1660. * \c true if successful, else \c false; in this case, check the
  1661. * encoder state with FLAC__stream_encoder_get_state() to see what
  1662. * went wrong.
  1663. */
  1664. FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], uint32_t samples);
  1665. /** Submit data for encoding.
  1666. * This version allows you to supply the input data where the channels
  1667. * are interleaved into a single array (i.e. channel0_sample0,
  1668. * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...).
  1669. * The samples need not be block-aligned but they must be
  1670. * sample-aligned, i.e. the first value should be channel0_sample0
  1671. * and the last value channelN_sampleM. Each sample should be a signed
  1672. * integer, right-justified to the resolution set by
  1673. * FLAC__stream_encoder_set_bits_per_sample(). For example, if the
  1674. * resolution is 16 bits per sample, the samples should all be in the
  1675. * range [-32768,32767].
  1676. *
  1677. * For applications where channel order is important, channels must
  1678. * follow the order as described in the
  1679. * <A HREF="https://xiph.org/flac/format.html#frame_header">frame header</A>.
  1680. *
  1681. * \param encoder An initialized encoder instance in the OK state.
  1682. * \param buffer An array of channel-interleaved data (see above).
  1683. * \param samples The number of samples in one channel, the same as for
  1684. * FLAC__stream_encoder_process(). For example, if
  1685. * encoding two channels, \c 1000 \a samples corresponds
  1686. * to a \a buffer of 2000 values.
  1687. * \assert
  1688. * \code encoder != NULL \endcode
  1689. * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode
  1690. * \retval FLAC__bool
  1691. * \c true if successful, else \c false; in this case, check the
  1692. * encoder state with FLAC__stream_encoder_get_state() to see what
  1693. * went wrong.
  1694. */
  1695. FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], uint32_t samples);
  1696. /* \} */
  1697. #ifdef __cplusplus
  1698. }
  1699. #endif
  1700. #endif