From bf16f771bde5915bcf97be3620fac51a33f6a0bb Mon Sep 17 00:00:00 2001 From: "alexey.lysiuk" Date: Sun, 23 Oct 2016 11:50:02 +0300 Subject: [PATCH] + FLAC 1.3.1 http://www.xiph.org http://downloads.xiph.org/releases/flac/flac-1.3.1.tar.xz ./configure --disable-shared --enable-static && make install --- flac/include/FLAC/all.h | 371 +++++ flac/include/FLAC/assert.h | 46 + flac/include/FLAC/callback.h | 185 +++ flac/include/FLAC/export.h | 97 ++ flac/include/FLAC/format.h | 1025 +++++++++++++ flac/include/FLAC/metadata.h | 2182 ++++++++++++++++++++++++++++ flac/include/FLAC/ordinals.h | 86 ++ flac/include/FLAC/stream_decoder.h | 1560 ++++++++++++++++++++ flac/include/FLAC/stream_encoder.h | 1790 +++++++++++++++++++++++ flac/lib/libFLAC.a | Bin 0 -> 331624 bytes 10 files changed, 7342 insertions(+) create mode 100644 flac/include/FLAC/all.h create mode 100644 flac/include/FLAC/assert.h create mode 100644 flac/include/FLAC/callback.h create mode 100644 flac/include/FLAC/export.h create mode 100644 flac/include/FLAC/format.h create mode 100644 flac/include/FLAC/metadata.h create mode 100644 flac/include/FLAC/ordinals.h create mode 100644 flac/include/FLAC/stream_decoder.h create mode 100644 flac/include/FLAC/stream_encoder.h create mode 100644 flac/lib/libFLAC.a diff --git a/flac/include/FLAC/all.h b/flac/include/FLAC/all.h new file mode 100644 index 00000000..2851cf59 --- /dev/null +++ b/flac/include/FLAC/all.h @@ -0,0 +1,371 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__ALL_H +#define FLAC__ALL_H + +#include "export.h" + +#include "assert.h" +#include "callback.h" +#include "format.h" +#include "metadata.h" +#include "ordinals.h" +#include "stream_decoder.h" +#include "stream_encoder.h" + +/** \mainpage + * + * \section intro Introduction + * + * This is the documentation for the FLAC C and C++ APIs. It is + * highly interconnected; this introduction should give you a top + * level idea of the structure and how to find the information you + * need. As a prerequisite you should have at least a basic + * knowledge of the FLAC format, documented + * here. + * + * \section c_api FLAC C API + * + * The FLAC C API is the interface to libFLAC, a set of structures + * describing the components of FLAC streams, and functions for + * encoding and decoding streams, as well as manipulating FLAC + * metadata in files. The public include files will be installed + * in your include area (for example /usr/include/FLAC/...). + * + * By writing a little code and linking against libFLAC, it is + * relatively easy to add FLAC support to another program. The + * library is licensed under Xiph's BSD license. + * Complete source code of libFLAC as well as the command-line + * encoder and plugins is available and is a useful source of + * examples. + * + * Aside from encoders and decoders, libFLAC provides a powerful + * metadata interface for manipulating metadata in FLAC files. It + * allows the user to add, delete, and modify FLAC metadata blocks + * and it can automatically take advantage of PADDING blocks to avoid + * rewriting the entire FLAC file when changing the size of the + * metadata. + * + * libFLAC usually only requires the standard C library and C math + * library. In particular, threading is not used so there is no + * dependency on a thread library. However, libFLAC does not use + * global variables and should be thread-safe. + * + * libFLAC also supports encoding to and decoding from Ogg FLAC. + * However the metadata editing interfaces currently have limited + * read-only support for Ogg FLAC files. + * + * \section cpp_api FLAC C++ API + * + * The FLAC C++ API is a set of classes that encapsulate the + * structures and functions in libFLAC. They provide slightly more + * functionality with respect to metadata but are otherwise + * equivalent. For the most part, they share the same usage as + * their counterparts in libFLAC, and the FLAC C API documentation + * can be used as a supplement. The public include files + * for the C++ API will be installed in your include area (for + * example /usr/include/FLAC++/...). + * + * libFLAC++ is also licensed under + * Xiph's BSD license. + * + * \section getting_started Getting Started + * + * A good starting point for learning the API is to browse through + * the modules. Modules are logical + * groupings of related functions or classes, which correspond roughly + * to header files or sections of header files. Each module includes a + * detailed description of the general usage of its functions or + * classes. + * + * From there you can go on to look at the documentation of + * individual functions. You can see different views of the individual + * functions through the links in top bar across this page. + * + * If you prefer a more hands-on approach, you can jump right to some + * example code. + * + * \section porting_guide Porting Guide + * + * Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink + * has been introduced which gives detailed instructions on how to + * port your code to newer versions of FLAC. + * + * \section embedded_developers Embedded Developers + * + * libFLAC has grown larger over time as more functionality has been + * included, but much of it may be unnecessary for a particular embedded + * implementation. Unused parts may be pruned by some simple editing of + * src/libFLAC/Makefile.am. In general, the decoders, encoders, and + * metadata interface are all independent from each other. + * + * It is easiest to just describe the dependencies: + * + * - All modules depend on the \link flac_format Format \endlink module. + * - The decoders and encoders depend on the bitbuffer. + * - The decoder is independent of the encoder. The encoder uses the + * decoder because of the verify feature, but this can be removed if + * not needed. + * - Parts of the metadata interface require the stream decoder (but not + * the encoder). + * - Ogg support is selectable through the compile time macro + * \c FLAC__HAS_OGG. + * + * For example, if your application only requires the stream decoder, no + * encoder, and no metadata interface, you can remove the stream encoder + * and the metadata interface, which will greatly reduce the size of the + * library. + * + * Also, there are several places in the libFLAC code with comments marked + * with "OPT:" where a #define can be changed to enable code that might be + * faster on a specific platform. Experimenting with these can yield faster + * binaries. + */ + +/** \defgroup porting Porting Guide for New Versions + * + * This module describes differences in the library interfaces from + * version to version. It assists in the porting of code that uses + * the libraries to newer versions of FLAC. + * + * One simple facility for making porting easier that has been added + * in FLAC 1.1.3 is a set of \c #defines in \c export.h of each + * library's includes (e.g. \c include/FLAC/export.h). The + * \c #defines mirror the libraries' + * libtool version numbers, + * e.g. in libFLAC there are \c FLAC_API_VERSION_CURRENT, + * \c FLAC_API_VERSION_REVISION, and \c FLAC_API_VERSION_AGE. + * These can be used to support multiple versions of an API during the + * transition phase, e.g. + * + * \code + * #if !defined(FLAC_API_VERSION_CURRENT) || FLAC_API_VERSION_CURRENT <= 7 + * legacy code + * #else + * new code + * #endif + * \endcode + * + * The the source will work for multiple versions and the legacy code can + * easily be removed when the transition is complete. + * + * Another available symbol is FLAC_API_SUPPORTS_OGG_FLAC (defined in + * include/FLAC/export.h), which can be used to determine whether or not + * the library has been compiled with support for Ogg FLAC. This is + * simpler than trying to call an Ogg init function and catching the + * error. + */ + +/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3 + * \ingroup porting + * + * \brief + * This module describes porting from FLAC 1.1.2 to FLAC 1.1.3. + * + * The main change between the APIs in 1.1.2 and 1.1.3 is that they have + * been simplified. First, libOggFLAC has been merged into libFLAC and + * libOggFLAC++ has been merged into libFLAC++. Second, both the three + * decoding layers and three encoding layers have been merged into a + * single stream decoder and stream encoder. That is, the functionality + * of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged + * into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and + * FLAC__FileEncoder into FLAC__StreamEncoder. Only the + * FLAC__StreamDecoder and FLAC__StreamEncoder remain. What this means + * is there is now a single API that can be used to encode or decode + * streams to/from native FLAC or Ogg FLAC and the single API can work + * on both seekable and non-seekable streams. + * + * Instead of creating an encoder or decoder of a certain layer, now the + * client will always create a FLAC__StreamEncoder or + * FLAC__StreamDecoder. The old layers are now differentiated by the + * initialization function. For example, for the decoder, + * FLAC__stream_decoder_init() has been replaced by + * FLAC__stream_decoder_init_stream(). This init function takes + * callbacks for the I/O, and the seeking callbacks are optional. This + * allows the client to use the same object for seekable and + * non-seekable streams. For decoding a FLAC file directly, the client + * can use FLAC__stream_decoder_init_file() and pass just a filename + * and fewer callbacks; most of the other callbacks are supplied + * internally. For situations where fopen()ing by filename is not + * possible (e.g. Unicode filenames on Windows) the client can instead + * open the file itself and supply the FILE* to + * FLAC__stream_decoder_init_FILE(). The init functions now returns a + * FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState. + * Since the callbacks and client data are now passed to the init + * function, the FLAC__stream_decoder_set_*_callback() functions and + * FLAC__stream_decoder_set_client_data() are no longer needed. The + * rest of the calls to the decoder are the same as before. + * + * There are counterpart init functions for Ogg FLAC, e.g. + * FLAC__stream_decoder_init_ogg_stream(). All the rest of the calls + * and callbacks are the same as for native FLAC. + * + * As an example, in FLAC 1.1.2 a seekable stream decoder would have + * been set up like so: + * + * \code + * FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new(); + * if(decoder == NULL) do_something; + * FLAC__seekable_stream_decoder_set_md5_checking(decoder, true); + * [... other settings ...] + * FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback); + * FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback); + * FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback); + * FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback); + * FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback); + * FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback); + * FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback); + * FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback); + * FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data); + * if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do_something; + * \endcode + * + * In FLAC 1.1.3 it is like this: + * + * \code + * FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new(); + * if(decoder == NULL) do_something; + * FLAC__stream_decoder_set_md5_checking(decoder, true); + * [... other settings ...] + * if(FLAC__stream_decoder_init_stream( + * decoder, + * my_read_callback, + * my_seek_callback, // or NULL + * my_tell_callback, // or NULL + * my_length_callback, // or NULL + * my_eof_callback, // or NULL + * my_write_callback, + * my_metadata_callback, // or NULL + * my_error_callback, + * my_client_data + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; + * \endcode + * + * or you could do; + * + * \code + * [...] + * FILE *file = fopen("somefile.flac","rb"); + * if(file == NULL) do_somthing; + * if(FLAC__stream_decoder_init_FILE( + * decoder, + * file, + * my_write_callback, + * my_metadata_callback, // or NULL + * my_error_callback, + * my_client_data + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; + * \endcode + * + * or just: + * + * \code + * [...] + * if(FLAC__stream_decoder_init_file( + * decoder, + * "somefile.flac", + * my_write_callback, + * my_metadata_callback, // or NULL + * my_error_callback, + * my_client_data + * ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do_something; + * \endcode + * + * Another small change to the decoder is in how it handles unparseable + * streams. Before, when the decoder found an unparseable stream + * (reserved for when the decoder encounters a stream from a future + * encoder that it can't parse), it changed the state to + * \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM. Now the decoder instead + * drops sync and calls the error callback with a new error code + * \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM. This is + * more robust. If your error callback does not discriminate on the the + * error state, your code does not need to be changed. + * + * The encoder now has a new setting: + * FLAC__stream_encoder_set_apodization(). This is for setting the + * method used to window the data before LPC analysis. You only need to + * add a call to this function if the default is not suitable. There + * are also two new convenience functions that may be useful: + * FLAC__metadata_object_cuesheet_calculate_cddb_id() and + * FLAC__metadata_get_cuesheet(). + * + * The \a bytes parameter to FLAC__StreamDecoderReadCallback, + * FLAC__StreamEncoderReadCallback, and FLAC__StreamEncoderWriteCallback + * is now \c size_t instead of \c unsigned. + */ + +/** \defgroup porting_1_1_3_to_1_1_4 Porting from FLAC 1.1.3 to 1.1.4 + * \ingroup porting + * + * \brief + * This module describes porting from FLAC 1.1.3 to FLAC 1.1.4. + * + * There were no changes to any of the interfaces from 1.1.3 to 1.1.4. + * There was a slight change in the implementation of + * FLAC__stream_encoder_set_metadata(); the function now makes a copy + * of the \a metadata array of pointers so the client no longer needs + * to maintain it after the call. The objects themselves that are + * pointed to by the array are still not copied though and must be + * maintained until the call to FLAC__stream_encoder_finish(). + */ + +/** \defgroup porting_1_1_4_to_1_2_0 Porting from FLAC 1.1.4 to 1.2.0 + * \ingroup porting + * + * \brief + * This module describes porting from FLAC 1.1.4 to FLAC 1.2.0. + * + * There were only very minor changes to the interfaces from 1.1.4 to 1.2.0. + * In libFLAC, \c FLAC__format_sample_rate_is_subset() was added. + * In libFLAC++, \c FLAC::Decoder::Stream::get_decode_position() was added. + * + * Finally, value of the constant \c FLAC__FRAME_HEADER_RESERVED_LEN + * has changed to reflect the conversion of one of the reserved bits + * into active use. It used to be \c 2 and now is \c 1. However the + * FLAC frame header length has not changed, so to skip the proper + * number of bits, use \c FLAC__FRAME_HEADER_RESERVED_LEN + + * \c FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN + */ + +/** \defgroup flac FLAC C API + * + * The FLAC C API is the interface to libFLAC, a set of structures + * describing the components of FLAC streams, and functions for + * encoding and decoding streams, as well as manipulating FLAC + * metadata in files. + * + * You should start with the format components as all other modules + * are dependent on it. + */ + +#endif diff --git a/flac/include/FLAC/assert.h b/flac/include/FLAC/assert.h new file mode 100644 index 00000000..dc9bcef4 --- /dev/null +++ b/flac/include/FLAC/assert.h @@ -0,0 +1,46 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2001-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__ASSERT_H +#define FLAC__ASSERT_H + +/* we need this since some compilers (like MSVC) leave assert()s on release code (and we don't want to use their ASSERT) */ +#ifdef DEBUG +#include +#define FLAC__ASSERT(x) assert(x) +#define FLAC__ASSERT_DECLARATION(x) x +#else +#define FLAC__ASSERT(x) +#define FLAC__ASSERT_DECLARATION(x) +#endif + +#endif diff --git a/flac/include/FLAC/callback.h b/flac/include/FLAC/callback.h new file mode 100644 index 00000000..ce8787ff --- /dev/null +++ b/flac/include/FLAC/callback.h @@ -0,0 +1,185 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2004-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__CALLBACK_H +#define FLAC__CALLBACK_H + +#include "ordinals.h" +#include /* for size_t */ + +/** \file include/FLAC/callback.h + * + * \brief + * This module defines the structures for describing I/O callbacks + * to the other FLAC interfaces. + * + * See the detailed documentation for callbacks in the + * \link flac_callbacks callbacks \endlink module. + */ + +/** \defgroup flac_callbacks FLAC/callback.h: I/O callback structures + * \ingroup flac + * + * \brief + * This module defines the structures for describing I/O callbacks + * to the other FLAC interfaces. + * + * The purpose of the I/O callback functions is to create a common way + * for the metadata interfaces to handle I/O. + * + * Originally the metadata interfaces required filenames as the way of + * specifying FLAC files to operate on. This is problematic in some + * environments so there is an additional option to specify a set of + * callbacks for doing I/O on the FLAC file, instead of the filename. + * + * In addition to the callbacks, a FLAC__IOHandle type is defined as an + * opaque structure for a data source. + * + * The callback function prototypes are similar (but not identical) to the + * stdio functions fread, fwrite, fseek, ftell, feof, and fclose. If you use + * stdio streams to implement the callbacks, you can pass fread, fwrite, and + * fclose anywhere a FLAC__IOCallback_Read, FLAC__IOCallback_Write, or + * FLAC__IOCallback_Close is required, and a FILE* anywhere a FLAC__IOHandle + * is required. \warning You generally CANNOT directly use fseek or ftell + * for FLAC__IOCallback_Seek or FLAC__IOCallback_Tell since on most systems + * these use 32-bit offsets and FLAC requires 64-bit offsets to deal with + * large files. You will have to find an equivalent function (e.g. ftello), + * or write a wrapper. The same is true for feof() since this is usually + * implemented as a macro, not as a function whose address can be taken. + * + * \{ + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** This is the opaque handle type used by the callbacks. Typically + * this is a \c FILE* or address of a file descriptor. + */ +typedef void* FLAC__IOHandle; + +/** Signature for the read callback. + * The signature and semantics match POSIX fread() implementations + * and can generally be used interchangeably. + * + * \param ptr The address of the read buffer. + * \param size The size of the records to be read. + * \param nmemb The number of records to be read. + * \param handle The handle to the data source. + * \retval size_t + * The number of records read. + */ +typedef size_t (*FLAC__IOCallback_Read) (void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); + +/** Signature for the write callback. + * The signature and semantics match POSIX fwrite() implementations + * and can generally be used interchangeably. + * + * \param ptr The address of the write buffer. + * \param size The size of the records to be written. + * \param nmemb The number of records to be written. + * \param handle The handle to the data source. + * \retval size_t + * The number of records written. + */ +typedef size_t (*FLAC__IOCallback_Write) (const void *ptr, size_t size, size_t nmemb, FLAC__IOHandle handle); + +/** Signature for the seek callback. + * The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT + * EXCEPTION: the offset is a 64-bit type whereas fseek() is generally 'long' + * and 32-bits wide. + * + * \param handle The handle to the data source. + * \param offset The new position, relative to \a whence + * \param whence \c SEEK_SET, \c SEEK_CUR, or \c SEEK_END + * \retval int + * \c 0 on success, \c -1 on error. + */ +typedef int (*FLAC__IOCallback_Seek) (FLAC__IOHandle handle, FLAC__int64 offset, int whence); + +/** Signature for the tell callback. + * The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT + * EXCEPTION: the offset is a 64-bit type whereas ftell() is generally 'long' + * and 32-bits wide. + * + * \param handle The handle to the data source. + * \retval FLAC__int64 + * The current position on success, \c -1 on error. + */ +typedef FLAC__int64 (*FLAC__IOCallback_Tell) (FLAC__IOHandle handle); + +/** Signature for the EOF callback. + * The signature and semantics mostly match POSIX feof() but WATCHOUT: + * on many systems, feof() is a macro, so in this case a wrapper function + * must be provided instead. + * + * \param handle The handle to the data source. + * \retval int + * \c 0 if not at end of file, nonzero if at end of file. + */ +typedef int (*FLAC__IOCallback_Eof) (FLAC__IOHandle handle); + +/** Signature for the close callback. + * The signature and semantics match POSIX fclose() implementations + * and can generally be used interchangeably. + * + * \param handle The handle to the data source. + * \retval int + * \c 0 on success, \c EOF on error. + */ +typedef int (*FLAC__IOCallback_Close) (FLAC__IOHandle handle); + +/** A structure for holding a set of callbacks. + * Each FLAC interface that requires a FLAC__IOCallbacks structure will + * describe which of the callbacks are required. The ones that are not + * required may be set to NULL. + * + * If the seek requirement for an interface is optional, you can signify that + * a data sorce is not seekable by setting the \a seek field to \c NULL. + */ +typedef struct { + FLAC__IOCallback_Read read; + FLAC__IOCallback_Write write; + FLAC__IOCallback_Seek seek; + FLAC__IOCallback_Tell tell; + FLAC__IOCallback_Eof eof; + FLAC__IOCallback_Close close; +} FLAC__IOCallbacks; + +/* \} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/flac/include/FLAC/export.h b/flac/include/FLAC/export.h new file mode 100644 index 00000000..9cc9e137 --- /dev/null +++ b/flac/include/FLAC/export.h @@ -0,0 +1,97 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__EXPORT_H +#define FLAC__EXPORT_H + +/** \file include/FLAC/export.h + * + * \brief + * This module contains #defines and symbols for exporting function + * calls, and providing version information and compiled-in features. + * + * See the \link flac_export export \endlink module. + */ + +/** \defgroup flac_export FLAC/export.h: export symbols + * \ingroup flac + * + * \brief + * This module contains #defines and symbols for exporting function + * calls, and providing version information and compiled-in features. + * + * If you are compiling with MSVC and will link to the static library + * (libFLAC.lib) you should define FLAC__NO_DLL in your project to + * make sure the symbols are exported properly. + * + * \{ + */ + +#if defined(FLAC__NO_DLL) +#define FLAC_API + +#elif defined(_MSC_VER) +#ifdef FLAC_API_EXPORTS +#define FLAC_API __declspec(dllexport) +#else +#define FLAC_API __declspec(dllimport) +#endif + +#elif defined(FLAC__USE_VISIBILITY_ATTR) +#define FLAC_API __attribute__ ((visibility ("default"))) + +#else +#define FLAC_API + +#endif + +/** These #defines will mirror the libtool-based library version number, see + * http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning + */ +#define FLAC_API_VERSION_CURRENT 11 +#define FLAC_API_VERSION_REVISION 0 /**< see above */ +#define FLAC_API_VERSION_AGE 3 /**< see above */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */ +extern FLAC_API int FLAC_API_SUPPORTS_OGG_FLAC; + +#ifdef __cplusplus +} +#endif + +/* \} */ + +#endif diff --git a/flac/include/FLAC/format.h b/flac/include/FLAC/format.h new file mode 100644 index 00000000..7424565b --- /dev/null +++ b/flac/include/FLAC/format.h @@ -0,0 +1,1025 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__FORMAT_H +#define FLAC__FORMAT_H + +#include "export.h" +#include "ordinals.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** \file include/FLAC/format.h + * + * \brief + * This module contains structure definitions for the representation + * of FLAC format components in memory. These are the basic + * structures used by the rest of the interfaces. + * + * See the detailed documentation in the + * \link flac_format format \endlink module. + */ + +/** \defgroup flac_format FLAC/format.h: format components + * \ingroup flac + * + * \brief + * This module contains structure definitions for the representation + * of FLAC format components in memory. These are the basic + * structures used by the rest of the interfaces. + * + * First, you should be familiar with the + * FLAC format. Many of the values here + * follow directly from the specification. As a user of libFLAC, the + * interesting parts really are the structures that describe the frame + * header and metadata blocks. + * + * The format structures here are very primitive, designed to store + * information in an efficient way. Reading information from the + * structures is easy but creating or modifying them directly is + * more complex. For the most part, as a user of a library, editing + * is not necessary; however, for metadata blocks it is, so there are + * convenience functions provided in the \link flac_metadata metadata + * module \endlink to simplify the manipulation of metadata blocks. + * + * \note + * It's not the best convention, but symbols ending in _LEN are in bits + * and _LENGTH are in bytes. _LENGTH symbols are \#defines instead of + * global variables because they are usually used when declaring byte + * arrays and some compilers require compile-time knowledge of array + * sizes when declared on the stack. + * + * \{ + */ + + +/* + Most of the values described in this file are defined by the FLAC + format specification. There is nothing to tune here. +*/ + +/** The largest legal metadata type code. */ +#define FLAC__MAX_METADATA_TYPE_CODE (126u) + +/** The minimum block size, in samples, permitted by the format. */ +#define FLAC__MIN_BLOCK_SIZE (16u) + +/** The maximum block size, in samples, permitted by the format. */ +#define FLAC__MAX_BLOCK_SIZE (65535u) + +/** The maximum block size, in samples, permitted by the FLAC subset for + * sample rates up to 48kHz. */ +#define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u) + +/** The maximum number of channels permitted by the format. */ +#define FLAC__MAX_CHANNELS (8u) + +/** The minimum sample resolution permitted by the format. */ +#define FLAC__MIN_BITS_PER_SAMPLE (4u) + +/** The maximum sample resolution permitted by the format. */ +#define FLAC__MAX_BITS_PER_SAMPLE (32u) + +/** The maximum sample resolution permitted by libFLAC. + * + * \warning + * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format. However, + * the reference encoder/decoder is currently limited to 24 bits because + * of prevalent 32-bit math, so make sure and use this value when + * appropriate. + */ +#define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u) + +/** The maximum sample rate permitted by the format. The value is + * ((2 ^ 16) - 1) * 10; see FLAC format + * as to why. + */ +#define FLAC__MAX_SAMPLE_RATE (655350u) + +/** The maximum LPC order permitted by the format. */ +#define FLAC__MAX_LPC_ORDER (32u) + +/** The maximum LPC order permitted by the FLAC subset for sample rates + * up to 48kHz. */ +#define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u) + +/** The minimum quantized linear predictor coefficient precision + * permitted by the format. + */ +#define FLAC__MIN_QLP_COEFF_PRECISION (5u) + +/** The maximum quantized linear predictor coefficient precision + * permitted by the format. + */ +#define FLAC__MAX_QLP_COEFF_PRECISION (15u) + +/** The maximum order of the fixed predictors permitted by the format. */ +#define FLAC__MAX_FIXED_ORDER (4u) + +/** The maximum Rice partition order permitted by the format. */ +#define FLAC__MAX_RICE_PARTITION_ORDER (15u) + +/** The maximum Rice partition order permitted by the FLAC Subset. */ +#define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u) + +/** The version string of the release, stamped onto the libraries and binaries. + * + * \note + * This does not correspond to the shared library version number, which + * is used to determine binary compatibility. + */ +extern FLAC_API const char *FLAC__VERSION_STRING; + +/** The vendor string inserted by the encoder into the VORBIS_COMMENT block. + * This is a NUL-terminated ASCII string; when inserted into the + * VORBIS_COMMENT the trailing null is stripped. + */ +extern FLAC_API const char *FLAC__VENDOR_STRING; + +/** The byte string representation of the beginning of a FLAC stream. */ +extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */ + +/** The 32-bit integer big-endian representation of the beginning of + * a FLAC stream. + */ +extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */ + +/** The length of the FLAC signature in bits. */ +extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */ + +/** The length of the FLAC signature in bytes. */ +#define FLAC__STREAM_SYNC_LENGTH (4u) + + +/***************************************************************************** + * + * Subframe structures + * + *****************************************************************************/ + +/*****************************************************************************/ + +/** An enumeration of the available entropy coding methods. */ +typedef enum { + FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0, + /**< Residual is coded by partitioning into contexts, each with it's own + * 4-bit Rice parameter. */ + + FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2 = 1 + /**< Residual is coded by partitioning into contexts, each with it's own + * 5-bit Rice parameter. */ +} FLAC__EntropyCodingMethodType; + +/** Maps a FLAC__EntropyCodingMethodType to a C string. + * + * Using a FLAC__EntropyCodingMethodType as the index to this array will + * give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[]; + + +/** Contents of a Rice partitioned residual + */ +typedef struct { + + unsigned *parameters; + /**< The Rice parameters for each context. */ + + unsigned *raw_bits; + /**< Widths for escape-coded partitions. Will be non-zero for escaped + * partitions and zero for unescaped partitions. + */ + + unsigned capacity_by_order; + /**< The capacity of the \a parameters and \a raw_bits arrays + * specified as an order, i.e. the number of array elements + * allocated is 2 ^ \a capacity_by_order. + */ +} FLAC__EntropyCodingMethod_PartitionedRiceContents; + +/** Header for a Rice partitioned residual. (c.f. format specification) + */ +typedef struct { + + unsigned order; + /**< The partition order, i.e. # of contexts = 2 ^ \a order. */ + + const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents; + /**< The context's Rice parameters and/or raw bits. */ + +} FLAC__EntropyCodingMethod_PartitionedRice; + +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN; /**< == 5 (bits) */ +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */ + +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER; +/**< == (1<format specification) + */ +typedef struct { + FLAC__EntropyCodingMethodType type; + union { + FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice; + } data; +} FLAC__EntropyCodingMethod; + +extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */ + +/*****************************************************************************/ + +/** An enumeration of the available subframe types. */ +typedef enum { + FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */ + FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */ + FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */ + FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */ +} FLAC__SubframeType; + +/** Maps a FLAC__SubframeType to a C string. + * + * Using a FLAC__SubframeType as the index to this array will + * give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__SubframeTypeString[]; + + +/** CONSTANT subframe. (c.f. format specification) + */ +typedef struct { + FLAC__int32 value; /**< The constant signal value. */ +} FLAC__Subframe_Constant; + + +/** VERBATIM subframe. (c.f. format specification) + */ +typedef struct { + const FLAC__int32 *data; /**< A pointer to verbatim signal. */ +} FLAC__Subframe_Verbatim; + + +/** FIXED subframe. (c.f. format specification) + */ +typedef struct { + FLAC__EntropyCodingMethod entropy_coding_method; + /**< The residual coding method. */ + + unsigned order; + /**< The polynomial order. */ + + FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER]; + /**< Warmup samples to prime the predictor, length == order. */ + + const FLAC__int32 *residual; + /**< The residual signal, length == (blocksize minus order) samples. */ +} FLAC__Subframe_Fixed; + + +/** LPC subframe. (c.f. format specification) + */ +typedef struct { + FLAC__EntropyCodingMethod entropy_coding_method; + /**< The residual coding method. */ + + unsigned order; + /**< The FIR order. */ + + unsigned qlp_coeff_precision; + /**< Quantized FIR filter coefficient precision in bits. */ + + int quantization_level; + /**< The qlp coeff shift needed. */ + + FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER]; + /**< FIR filter coefficients. */ + + FLAC__int32 warmup[FLAC__MAX_LPC_ORDER]; + /**< Warmup samples to prime the predictor, length == order. */ + + const FLAC__int32 *residual; + /**< The residual signal, length == (blocksize minus order) samples. */ +} FLAC__Subframe_LPC; + +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */ + + +/** FLAC subframe structure. (c.f. format specification) + */ +typedef struct { + FLAC__SubframeType type; + union { + FLAC__Subframe_Constant constant; + FLAC__Subframe_Fixed fixed; + FLAC__Subframe_LPC lpc; + FLAC__Subframe_Verbatim verbatim; + } data; + unsigned wasted_bits; +} FLAC__Subframe; + +/** == 1 (bit) + * + * This used to be a zero-padding bit (hence the name + * FLAC__SUBFRAME_ZERO_PAD_LEN) but is now a reserved bit. It still has a + * mandatory value of \c 0 but in the future may take on the value \c 0 or \c 1 + * to mean something else. + */ +extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */ +extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */ + +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */ +extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */ + +/*****************************************************************************/ + + +/***************************************************************************** + * + * Frame structures + * + *****************************************************************************/ + +/** An enumeration of the available channel assignments. */ +typedef enum { + FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */ + FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */ + FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */ + FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */ +} FLAC__ChannelAssignment; + +/** Maps a FLAC__ChannelAssignment to a C string. + * + * Using a FLAC__ChannelAssignment as the index to this array will + * give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__ChannelAssignmentString[]; + +/** An enumeration of the possible frame numbering methods. */ +typedef enum { + FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */ + FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */ +} FLAC__FrameNumberType; + +/** Maps a FLAC__FrameNumberType to a C string. + * + * Using a FLAC__FrameNumberType as the index to this array will + * give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__FrameNumberTypeString[]; + + +/** FLAC frame header structure. (c.f. format specification) + */ +typedef struct { + unsigned blocksize; + /**< The number of samples per subframe. */ + + unsigned sample_rate; + /**< The sample rate in Hz. */ + + unsigned channels; + /**< The number of channels (== number of subframes). */ + + FLAC__ChannelAssignment channel_assignment; + /**< The channel assignment for the frame. */ + + unsigned bits_per_sample; + /**< The sample resolution. */ + + FLAC__FrameNumberType number_type; + /**< The numbering scheme used for the frame. As a convenience, the + * decoder will always convert a frame number to a sample number because + * the rules are complex. */ + + union { + FLAC__uint32 frame_number; + FLAC__uint64 sample_number; + } number; + /**< The frame number or sample number of first sample in frame; + * use the \a number_type value to determine which to use. */ + + FLAC__uint8 crc; + /**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) + * of the raw frame header bytes, meaning everything before the CRC byte + * including the sync code. + */ +} FLAC__FrameHeader; + +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 1 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN; /**< == 1 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */ +extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */ + + +/** FLAC frame footer structure. (c.f. format specification) + */ +typedef struct { + FLAC__uint16 crc; + /**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with + * 0) of the bytes before the crc, back to and including the frame header + * sync code. + */ +} FLAC__FrameFooter; + +extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */ + + +/** FLAC frame structure. (c.f. format specification) + */ +typedef struct { + FLAC__FrameHeader header; + FLAC__Subframe subframes[FLAC__MAX_CHANNELS]; + FLAC__FrameFooter footer; +} FLAC__Frame; + +/*****************************************************************************/ + + +/***************************************************************************** + * + * Meta-data structures + * + *****************************************************************************/ + +/** An enumeration of the available metadata block types. */ +typedef enum { + + FLAC__METADATA_TYPE_STREAMINFO = 0, + /**< STREAMINFO block */ + + FLAC__METADATA_TYPE_PADDING = 1, + /**< PADDING block */ + + FLAC__METADATA_TYPE_APPLICATION = 2, + /**< APPLICATION block */ + + FLAC__METADATA_TYPE_SEEKTABLE = 3, + /**< SEEKTABLE block */ + + FLAC__METADATA_TYPE_VORBIS_COMMENT = 4, + /**< VORBISCOMMENT block (a.k.a. FLAC tags) */ + + FLAC__METADATA_TYPE_CUESHEET = 5, + /**< CUESHEET block */ + + FLAC__METADATA_TYPE_PICTURE = 6, + /**< PICTURE block */ + + FLAC__METADATA_TYPE_UNDEFINED = 7, + /**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */ + + FLAC__MAX_METADATA_TYPE = FLAC__MAX_METADATA_TYPE_CODE, + /**< No type will ever be greater than this. There is not enough room in the protocol block. */ +} FLAC__MetadataType; + +/** Maps a FLAC__MetadataType to a C string. + * + * Using a FLAC__MetadataType as the index to this array will + * give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__MetadataTypeString[]; + + +/** FLAC STREAMINFO structure. (c.f. format specification) + */ +typedef struct { + unsigned min_blocksize, max_blocksize; + unsigned min_framesize, max_framesize; + unsigned sample_rate; + unsigned channels; + unsigned bits_per_sample; + FLAC__uint64 total_samples; + FLAC__byte md5sum[16]; +} FLAC__StreamMetadata_StreamInfo; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */ + +/** The total stream length of the STREAMINFO block in bytes. */ +#define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u) + +/** FLAC PADDING structure. (c.f. format specification) + */ +typedef struct { + int dummy; + /**< Conceptually this is an empty struct since we don't store the + * padding bytes. Empty structs are not allowed by some C compilers, + * hence the dummy. + */ +} FLAC__StreamMetadata_Padding; + + +/** FLAC APPLICATION structure. (c.f. format specification) + */ +typedef struct { + FLAC__byte id[4]; + FLAC__byte *data; +} FLAC__StreamMetadata_Application; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */ + +/** SeekPoint structure used in SEEKTABLE blocks. (c.f. format specification) + */ +typedef struct { + FLAC__uint64 sample_number; + /**< The sample number of the target frame. */ + + FLAC__uint64 stream_offset; + /**< The offset, in bytes, of the target frame with respect to + * beginning of the first frame. */ + + unsigned frame_samples; + /**< The number of samples in the target frame. */ +} FLAC__StreamMetadata_SeekPoint; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */ + +/** The total stream length of a seek point in bytes. */ +#define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u) + +/** The value used in the \a sample_number field of + * FLAC__StreamMetadataSeekPoint used to indicate a placeholder + * point (== 0xffffffffffffffff). + */ +extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER; + + +/** FLAC SEEKTABLE structure. (c.f. format specification) + * + * \note From the format specification: + * - The seek points must be sorted by ascending sample number. + * - Each seek point's sample number must be the first sample of the + * target frame. + * - Each seek point's sample number must be unique within the table. + * - Existence of a SEEKTABLE block implies a correct setting of + * total_samples in the stream_info block. + * - Behavior is undefined when more than one SEEKTABLE block is + * present in a stream. + */ +typedef struct { + unsigned num_points; + FLAC__StreamMetadata_SeekPoint *points; +} FLAC__StreamMetadata_SeekTable; + + +/** Vorbis comment entry structure used in VORBIS_COMMENT blocks. (c.f. format specification) + * + * For convenience, the APIs maintain a trailing NUL character at the end of + * \a entry which is not counted toward \a length, i.e. + * \code strlen(entry) == length \endcode + */ +typedef struct { + FLAC__uint32 length; + FLAC__byte *entry; +} FLAC__StreamMetadata_VorbisComment_Entry; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */ + + +/** FLAC VORBIS_COMMENT structure. (c.f. format specification) + */ +typedef struct { + FLAC__StreamMetadata_VorbisComment_Entry vendor_string; + FLAC__uint32 num_comments; + FLAC__StreamMetadata_VorbisComment_Entry *comments; +} FLAC__StreamMetadata_VorbisComment; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */ + + +/** FLAC CUESHEET track index structure. (See the + * format specification for + * the full description of each field.) + */ +typedef struct { + FLAC__uint64 offset; + /**< Offset in samples, relative to the track offset, of the index + * point. + */ + + FLAC__byte number; + /**< The index point number. */ +} FLAC__StreamMetadata_CueSheet_Index; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */ + + +/** FLAC CUESHEET track structure. (See the + * format specification for + * the full description of each field.) + */ +typedef struct { + FLAC__uint64 offset; + /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */ + + FLAC__byte number; + /**< The track number. */ + + char isrc[13]; + /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing \c NUL byte */ + + unsigned type:1; + /**< The track type: 0 for audio, 1 for non-audio. */ + + unsigned pre_emphasis:1; + /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */ + + FLAC__byte num_indices; + /**< The number of track index points. */ + + FLAC__StreamMetadata_CueSheet_Index *indices; + /**< NULL if num_indices == 0, else pointer to array of index points. */ + +} FLAC__StreamMetadata_CueSheet_Track; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */ + + +/** FLAC CUESHEET structure. (See the + * format specification + * for the full description of each field.) + */ +typedef struct { + char media_catalog_number[129]; + /**< Media catalog number, in ASCII printable characters 0x20-0x7e. In + * general, the media catalog number may be 0 to 128 bytes long; any + * unused characters should be right-padded with NUL characters. + */ + + FLAC__uint64 lead_in; + /**< The number of lead-in samples. */ + + FLAC__bool is_cd; + /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false. */ + + unsigned num_tracks; + /**< The number of tracks. */ + + FLAC__StreamMetadata_CueSheet_Track *tracks; + /**< NULL if num_tracks == 0, else pointer to array of tracks. */ + +} FLAC__StreamMetadata_CueSheet; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */ + + +/** An enumeration of the PICTURE types (see FLAC__StreamMetadataPicture and id3 v2.4 APIC tag). */ +typedef enum { + FLAC__STREAM_METADATA_PICTURE_TYPE_OTHER = 0, /**< Other */ + FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON_STANDARD = 1, /**< 32x32 pixels 'file icon' (PNG only) */ + FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON = 2, /**< Other file icon */ + FLAC__STREAM_METADATA_PICTURE_TYPE_FRONT_COVER = 3, /**< Cover (front) */ + FLAC__STREAM_METADATA_PICTURE_TYPE_BACK_COVER = 4, /**< Cover (back) */ + FLAC__STREAM_METADATA_PICTURE_TYPE_LEAFLET_PAGE = 5, /**< Leaflet page */ + FLAC__STREAM_METADATA_PICTURE_TYPE_MEDIA = 6, /**< Media (e.g. label side of CD) */ + FLAC__STREAM_METADATA_PICTURE_TYPE_LEAD_ARTIST = 7, /**< Lead artist/lead performer/soloist */ + FLAC__STREAM_METADATA_PICTURE_TYPE_ARTIST = 8, /**< Artist/performer */ + FLAC__STREAM_METADATA_PICTURE_TYPE_CONDUCTOR = 9, /**< Conductor */ + FLAC__STREAM_METADATA_PICTURE_TYPE_BAND = 10, /**< Band/Orchestra */ + FLAC__STREAM_METADATA_PICTURE_TYPE_COMPOSER = 11, /**< Composer */ + FLAC__STREAM_METADATA_PICTURE_TYPE_LYRICIST = 12, /**< Lyricist/text writer */ + FLAC__STREAM_METADATA_PICTURE_TYPE_RECORDING_LOCATION = 13, /**< Recording Location */ + FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_RECORDING = 14, /**< During recording */ + FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_PERFORMANCE = 15, /**< During performance */ + FLAC__STREAM_METADATA_PICTURE_TYPE_VIDEO_SCREEN_CAPTURE = 16, /**< Movie/video screen capture */ + FLAC__STREAM_METADATA_PICTURE_TYPE_FISH = 17, /**< A bright coloured fish */ + FLAC__STREAM_METADATA_PICTURE_TYPE_ILLUSTRATION = 18, /**< Illustration */ + FLAC__STREAM_METADATA_PICTURE_TYPE_BAND_LOGOTYPE = 19, /**< Band/artist logotype */ + FLAC__STREAM_METADATA_PICTURE_TYPE_PUBLISHER_LOGOTYPE = 20, /**< Publisher/Studio logotype */ + FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED +} FLAC__StreamMetadata_Picture_Type; + +/** Maps a FLAC__StreamMetadata_Picture_Type to a C string. + * + * Using a FLAC__StreamMetadata_Picture_Type as the index to this array + * will give the string equivalent. The contents should not be + * modified. + */ +extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[]; + +/** FLAC PICTURE structure. (See the + * format specification + * for the full description of each field.) + */ +typedef struct { + FLAC__StreamMetadata_Picture_Type type; + /**< The kind of picture stored. */ + + char *mime_type; + /**< Picture data's MIME type, in ASCII printable characters + * 0x20-0x7e, NUL terminated. For best compatibility with players, + * use picture data of MIME type \c image/jpeg or \c image/png. A + * MIME type of '-->' is also allowed, in which case the picture + * data should be a complete URL. In file storage, the MIME type is + * stored as a 32-bit length followed by the ASCII string with no NUL + * terminator, but is converted to a plain C string in this structure + * for convenience. + */ + + FLAC__byte *description; + /**< Picture's description in UTF-8, NUL terminated. In file storage, + * the description is stored as a 32-bit length followed by the UTF-8 + * string with no NUL terminator, but is converted to a plain C string + * in this structure for convenience. + */ + + FLAC__uint32 width; + /**< Picture's width in pixels. */ + + FLAC__uint32 height; + /**< Picture's height in pixels. */ + + FLAC__uint32 depth; + /**< Picture's color depth in bits-per-pixel. */ + + FLAC__uint32 colors; + /**< For indexed palettes (like GIF), picture's number of colors (the + * number of palette entries), or \c 0 for non-indexed (i.e. 2^depth). + */ + + FLAC__uint32 data_length; + /**< Length of binary picture data in bytes. */ + + FLAC__byte *data; + /**< Binary picture data. */ + +} FLAC__StreamMetadata_Picture; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN; /**< == 32 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN; /**< == 32 (bits) */ + + +/** Structure that is used when a metadata block of unknown type is loaded. + * The contents are opaque. The structure is used only internally to + * correctly handle unknown metadata. + */ +typedef struct { + FLAC__byte *data; +} FLAC__StreamMetadata_Unknown; + + +/** FLAC metadata block structure. (c.f. format specification) + */ +typedef struct { + FLAC__MetadataType type; + /**< The type of the metadata block; used determine which member of the + * \a data union to dereference. If type >= FLAC__METADATA_TYPE_UNDEFINED + * then \a data.unknown must be used. */ + + FLAC__bool is_last; + /**< \c true if this metadata block is the last, else \a false */ + + unsigned length; + /**< Length, in bytes, of the block data as it appears in the stream. */ + + union { + FLAC__StreamMetadata_StreamInfo stream_info; + FLAC__StreamMetadata_Padding padding; + FLAC__StreamMetadata_Application application; + FLAC__StreamMetadata_SeekTable seek_table; + FLAC__StreamMetadata_VorbisComment vorbis_comment; + FLAC__StreamMetadata_CueSheet cue_sheet; + FLAC__StreamMetadata_Picture picture; + FLAC__StreamMetadata_Unknown unknown; + } data; + /**< Polymorphic block data; use the \a type value to determine which + * to use. */ +} FLAC__StreamMetadata; + +extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */ +extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */ + +/** The total stream length of a metadata block header in bytes. */ +#define FLAC__STREAM_METADATA_HEADER_LENGTH (4u) + +/*****************************************************************************/ + + +/***************************************************************************** + * + * Utility functions + * + *****************************************************************************/ + +/** Tests that a sample rate is valid for FLAC. + * + * \param sample_rate The sample rate to test for compliance. + * \retval FLAC__bool + * \c true if the given sample rate conforms to the specification, else + * \c false. + */ +FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate); + +/** Tests that a blocksize at the given sample rate is valid for the FLAC + * subset. + * + * \param blocksize The blocksize to test for compliance. + * \param sample_rate The sample rate is needed, since the valid subset + * blocksize depends on the sample rate. + * \retval FLAC__bool + * \c true if the given blocksize conforms to the specification for the + * subset at the given sample rate, else \c false. + */ +FLAC_API FLAC__bool FLAC__format_blocksize_is_subset(unsigned blocksize, unsigned sample_rate); + +/** Tests that a sample rate is valid for the FLAC subset. The subset rules + * for valid sample rates are slightly more complex since the rate has to + * be expressible completely in the frame header. + * + * \param sample_rate The sample rate to test for compliance. + * \retval FLAC__bool + * \c true if the given sample rate conforms to the specification for the + * subset, else \c false. + */ +FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate); + +/** Check a Vorbis comment entry name to see if it conforms to the Vorbis + * comment specification. + * + * Vorbis comment names must be composed only of characters from + * [0x20-0x3C,0x3E-0x7D]. + * + * \param name A NUL-terminated string to be checked. + * \assert + * \code name != NULL \endcode + * \retval FLAC__bool + * \c false if entry name is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name); + +/** Check a Vorbis comment entry value to see if it conforms to the Vorbis + * comment specification. + * + * Vorbis comment values must be valid UTF-8 sequences. + * + * \param value A string to be checked. + * \param length A the length of \a value in bytes. May be + * \c (unsigned)(-1) to indicate that \a value is a plain + * UTF-8 NUL-terminated string. + * \assert + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if entry name is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length); + +/** Check a Vorbis comment entry to see if it conforms to the Vorbis + * comment specification. + * + * Vorbis comment entries must be of the form 'name=value', and 'name' and + * 'value' must be legal according to + * FLAC__format_vorbiscomment_entry_name_is_legal() and + * FLAC__format_vorbiscomment_entry_value_is_legal() respectively. + * + * \param entry An entry to be checked. + * \param length The length of \a entry in bytes. + * \assert + * \code value != NULL \endcode + * \retval FLAC__bool + * \c false if entry name is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length); + +/** Check a seek table to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * seek table. + * + * \param seek_table A pointer to a seek table to be checked. + * \assert + * \code seek_table != NULL \endcode + * \retval FLAC__bool + * \c false if seek table is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table); + +/** Sort a seek table's seek points according to the format specification. + * This includes a "unique-ification" step to remove duplicates, i.e. + * seek points with identical \a sample_number values. Duplicate seek + * points are converted into placeholder points and sorted to the end of + * the table. + * + * \param seek_table A pointer to a seek table to be sorted. + * \assert + * \code seek_table != NULL \endcode + * \retval unsigned + * The number of duplicate seek points converted into placeholders. + */ +FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table); + +/** Check a cue sheet to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * cue sheet. + * + * \param cue_sheet A pointer to an existing cue sheet to be checked. + * \param check_cd_da_subset If \c true, check CUESHEET against more + * stringent requirements for a CD-DA (audio) disc. + * \param violation Address of a pointer to a string. If there is a + * violation, a pointer to a string explanation of the + * violation will be returned here. \a violation may be + * \c NULL if you don't need the returned string. Do not + * free the returned string; it will always point to static + * data. + * \assert + * \code cue_sheet != NULL \endcode + * \retval FLAC__bool + * \c false if cue sheet is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation); + +/** Check picture data to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * PICTURE block. + * + * \param picture A pointer to existing picture data to be checked. + * \param violation Address of a pointer to a string. If there is a + * violation, a pointer to a string explanation of the + * violation will be returned here. \a violation may be + * \c NULL if you don't need the returned string. Do not + * free the returned string; it will always point to static + * data. + * \assert + * \code picture != NULL \endcode + * \retval FLAC__bool + * \c false if picture data is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation); + +/* \} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/flac/include/FLAC/metadata.h b/flac/include/FLAC/metadata.h new file mode 100644 index 00000000..89515329 --- /dev/null +++ b/flac/include/FLAC/metadata.h @@ -0,0 +1,2182 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2001-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__METADATA_H +#define FLAC__METADATA_H + +#include /* for off_t */ +#include "export.h" +#include "callback.h" +#include "format.h" + +/* -------------------------------------------------------------------- + (For an example of how all these routines are used, see the source + code for the unit tests in src/test_libFLAC/metadata_*.c, or + metaflac in src/metaflac/) + ------------------------------------------------------------------*/ + +/** \file include/FLAC/metadata.h + * + * \brief + * This module provides functions for creating and manipulating FLAC + * metadata blocks in memory, and three progressively more powerful + * interfaces for traversing and editing metadata in FLAC files. + * + * See the detailed documentation for each interface in the + * \link flac_metadata metadata \endlink module. + */ + +/** \defgroup flac_metadata FLAC/metadata.h: metadata interfaces + * \ingroup flac + * + * \brief + * This module provides functions for creating and manipulating FLAC + * metadata blocks in memory, and three progressively more powerful + * interfaces for traversing and editing metadata in native FLAC files. + * Note that currently only the Chain interface (level 2) supports Ogg + * FLAC files, and it is read-only i.e. no writing back changed + * metadata to file. + * + * There are three metadata interfaces of increasing complexity: + * + * Level 0: + * Read-only access to the STREAMINFO, VORBIS_COMMENT, CUESHEET, and + * PICTURE blocks. + * + * Level 1: + * Read-write access to all metadata blocks. This level is write- + * efficient in most cases (more on this below), and uses less memory + * than level 2. + * + * Level 2: + * Read-write access to all metadata blocks. This level is write- + * efficient in all cases, but uses more memory since all metadata for + * the whole file is read into memory and manipulated before writing + * out again. + * + * What do we mean by efficient? Since FLAC metadata appears at the + * beginning of the file, when writing metadata back to a FLAC file + * it is possible to grow or shrink the metadata such that the entire + * file must be rewritten. However, if the size remains the same during + * changes or PADDING blocks are utilized, only the metadata needs to be + * overwritten, which is much faster. + * + * Efficient means the whole file is rewritten at most one time, and only + * when necessary. Level 1 is not efficient only in the case that you + * cause more than one metadata block to grow or shrink beyond what can + * be accomodated by padding. In this case you should probably use level + * 2, which allows you to edit all the metadata for a file in memory and + * write it out all at once. + * + * All levels know how to skip over and not disturb an ID3v2 tag at the + * front of the file. + * + * All levels access files via their filenames. In addition, level 2 + * has additional alternative read and write functions that take an I/O + * handle and callbacks, for situations where access by filename is not + * possible. + * + * In addition to the three interfaces, this module defines functions for + * creating and manipulating various metadata objects in memory. As we see + * from the Format module, FLAC metadata blocks in memory are very primitive + * structures for storing information in an efficient way. Reading + * information from the structures is easy but creating or modifying them + * directly is more complex. The metadata object routines here facilitate + * this by taking care of the consistency and memory management drudgery. + * + * Unless you will be using the level 1 or 2 interfaces to modify existing + * metadata however, you will not probably not need these. + * + * From a dependency standpoint, none of the encoders or decoders require + * the metadata module. This is so that embedded users can strip out the + * metadata module from libFLAC to reduce the size and complexity. + */ + +#ifdef __cplusplus +extern "C" { +#endif + + +/** \defgroup flac_metadata_level0 FLAC/metadata.h: metadata level 0 interface + * \ingroup flac_metadata + * + * \brief + * The level 0 interface consists of individual routines to read the + * STREAMINFO, VORBIS_COMMENT, CUESHEET, and PICTURE blocks, requiring + * only a filename. + * + * They try to skip any ID3v2 tag at the head of the file. + * + * \{ + */ + +/** Read the STREAMINFO metadata block of the given FLAC file. This function + * will try to skip any ID3v2 tag at the head of the file. + * + * \param filename The path to the FLAC file to read. + * \param streaminfo A pointer to space for the STREAMINFO block. Since + * FLAC__StreamMetadata is a simple structure with no + * memory allocation involved, you pass the address of + * an existing structure. It need not be initialized. + * \assert + * \code filename != NULL \endcode + * \code streaminfo != NULL \endcode + * \retval FLAC__bool + * \c true if a valid STREAMINFO block was read from \a filename. Returns + * \c false if there was a memory allocation error, a file decoder error, + * or the file contained no STREAMINFO block. (A memory allocation error + * is possible because this function must set up a file decoder.) + */ +FLAC_API FLAC__bool FLAC__metadata_get_streaminfo(const char *filename, FLAC__StreamMetadata *streaminfo); + +/** Read the VORBIS_COMMENT metadata block of the given FLAC file. This + * function will try to skip any ID3v2 tag at the head of the file. + * + * \param filename The path to the FLAC file to read. + * \param tags The address where the returned pointer will be + * stored. The \a tags object must be deleted by + * the caller using FLAC__metadata_object_delete(). + * \assert + * \code filename != NULL \endcode + * \code tags != NULL \endcode + * \retval FLAC__bool + * \c true if a valid VORBIS_COMMENT block was read from \a filename, + * and \a *tags will be set to the address of the metadata structure. + * Returns \c false if there was a memory allocation error, a file + * decoder error, or the file contained no VORBIS_COMMENT block, and + * \a *tags will be set to \c NULL. + */ +FLAC_API FLAC__bool FLAC__metadata_get_tags(const char *filename, FLAC__StreamMetadata **tags); + +/** Read the CUESHEET metadata block of the given FLAC file. This + * function will try to skip any ID3v2 tag at the head of the file. + * + * \param filename The path to the FLAC file to read. + * \param cuesheet The address where the returned pointer will be + * stored. The \a cuesheet object must be deleted by + * the caller using FLAC__metadata_object_delete(). + * \assert + * \code filename != NULL \endcode + * \code cuesheet != NULL \endcode + * \retval FLAC__bool + * \c true if a valid CUESHEET block was read from \a filename, + * and \a *cuesheet will be set to the address of the metadata + * structure. Returns \c false if there was a memory allocation + * error, a file decoder error, or the file contained no CUESHEET + * block, and \a *cuesheet will be set to \c NULL. + */ +FLAC_API FLAC__bool FLAC__metadata_get_cuesheet(const char *filename, FLAC__StreamMetadata **cuesheet); + +/** Read a PICTURE metadata block of the given FLAC file. This + * function will try to skip any ID3v2 tag at the head of the file. + * Since there can be more than one PICTURE block in a file, this + * function takes a number of parameters that act as constraints to + * the search. The PICTURE block with the largest area matching all + * the constraints will be returned, or \a *picture will be set to + * \c NULL if there was no such block. + * + * \param filename The path to the FLAC file to read. + * \param picture The address where the returned pointer will be + * stored. The \a picture object must be deleted by + * the caller using FLAC__metadata_object_delete(). + * \param type The desired picture type. Use \c -1 to mean + * "any type". + * \param mime_type The desired MIME type, e.g. "image/jpeg". The + * string will be matched exactly. Use \c NULL to + * mean "any MIME type". + * \param description The desired description. The string will be + * matched exactly. Use \c NULL to mean "any + * description". + * \param max_width The maximum width in pixels desired. Use + * \c (unsigned)(-1) to mean "any width". + * \param max_height The maximum height in pixels desired. Use + * \c (unsigned)(-1) to mean "any height". + * \param max_depth The maximum color depth in bits-per-pixel desired. + * Use \c (unsigned)(-1) to mean "any depth". + * \param max_colors The maximum number of colors desired. Use + * \c (unsigned)(-1) to mean "any number of colors". + * \assert + * \code filename != NULL \endcode + * \code picture != NULL \endcode + * \retval FLAC__bool + * \c true if a valid PICTURE block was read from \a filename, + * and \a *picture will be set to the address of the metadata + * structure. Returns \c false if there was a memory allocation + * error, a file decoder error, or the file contained no PICTURE + * block, and \a *picture will be set to \c NULL. + */ +FLAC_API FLAC__bool FLAC__metadata_get_picture(const char *filename, FLAC__StreamMetadata **picture, FLAC__StreamMetadata_Picture_Type type, const char *mime_type, const FLAC__byte *description, unsigned max_width, unsigned max_height, unsigned max_depth, unsigned max_colors); + +/* \} */ + + +/** \defgroup flac_metadata_level1 FLAC/metadata.h: metadata level 1 interface + * \ingroup flac_metadata + * + * \brief + * The level 1 interface provides read-write access to FLAC file metadata and + * operates directly on the FLAC file. + * + * The general usage of this interface is: + * + * - Create an iterator using FLAC__metadata_simple_iterator_new() + * - Attach it to a file using FLAC__metadata_simple_iterator_init() and check + * the exit code. Call FLAC__metadata_simple_iterator_is_writable() to + * see if the file is writable, or only read access is allowed. + * - Use FLAC__metadata_simple_iterator_next() and + * FLAC__metadata_simple_iterator_prev() to traverse the blocks. + * This is does not read the actual blocks themselves. + * FLAC__metadata_simple_iterator_next() is relatively fast. + * FLAC__metadata_simple_iterator_prev() is slower since it needs to search + * forward from the front of the file. + * - Use FLAC__metadata_simple_iterator_get_block_type() or + * FLAC__metadata_simple_iterator_get_block() to access the actual data at + * the current iterator position. The returned object is yours to modify + * and free. + * - Use FLAC__metadata_simple_iterator_set_block() to write a modified block + * back. You must have write permission to the original file. Make sure to + * read the whole comment to FLAC__metadata_simple_iterator_set_block() + * below. + * - Use FLAC__metadata_simple_iterator_insert_block_after() to add new blocks. + * Use the object creation functions from + * \link flac_metadata_object here \endlink to generate new objects. + * - Use FLAC__metadata_simple_iterator_delete_block() to remove the block + * currently referred to by the iterator, or replace it with padding. + * - Destroy the iterator with FLAC__metadata_simple_iterator_delete() when + * finished. + * + * \note + * The FLAC file remains open the whole time between + * FLAC__metadata_simple_iterator_init() and + * FLAC__metadata_simple_iterator_delete(), so make sure you are not altering + * the file during this time. + * + * \note + * Do not modify the \a is_last, \a length, or \a type fields of returned + * FLAC__StreamMetadata objects. These are managed automatically. + * + * \note + * If any of the modification functions + * (FLAC__metadata_simple_iterator_set_block(), + * FLAC__metadata_simple_iterator_delete_block(), + * FLAC__metadata_simple_iterator_insert_block_after(), etc.) return \c false, + * you should delete the iterator as it may no longer be valid. + * + * \{ + */ + +struct FLAC__Metadata_SimpleIterator; +/** The opaque structure definition for the level 1 iterator type. + * See the + * \link flac_metadata_level1 metadata level 1 module \endlink + * for a detailed description. + */ +typedef struct FLAC__Metadata_SimpleIterator FLAC__Metadata_SimpleIterator; + +/** Status type for FLAC__Metadata_SimpleIterator. + * + * The iterator's current status can be obtained by calling FLAC__metadata_simple_iterator_status(). + */ +typedef enum { + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK = 0, + /**< The iterator is in the normal OK state */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, + /**< The data passed into a function violated the function's usage criteria */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ERROR_OPENING_FILE, + /**< The iterator could not open the target file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_A_FLAC_FILE, + /**< The iterator could not find the FLAC signature at the start of the file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_NOT_WRITABLE, + /**< The iterator tried to write to a file that was not writable */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_BAD_METADATA, + /**< The iterator encountered input that does not conform to the FLAC metadata specification */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR, + /**< The iterator encountered an error while reading the FLAC file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, + /**< The iterator encountered an error while seeking in the FLAC file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_WRITE_ERROR, + /**< The iterator encountered an error while writing the FLAC file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_RENAME_ERROR, + /**< The iterator encountered an error renaming the FLAC file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_UNLINK_ERROR, + /**< The iterator encountered an error removing the temporary file */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_MEMORY_ALLOCATION_ERROR, + /**< Memory allocation failed */ + + FLAC__METADATA_SIMPLE_ITERATOR_STATUS_INTERNAL_ERROR + /**< The caller violated an assertion or an unexpected error occurred */ + +} FLAC__Metadata_SimpleIteratorStatus; + +/** Maps a FLAC__Metadata_SimpleIteratorStatus to a C string. + * + * Using a FLAC__Metadata_SimpleIteratorStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__Metadata_SimpleIteratorStatusString[]; + + +/** Create a new iterator instance. + * + * \retval FLAC__Metadata_SimpleIterator* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__Metadata_SimpleIterator *FLAC__metadata_simple_iterator_new(void); + +/** Free an iterator instance. Deletes the object pointed to by \a iterator. + * + * \param iterator A pointer to an existing iterator. + * \assert + * \code iterator != NULL \endcode + */ +FLAC_API void FLAC__metadata_simple_iterator_delete(FLAC__Metadata_SimpleIterator *iterator); + +/** Get the current status of the iterator. Call this after a function + * returns \c false to get the reason for the error. Also resets the status + * to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK. + * + * \param iterator A pointer to an existing iterator. + * \assert + * \code iterator != NULL \endcode + * \retval FLAC__Metadata_SimpleIteratorStatus + * The current status of the iterator. + */ +FLAC_API FLAC__Metadata_SimpleIteratorStatus FLAC__metadata_simple_iterator_status(FLAC__Metadata_SimpleIterator *iterator); + +/** Initialize the iterator to point to the first metadata block in the + * given FLAC file. + * + * \param iterator A pointer to an existing iterator. + * \param filename The path to the FLAC file. + * \param read_only If \c true, the FLAC file will be opened + * in read-only mode; if \c false, the FLAC + * file will be opened for edit even if no + * edits are performed. + * \param preserve_file_stats If \c true, the owner and modification + * time will be preserved even if the FLAC + * file is written to. + * \assert + * \code iterator != NULL \endcode + * \code filename != NULL \endcode + * \retval FLAC__bool + * \c false if a memory allocation error occurs, the file can't be + * opened, or another error occurs, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_init(FLAC__Metadata_SimpleIterator *iterator, const char *filename, FLAC__bool read_only, FLAC__bool preserve_file_stats); + +/** Returns \c true if the FLAC file is writable. If \c false, calls to + * FLAC__metadata_simple_iterator_set_block() and + * FLAC__metadata_simple_iterator_insert_block_after() will fail. + * + * \param iterator A pointer to an existing iterator. + * \assert + * \code iterator != NULL \endcode + * \retval FLAC__bool + * See above. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_writable(const FLAC__Metadata_SimpleIterator *iterator); + +/** Moves the iterator forward one metadata block, returning \c false if + * already at the end. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__bool + * \c false if already at the last metadata block of the chain, else + * \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_next(FLAC__Metadata_SimpleIterator *iterator); + +/** Moves the iterator backward one metadata block, returning \c false if + * already at the beginning. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__bool + * \c false if already at the first metadata block of the chain, else + * \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_prev(FLAC__Metadata_SimpleIterator *iterator); + +/** Returns a flag telling if the current metadata block is the last. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__bool + * \c true if the current metadata block is the last in the file, + * else \c false. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_is_last(const FLAC__Metadata_SimpleIterator *iterator); + +/** Get the offset of the metadata block at the current position. This + * avoids reading the actual block data which can save time for large + * blocks. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval off_t + * The offset of the metadata block at the current iterator position. + * This is the byte offset relative to the beginning of the file of + * the current metadata block's header. + */ +FLAC_API off_t FLAC__metadata_simple_iterator_get_block_offset(const FLAC__Metadata_SimpleIterator *iterator); + +/** Get the type of the metadata block at the current position. This + * avoids reading the actual block data which can save time for large + * blocks. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__MetadataType + * The type of the metadata block at the current iterator position. + */ +FLAC_API FLAC__MetadataType FLAC__metadata_simple_iterator_get_block_type(const FLAC__Metadata_SimpleIterator *iterator); + +/** Get the length of the metadata block at the current position. This + * avoids reading the actual block data which can save time for large + * blocks. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval unsigned + * The length of the metadata block at the current iterator position. + * The is same length as that in the + * metadata block header, + * i.e. the length of the metadata body that follows the header. + */ +FLAC_API unsigned FLAC__metadata_simple_iterator_get_block_length(const FLAC__Metadata_SimpleIterator *iterator); + +/** Get the application ID of the \c APPLICATION block at the current + * position. This avoids reading the actual block data which can save + * time for large blocks. + * + * \param iterator A pointer to an existing initialized iterator. + * \param id A pointer to a buffer of at least \c 4 bytes where + * the ID will be stored. + * \assert + * \code iterator != NULL \endcode + * \code id != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__bool + * \c true if the ID was successfully read, else \c false, in which + * case you should check FLAC__metadata_simple_iterator_status() to + * find out why. If the status is + * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_ILLEGAL_INPUT, then the + * current metadata block is not an \c APPLICATION block. Otherwise + * if the status is + * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_READ_ERROR or + * \c FLAC__METADATA_SIMPLE_ITERATOR_STATUS_SEEK_ERROR, an I/O error + * occurred and the iterator can no longer be used. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_get_application_id(FLAC__Metadata_SimpleIterator *iterator, FLAC__byte *id); + +/** Get the metadata block at the current position. You can modify the + * block but must use FLAC__metadata_simple_iterator_set_block() to + * write it back to the FLAC file. + * + * You must call FLAC__metadata_object_delete() on the returned object + * when you are finished with it. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__StreamMetadata* + * The current metadata block, or \c NULL if there was a memory + * allocation error. + */ +FLAC_API FLAC__StreamMetadata *FLAC__metadata_simple_iterator_get_block(FLAC__Metadata_SimpleIterator *iterator); + +/** Write a block back to the FLAC file. This function tries to be + * as efficient as possible; how the block is actually written is + * shown by the following: + * + * Existing block is a STREAMINFO block and the new block is a + * STREAMINFO block: the new block is written in place. Make sure + * you know what you're doing when changing the values of a + * STREAMINFO block. + * + * Existing block is a STREAMINFO block and the new block is a + * not a STREAMINFO block: this is an error since the first block + * must be a STREAMINFO block. Returns \c false without altering the + * file. + * + * Existing block is not a STREAMINFO block and the new block is a + * STREAMINFO block: this is an error since there may be only one + * STREAMINFO block. Returns \c false without altering the file. + * + * Existing block and new block are the same length: the existing + * block will be replaced by the new block, written in place. + * + * Existing block is longer than new block: if use_padding is \c true, + * the existing block will be overwritten in place with the new + * block followed by a PADDING block, if possible, to make the total + * size the same as the existing block. Remember that a padding + * block requires at least four bytes so if the difference in size + * between the new block and existing block is less than that, the + * entire file will have to be rewritten, using the new block's + * exact size. If use_padding is \c false, the entire file will be + * rewritten, replacing the existing block by the new block. + * + * Existing block is shorter than new block: if use_padding is \c true, + * the function will try and expand the new block into the following + * PADDING block, if it exists and doing so won't shrink the PADDING + * block to less than 4 bytes. If there is no following PADDING + * block, or it will shrink to less than 4 bytes, or use_padding is + * \c false, the entire file is rewritten, replacing the existing block + * with the new block. Note that in this case any following PADDING + * block is preserved as is. + * + * After writing the block, the iterator will remain in the same + * place, i.e. pointing to the new block. + * + * \param iterator A pointer to an existing initialized iterator. + * \param block The block to set. + * \param use_padding See above. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \code block != NULL \endcode + * \retval FLAC__bool + * \c true if successful, else \c false. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_set_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); + +/** This is similar to FLAC__metadata_simple_iterator_set_block() + * except that instead of writing over an existing block, it appends + * a block after the existing block. \a use_padding is again used to + * tell the function to try an expand into following padding in an + * attempt to avoid rewriting the entire file. + * + * This function will fail and return \c false if given a STREAMINFO + * block. + * + * After writing the block, the iterator will be pointing to the + * new block. + * + * \param iterator A pointer to an existing initialized iterator. + * \param block The block to set. + * \param use_padding See above. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \code block != NULL \endcode + * \retval FLAC__bool + * \c true if successful, else \c false. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_insert_block_after(FLAC__Metadata_SimpleIterator *iterator, FLAC__StreamMetadata *block, FLAC__bool use_padding); + +/** Deletes the block at the current position. This will cause the + * entire FLAC file to be rewritten, unless \a use_padding is \c true, + * in which case the block will be replaced by an equal-sized PADDING + * block. The iterator will be left pointing to the block before the + * one just deleted. + * + * You may not delete the STREAMINFO block. + * + * \param iterator A pointer to an existing initialized iterator. + * \param use_padding See above. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_simple_iterator_init() + * \retval FLAC__bool + * \c true if successful, else \c false. + */ +FLAC_API FLAC__bool FLAC__metadata_simple_iterator_delete_block(FLAC__Metadata_SimpleIterator *iterator, FLAC__bool use_padding); + +/* \} */ + + +/** \defgroup flac_metadata_level2 FLAC/metadata.h: metadata level 2 interface + * \ingroup flac_metadata + * + * \brief + * The level 2 interface provides read-write access to FLAC file metadata; + * all metadata is read into memory, operated on in memory, and then written + * to file, which is more efficient than level 1 when editing multiple blocks. + * + * Currently Ogg FLAC is supported for read only, via + * FLAC__metadata_chain_read_ogg() but a subsequent + * FLAC__metadata_chain_write() will fail. + * + * The general usage of this interface is: + * + * - Create a new chain using FLAC__metadata_chain_new(). A chain is a + * linked list of FLAC metadata blocks. + * - Read all metadata into the the chain from a FLAC file using + * FLAC__metadata_chain_read() or FLAC__metadata_chain_read_ogg() and + * check the status. + * - Optionally, consolidate the padding using + * FLAC__metadata_chain_merge_padding() or + * FLAC__metadata_chain_sort_padding(). + * - Create a new iterator using FLAC__metadata_iterator_new() + * - Initialize the iterator to point to the first element in the chain + * using FLAC__metadata_iterator_init() + * - Traverse the chain using FLAC__metadata_iterator_next and + * FLAC__metadata_iterator_prev(). + * - Get a block for reading or modification using + * FLAC__metadata_iterator_get_block(). The pointer to the object + * inside the chain is returned, so the block is yours to modify. + * Changes will be reflected in the FLAC file when you write the + * chain. You can also add and delete blocks (see functions below). + * - When done, write out the chain using FLAC__metadata_chain_write(). + * Make sure to read the whole comment to the function below. + * - Delete the chain using FLAC__metadata_chain_delete(). + * + * \note + * Even though the FLAC file is not open while the chain is being + * manipulated, you must not alter the file externally during + * this time. The chain assumes the FLAC file will not change + * between the time of FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg() + * and FLAC__metadata_chain_write(). + * + * \note + * Do not modify the is_last, length, or type fields of returned + * FLAC__StreamMetadata objects. These are managed automatically. + * + * \note + * The metadata objects returned by FLAC__metadata_iterator_get_block() + * are owned by the chain; do not FLAC__metadata_object_delete() them. + * In the same way, blocks passed to FLAC__metadata_iterator_set_block() + * become owned by the chain and they will be deleted when the chain is + * deleted. + * + * \{ + */ + +struct FLAC__Metadata_Chain; +/** The opaque structure definition for the level 2 chain type. + */ +typedef struct FLAC__Metadata_Chain FLAC__Metadata_Chain; + +struct FLAC__Metadata_Iterator; +/** The opaque structure definition for the level 2 iterator type. + */ +typedef struct FLAC__Metadata_Iterator FLAC__Metadata_Iterator; + +typedef enum { + FLAC__METADATA_CHAIN_STATUS_OK = 0, + /**< The chain is in the normal OK state */ + + FLAC__METADATA_CHAIN_STATUS_ILLEGAL_INPUT, + /**< The data passed into a function violated the function's usage criteria */ + + FLAC__METADATA_CHAIN_STATUS_ERROR_OPENING_FILE, + /**< The chain could not open the target file */ + + FLAC__METADATA_CHAIN_STATUS_NOT_A_FLAC_FILE, + /**< The chain could not find the FLAC signature at the start of the file */ + + FLAC__METADATA_CHAIN_STATUS_NOT_WRITABLE, + /**< The chain tried to write to a file that was not writable */ + + FLAC__METADATA_CHAIN_STATUS_BAD_METADATA, + /**< The chain encountered input that does not conform to the FLAC metadata specification */ + + FLAC__METADATA_CHAIN_STATUS_READ_ERROR, + /**< The chain encountered an error while reading the FLAC file */ + + FLAC__METADATA_CHAIN_STATUS_SEEK_ERROR, + /**< The chain encountered an error while seeking in the FLAC file */ + + FLAC__METADATA_CHAIN_STATUS_WRITE_ERROR, + /**< The chain encountered an error while writing the FLAC file */ + + FLAC__METADATA_CHAIN_STATUS_RENAME_ERROR, + /**< The chain encountered an error renaming the FLAC file */ + + FLAC__METADATA_CHAIN_STATUS_UNLINK_ERROR, + /**< The chain encountered an error removing the temporary file */ + + FLAC__METADATA_CHAIN_STATUS_MEMORY_ALLOCATION_ERROR, + /**< Memory allocation failed */ + + FLAC__METADATA_CHAIN_STATUS_INTERNAL_ERROR, + /**< The caller violated an assertion or an unexpected error occurred */ + + FLAC__METADATA_CHAIN_STATUS_INVALID_CALLBACKS, + /**< One or more of the required callbacks was NULL */ + + FLAC__METADATA_CHAIN_STATUS_READ_WRITE_MISMATCH, + /**< FLAC__metadata_chain_write() was called on a chain read by + * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), + * or + * FLAC__metadata_chain_write_with_callbacks()/FLAC__metadata_chain_write_with_callbacks_and_tempfile() + * was called on a chain read by + * FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). + * Matching read/write methods must always be used. */ + + FLAC__METADATA_CHAIN_STATUS_WRONG_WRITE_CALL + /**< FLAC__metadata_chain_write_with_callbacks() was called when the + * chain write requires a tempfile; use + * FLAC__metadata_chain_write_with_callbacks_and_tempfile() instead. + * Or, FLAC__metadata_chain_write_with_callbacks_and_tempfile() was + * called when the chain write does not require a tempfile; use + * FLAC__metadata_chain_write_with_callbacks() instead. + * Always check FLAC__metadata_chain_check_if_tempfile_needed() + * before writing via callbacks. */ + +} FLAC__Metadata_ChainStatus; + +/** Maps a FLAC__Metadata_ChainStatus to a C string. + * + * Using a FLAC__Metadata_ChainStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__Metadata_ChainStatusString[]; + +/*********** FLAC__Metadata_Chain ***********/ + +/** Create a new chain instance. + * + * \retval FLAC__Metadata_Chain* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__Metadata_Chain *FLAC__metadata_chain_new(void); + +/** Free a chain instance. Deletes the object pointed to by \a chain. + * + * \param chain A pointer to an existing chain. + * \assert + * \code chain != NULL \endcode + */ +FLAC_API void FLAC__metadata_chain_delete(FLAC__Metadata_Chain *chain); + +/** Get the current status of the chain. Call this after a function + * returns \c false to get the reason for the error. Also resets the + * status to FLAC__METADATA_CHAIN_STATUS_OK. + * + * \param chain A pointer to an existing chain. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__Metadata_ChainStatus + * The current status of the chain. + */ +FLAC_API FLAC__Metadata_ChainStatus FLAC__metadata_chain_status(FLAC__Metadata_Chain *chain); + +/** Read all metadata from a FLAC file into the chain. + * + * \param chain A pointer to an existing chain. + * \param filename The path to the FLAC file to read. + * \assert + * \code chain != NULL \endcode + * \code filename != NULL \endcode + * \retval FLAC__bool + * \c true if a valid list of metadata blocks was read from + * \a filename, else \c false. On failure, check the status with + * FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_read(FLAC__Metadata_Chain *chain, const char *filename); + +/** Read all metadata from an Ogg FLAC file into the chain. + * + * \note Ogg FLAC metadata data writing is not supported yet and + * FLAC__metadata_chain_write() will fail. + * + * \param chain A pointer to an existing chain. + * \param filename The path to the Ogg FLAC file to read. + * \assert + * \code chain != NULL \endcode + * \code filename != NULL \endcode + * \retval FLAC__bool + * \c true if a valid list of metadata blocks was read from + * \a filename, else \c false. On failure, check the status with + * FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg(FLAC__Metadata_Chain *chain, const char *filename); + +/** Read all metadata from a FLAC stream into the chain via I/O callbacks. + * + * The \a handle need only be open for reading, but must be seekable. + * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" + * for Windows). + * + * \param chain A pointer to an existing chain. + * \param handle The I/O handle of the FLAC stream to read. The + * handle will NOT be closed after the metadata is read; + * that is the duty of the caller. + * \param callbacks + * A set of callbacks to use for I/O. The mandatory + * callbacks are \a read, \a seek, and \a tell. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if a valid list of metadata blocks was read from + * \a handle, else \c false. On failure, check the status with + * FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_read_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); + +/** Read all metadata from an Ogg FLAC stream into the chain via I/O callbacks. + * + * The \a handle need only be open for reading, but must be seekable. + * The equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" + * for Windows). + * + * \note Ogg FLAC metadata data writing is not supported yet and + * FLAC__metadata_chain_write() will fail. + * + * \param chain A pointer to an existing chain. + * \param handle The I/O handle of the Ogg FLAC stream to read. The + * handle will NOT be closed after the metadata is read; + * that is the duty of the caller. + * \param callbacks + * A set of callbacks to use for I/O. The mandatory + * callbacks are \a read, \a seek, and \a tell. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if a valid list of metadata blocks was read from + * \a handle, else \c false. On failure, check the status with + * FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_read_ogg_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); + +/** Checks if writing the given chain would require the use of a + * temporary file, or if it could be written in place. + * + * Under certain conditions, padding can be utilized so that writing + * edited metadata back to the FLAC file does not require rewriting the + * entire file. If rewriting is required, then a temporary workfile is + * required. When writing metadata using callbacks, you must check + * this function to know whether to call + * FLAC__metadata_chain_write_with_callbacks() or + * FLAC__metadata_chain_write_with_callbacks_and_tempfile(). When + * writing with FLAC__metadata_chain_write(), the temporary file is + * handled internally. + * + * \param chain A pointer to an existing chain. + * \param use_padding + * Whether or not padding will be allowed to be used + * during the write. The value of \a use_padding given + * here must match the value later passed to + * FLAC__metadata_chain_write_with_callbacks() or + * FLAC__metadata_chain_write_with_callbacks_with_tempfile(). + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if writing the current chain would require a tempfile, or + * \c false if metadata can be written in place. + */ +FLAC_API FLAC__bool FLAC__metadata_chain_check_if_tempfile_needed(FLAC__Metadata_Chain *chain, FLAC__bool use_padding); + +/** Write all metadata out to the FLAC file. This function tries to be as + * efficient as possible; how the metadata is actually written is shown by + * the following: + * + * If the current chain is the same size as the existing metadata, the new + * data is written in place. + * + * If the current chain is longer than the existing metadata, and + * \a use_padding is \c true, and the last block is a PADDING block of + * sufficient length, the function will truncate the final padding block + * so that the overall size of the metadata is the same as the existing + * metadata, and then just rewrite the metadata. Otherwise, if not all of + * the above conditions are met, the entire FLAC file must be rewritten. + * If you want to use padding this way it is a good idea to call + * FLAC__metadata_chain_sort_padding() first so that you have the maximum + * amount of padding to work with, unless you need to preserve ordering + * of the PADDING blocks for some reason. + * + * If the current chain is shorter than the existing metadata, and + * \a use_padding is \c true, and the final block is a PADDING block, the padding + * is extended to make the overall size the same as the existing data. If + * \a use_padding is \c true and the last block is not a PADDING block, a new + * PADDING block is added to the end of the new data to make it the same + * size as the existing data (if possible, see the note to + * FLAC__metadata_simple_iterator_set_block() about the four byte limit) + * and the new data is written in place. If none of the above apply or + * \a use_padding is \c false, the entire FLAC file is rewritten. + * + * If \a preserve_file_stats is \c true, the owner and modification time will + * be preserved even if the FLAC file is written. + * + * For this write function to be used, the chain must have been read with + * FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(), not + * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(). + * + * \param chain A pointer to an existing chain. + * \param use_padding See above. + * \param preserve_file_stats See above. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if the write succeeded, else \c false. On failure, + * check the status with FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_write(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__bool preserve_file_stats); + +/** Write all metadata out to a FLAC stream via callbacks. + * + * (See FLAC__metadata_chain_write() for the details on how padding is + * used to write metadata in place if possible.) + * + * The \a handle must be open for updating and be seekable. The + * equivalent minimum stdio fopen() file mode is \c "r+" (or \c "r+b" + * for Windows). + * + * For this write function to be used, the chain must have been read with + * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), + * not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). + * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned + * \c false. + * + * \param chain A pointer to an existing chain. + * \param use_padding See FLAC__metadata_chain_write() + * \param handle The I/O handle of the FLAC stream to write. The + * handle will NOT be closed after the metadata is + * written; that is the duty of the caller. + * \param callbacks A set of callbacks to use for I/O. The mandatory + * callbacks are \a write and \a seek. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if the write succeeded, else \c false. On failure, + * check the status with FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks); + +/** Write all metadata out to a FLAC stream via callbacks. + * + * (See FLAC__metadata_chain_write() for the details on how padding is + * used to write metadata in place if possible.) + * + * This version of the write-with-callbacks function must be used when + * FLAC__metadata_chain_check_if_tempfile_needed() returns true. In + * this function, you must supply an I/O handle corresponding to the + * FLAC file to edit, and a temporary handle to which the new FLAC + * file will be written. It is the caller's job to move this temporary + * FLAC file on top of the original FLAC file to complete the metadata + * edit. + * + * The \a handle must be open for reading and be seekable. The + * equivalent minimum stdio fopen() file mode is \c "r" (or \c "rb" + * for Windows). + * + * The \a temp_handle must be open for writing. The + * equivalent minimum stdio fopen() file mode is \c "w" (or \c "wb" + * for Windows). It should be an empty stream, or at least positioned + * at the start-of-file (in which case it is the caller's duty to + * truncate it on return). + * + * For this write function to be used, the chain must have been read with + * FLAC__metadata_chain_read_with_callbacks()/FLAC__metadata_chain_read_ogg_with_callbacks(), + * not FLAC__metadata_chain_read()/FLAC__metadata_chain_read_ogg(). + * Also, FLAC__metadata_chain_check_if_tempfile_needed() must have returned + * \c true. + * + * \param chain A pointer to an existing chain. + * \param use_padding See FLAC__metadata_chain_write() + * \param handle The I/O handle of the original FLAC stream to read. + * The handle will NOT be closed after the metadata is + * written; that is the duty of the caller. + * \param callbacks A set of callbacks to use for I/O on \a handle. + * The mandatory callbacks are \a read, \a seek, and + * \a eof. + * \param temp_handle The I/O handle of the FLAC stream to write. The + * handle will NOT be closed after the metadata is + * written; that is the duty of the caller. + * \param temp_callbacks + * A set of callbacks to use for I/O on temp_handle. + * The only mandatory callback is \a write. + * \assert + * \code chain != NULL \endcode + * \retval FLAC__bool + * \c true if the write succeeded, else \c false. On failure, + * check the status with FLAC__metadata_chain_status(). + */ +FLAC_API FLAC__bool FLAC__metadata_chain_write_with_callbacks_and_tempfile(FLAC__Metadata_Chain *chain, FLAC__bool use_padding, FLAC__IOHandle handle, FLAC__IOCallbacks callbacks, FLAC__IOHandle temp_handle, FLAC__IOCallbacks temp_callbacks); + +/** Merge adjacent PADDING blocks into a single block. + * + * \note This function does not write to the FLAC file, it only + * modifies the chain. + * + * \warning Any iterator on the current chain will become invalid after this + * call. You should delete the iterator and get a new one. + * + * \param chain A pointer to an existing chain. + * \assert + * \code chain != NULL \endcode + */ +FLAC_API void FLAC__metadata_chain_merge_padding(FLAC__Metadata_Chain *chain); + +/** This function will move all PADDING blocks to the end on the metadata, + * then merge them into a single block. + * + * \note This function does not write to the FLAC file, it only + * modifies the chain. + * + * \warning Any iterator on the current chain will become invalid after this + * call. You should delete the iterator and get a new one. + * + * \param chain A pointer to an existing chain. + * \assert + * \code chain != NULL \endcode + */ +FLAC_API void FLAC__metadata_chain_sort_padding(FLAC__Metadata_Chain *chain); + + +/*********** FLAC__Metadata_Iterator ***********/ + +/** Create a new iterator instance. + * + * \retval FLAC__Metadata_Iterator* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__Metadata_Iterator *FLAC__metadata_iterator_new(void); + +/** Free an iterator instance. Deletes the object pointed to by \a iterator. + * + * \param iterator A pointer to an existing iterator. + * \assert + * \code iterator != NULL \endcode + */ +FLAC_API void FLAC__metadata_iterator_delete(FLAC__Metadata_Iterator *iterator); + +/** Initialize the iterator to point to the first metadata block in the + * given chain. + * + * \param iterator A pointer to an existing iterator. + * \param chain A pointer to an existing and initialized (read) chain. + * \assert + * \code iterator != NULL \endcode + * \code chain != NULL \endcode + */ +FLAC_API void FLAC__metadata_iterator_init(FLAC__Metadata_Iterator *iterator, FLAC__Metadata_Chain *chain); + +/** Moves the iterator forward one metadata block, returning \c false if + * already at the end. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__bool + * \c false if already at the last metadata block of the chain, else + * \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_next(FLAC__Metadata_Iterator *iterator); + +/** Moves the iterator backward one metadata block, returning \c false if + * already at the beginning. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__bool + * \c false if already at the first metadata block of the chain, else + * \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_prev(FLAC__Metadata_Iterator *iterator); + +/** Get the type of the metadata block at the current position. + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__MetadataType + * The type of the metadata block at the current iterator position. + */ +FLAC_API FLAC__MetadataType FLAC__metadata_iterator_get_block_type(const FLAC__Metadata_Iterator *iterator); + +/** Get the metadata block at the current position. You can modify + * the block in place but must write the chain before the changes + * are reflected to the FLAC file. You do not need to call + * FLAC__metadata_iterator_set_block() to reflect the changes; + * the pointer returned by FLAC__metadata_iterator_get_block() + * points directly into the chain. + * + * \warning + * Do not call FLAC__metadata_object_delete() on the returned object; + * to delete a block use FLAC__metadata_iterator_delete_block(). + * + * \param iterator A pointer to an existing initialized iterator. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__StreamMetadata* + * The current metadata block. + */ +FLAC_API FLAC__StreamMetadata *FLAC__metadata_iterator_get_block(FLAC__Metadata_Iterator *iterator); + +/** Set the metadata block at the current position, replacing the existing + * block. The new block passed in becomes owned by the chain and it will be + * deleted when the chain is deleted. + * + * \param iterator A pointer to an existing initialized iterator. + * \param block A pointer to a metadata block. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \code block != NULL \endcode + * \retval FLAC__bool + * \c false if the conditions in the above description are not met, or + * a memory allocation error occurs, otherwise \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_set_block(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); + +/** Removes the current block from the chain. If \a replace_with_padding is + * \c true, the block will instead be replaced with a padding block of equal + * size. You can not delete the STREAMINFO block. The iterator will be + * left pointing to the block before the one just "deleted", even if + * \a replace_with_padding is \c true. + * + * \param iterator A pointer to an existing initialized iterator. + * \param replace_with_padding See above. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__bool + * \c false if the conditions in the above description are not met, + * otherwise \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_delete_block(FLAC__Metadata_Iterator *iterator, FLAC__bool replace_with_padding); + +/** Insert a new block before the current block. You cannot insert a block + * before the first STREAMINFO block. You cannot insert a STREAMINFO block + * as there can be only one, the one that already exists at the head when you + * read in a chain. The chain takes ownership of the new block and it will be + * deleted when the chain is deleted. The iterator will be left pointing to + * the new block. + * + * \param iterator A pointer to an existing initialized iterator. + * \param block A pointer to a metadata block to insert. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__bool + * \c false if the conditions in the above description are not met, or + * a memory allocation error occurs, otherwise \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_before(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); + +/** Insert a new block after the current block. You cannot insert a STREAMINFO + * block as there can be only one, the one that already exists at the head when + * you read in a chain. The chain takes ownership of the new block and it will + * be deleted when the chain is deleted. The iterator will be left pointing to + * the new block. + * + * \param iterator A pointer to an existing initialized iterator. + * \param block A pointer to a metadata block to insert. + * \assert + * \code iterator != NULL \endcode + * \a iterator has been successfully initialized with + * FLAC__metadata_iterator_init() + * \retval FLAC__bool + * \c false if the conditions in the above description are not met, or + * a memory allocation error occurs, otherwise \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_iterator_insert_block_after(FLAC__Metadata_Iterator *iterator, FLAC__StreamMetadata *block); + +/* \} */ + + +/** \defgroup flac_metadata_object FLAC/metadata.h: metadata object methods + * \ingroup flac_metadata + * + * \brief + * This module contains methods for manipulating FLAC metadata objects. + * + * Since many are variable length we have to be careful about the memory + * management. We decree that all pointers to data in the object are + * owned by the object and memory-managed by the object. + * + * Use the FLAC__metadata_object_new() and FLAC__metadata_object_delete() + * functions to create all instances. When using the + * FLAC__metadata_object_set_*() functions to set pointers to data, set + * \a copy to \c true to have the function make it's own copy of the data, or + * to \c false to give the object ownership of your data. In the latter case + * your pointer must be freeable by free() and will be free()d when the object + * is FLAC__metadata_object_delete()d. It is legal to pass a null pointer as + * the data pointer to a FLAC__metadata_object_set_*() function as long as + * the length argument is 0 and the \a copy argument is \c false. + * + * The FLAC__metadata_object_new() and FLAC__metadata_object_clone() function + * will return \c NULL in the case of a memory allocation error, otherwise a new + * object. The FLAC__metadata_object_set_*() functions return \c false in the + * case of a memory allocation error. + * + * We don't have the convenience of C++ here, so note that the library relies + * on you to keep the types straight. In other words, if you pass, for + * example, a FLAC__StreamMetadata* that represents a STREAMINFO block to + * FLAC__metadata_object_application_set_data(), you will get an assertion + * failure. + * + * For convenience the FLAC__metadata_object_vorbiscomment_*() functions + * maintain a trailing NUL on each Vorbis comment entry. This is not counted + * toward the length or stored in the stream, but it can make working with plain + * comments (those that don't contain embedded-NULs in the value) easier. + * Entries passed into these functions have trailing NULs added if missing, and + * returned entries are guaranteed to have a trailing NUL. + * + * The FLAC__metadata_object_vorbiscomment_*() functions that take a Vorbis + * comment entry/name/value will first validate that it complies with the Vorbis + * comment specification and return false if it does not. + * + * There is no need to recalculate the length field on metadata blocks you + * have modified. They will be calculated automatically before they are + * written back to a file. + * + * \{ + */ + + +/** Create a new metadata object instance of the given type. + * + * The object will be "empty"; i.e. values and data pointers will be \c 0, + * with the exception of FLAC__METADATA_TYPE_VORBIS_COMMENT, which will have + * the vendor string set (but zero comments). + * + * Do not pass in a value greater than or equal to + * \a FLAC__METADATA_TYPE_UNDEFINED unless you really know what you're + * doing. + * + * \param type Type of object to create + * \retval FLAC__StreamMetadata* + * \c NULL if there was an error allocating memory or the type code is + * greater than FLAC__MAX_METADATA_TYPE_CODE, else the new instance. + */ +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_new(FLAC__MetadataType type); + +/** Create a copy of an existing metadata object. + * + * The copy is a "deep" copy, i.e. dynamically allocated data within the + * object is also copied. The caller takes ownership of the new block and + * is responsible for freeing it with FLAC__metadata_object_delete(). + * + * \param object Pointer to object to copy. + * \assert + * \code object != NULL \endcode + * \retval FLAC__StreamMetadata* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__StreamMetadata *FLAC__metadata_object_clone(const FLAC__StreamMetadata *object); + +/** Free a metadata object. Deletes the object pointed to by \a object. + * + * The delete is a "deep" delete, i.e. dynamically allocated data within the + * object is also deleted. + * + * \param object A pointer to an existing object. + * \assert + * \code object != NULL \endcode + */ +FLAC_API void FLAC__metadata_object_delete(FLAC__StreamMetadata *object); + +/** Compares two metadata objects. + * + * The compare is "deep", i.e. dynamically allocated data within the + * object is also compared. + * + * \param block1 A pointer to an existing object. + * \param block2 A pointer to an existing object. + * \assert + * \code block1 != NULL \endcode + * \code block2 != NULL \endcode + * \retval FLAC__bool + * \c true if objects are identical, else \c false. + */ +FLAC_API FLAC__bool FLAC__metadata_object_is_equal(const FLAC__StreamMetadata *block1, const FLAC__StreamMetadata *block2); + +/** Sets the application data of an APPLICATION block. + * + * If \a copy is \c true, a copy of the data is stored; otherwise, the object + * takes ownership of the pointer. The existing data will be freed if this + * function is successful, otherwise the original data will remain if \a copy + * is \c true and malloc() fails. + * + * \note It is safe to pass a const pointer to \a data if \a copy is \c true. + * + * \param object A pointer to an existing APPLICATION object. + * \param data A pointer to the data to set. + * \param length The length of \a data in bytes. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_APPLICATION \endcode + * \code (data != NULL && length > 0) || + * (data == NULL && length == 0 && copy == false) \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, unsigned length, FLAC__bool copy); + +/** Resize the seekpoint array. + * + * If the size shrinks, elements will truncated; if it grows, new placeholder + * points will be added to the end. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param new_num_points The desired length of the array; may be \c 0. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code (object->data.seek_table.points == NULL && object->data.seek_table.num_points == 0) || + * (object->data.seek_table.points != NULL && object->data.seek_table.num_points > 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_resize_points(FLAC__StreamMetadata *object, unsigned new_num_points); + +/** Set a seekpoint in a seektable. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param point_num Index into seekpoint array to set. + * \param point The point to set. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code object->data.seek_table.num_points > point_num \endcode + */ +FLAC_API void FLAC__metadata_object_seektable_set_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); + +/** Insert a seekpoint into a seektable. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param point_num Index into seekpoint array to set. + * \param point The point to set. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code object->data.seek_table.num_points >= point_num \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_insert_point(FLAC__StreamMetadata *object, unsigned point_num, FLAC__StreamMetadata_SeekPoint point); + +/** Delete a seekpoint from a seektable. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param point_num Index into seekpoint array to set. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code object->data.seek_table.num_points > point_num \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_delete_point(FLAC__StreamMetadata *object, unsigned point_num); + +/** Check a seektable to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * seektable. + * + * \param object A pointer to an existing SEEKTABLE object. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \retval FLAC__bool + * \c false if seek table is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_is_legal(const FLAC__StreamMetadata *object); + +/** Append a number of placeholder points to the end of a seek table. + * + * \note + * As with the other ..._seektable_template_... functions, you should + * call FLAC__metadata_object_seektable_template_sort() when finished + * to make the seek table legal. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param num The number of placeholder points to append. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_placeholders(FLAC__StreamMetadata *object, unsigned num); + +/** Append a specific seek point template to the end of a seek table. + * + * \note + * As with the other ..._seektable_template_... functions, you should + * call FLAC__metadata_object_seektable_template_sort() when finished + * to make the seek table legal. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param sample_number The sample number of the seek point template. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_point(FLAC__StreamMetadata *object, FLAC__uint64 sample_number); + +/** Append specific seek point templates to the end of a seek table. + * + * \note + * As with the other ..._seektable_template_... functions, you should + * call FLAC__metadata_object_seektable_template_sort() when finished + * to make the seek table legal. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param sample_numbers An array of sample numbers for the seek points. + * \param num The number of seek point templates to append. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC__StreamMetadata *object, FLAC__uint64 sample_numbers[], unsigned num); + +/** Append a set of evenly-spaced seek point templates to the end of a + * seek table. + * + * \note + * As with the other ..._seektable_template_... functions, you should + * call FLAC__metadata_object_seektable_template_sort() when finished + * to make the seek table legal. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param num The number of placeholder points to append. + * \param total_samples The total number of samples to be encoded; + * the seekpoints will be spaced approximately + * \a total_samples / \a num samples apart. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code total_samples > 0 \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples); + +/** Append a set of evenly-spaced seek point templates to the end of a + * seek table. + * + * \note + * As with the other ..._seektable_template_... functions, you should + * call FLAC__metadata_object_seektable_template_sort() when finished + * to make the seek table legal. + * + * \param object A pointer to an existing SEEKTABLE object. + * \param samples The number of samples apart to space the placeholder + * points. The first point will be at sample \c 0, the + * second at sample \a samples, then 2*\a samples, and + * so on. As long as \a samples and \a total_samples + * are greater than \c 0, there will always be at least + * one seekpoint at sample \c 0. + * \param total_samples The total number of samples to be encoded; + * the seekpoints will be spaced + * \a samples samples apart. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \code samples > 0 \endcode + * \code total_samples > 0 \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples); + +/** Sort a seek table's seek points according to the format specification, + * removing duplicates. + * + * \param object A pointer to a seek table to be sorted. + * \param compact If \c false, behaves like FLAC__format_seektable_sort(). + * If \c true, duplicates are deleted and the seek table is + * shrunk appropriately; the number of placeholder points + * present in the seek table will be the same after the call + * as before. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_sort(FLAC__StreamMetadata *object, FLAC__bool compact); + +/** Sets the vendor string in a VORBIS_COMMENT block. + * + * For convenience, a trailing NUL is added to the entry if it doesn't have + * one already. + * + * If \a copy is \c true, a copy of the entry is stored; otherwise, the object + * takes ownership of the \c entry.entry pointer. + * + * \note If this function returns \c false, the caller still owns the + * pointer. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param entry The entry to set the vendor string to. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code (entry.entry != NULL && entry.length > 0) || + * (entry.entry == NULL && entry.length == 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); + +/** Resize the comment array. + * + * If the size shrinks, elements will truncated; if it grows, new empty + * fields will be added to the end. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param new_num_comments The desired length of the array; may be \c 0. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code (object->data.vorbis_comment.comments == NULL && object->data.vorbis_comment.num_comments == 0) || + * (object->data.vorbis_comment.comments != NULL && object->data.vorbis_comment.num_comments > 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments); + +/** Sets a comment in a VORBIS_COMMENT block. + * + * For convenience, a trailing NUL is added to the entry if it doesn't have + * one already. + * + * If \a copy is \c true, a copy of the entry is stored; otherwise, the object + * takes ownership of the \c entry.entry pointer. + * + * \note If this function returns \c false, the caller still owns the + * pointer. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param comment_num Index into comment array to set. + * \param entry The entry to set the comment to. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code comment_num < object->data.vorbis_comment.num_comments \endcode + * \code (entry.entry != NULL && entry.length > 0) || + * (entry.entry == NULL && entry.length == 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); + +/** Insert a comment in a VORBIS_COMMENT block at the given index. + * + * For convenience, a trailing NUL is added to the entry if it doesn't have + * one already. + * + * If \a copy is \c true, a copy of the entry is stored; otherwise, the object + * takes ownership of the \c entry.entry pointer. + * + * \note If this function returns \c false, the caller still owns the + * pointer. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param comment_num The index at which to insert the comment. The comments + * at and after \a comment_num move right one position. + * To append a comment to the end, set \a comment_num to + * \c object->data.vorbis_comment.num_comments . + * \param entry The comment to insert. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code object->data.vorbis_comment.num_comments >= comment_num \endcode + * \code (entry.entry != NULL && entry.length > 0) || + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); + +/** Appends a comment to a VORBIS_COMMENT block. + * + * For convenience, a trailing NUL is added to the entry if it doesn't have + * one already. + * + * If \a copy is \c true, a copy of the entry is stored; otherwise, the object + * takes ownership of the \c entry.entry pointer. + * + * \note If this function returns \c false, the caller still owns the + * pointer. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param entry The comment to insert. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code (entry.entry != NULL && entry.length > 0) || + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_append_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy); + +/** Replaces comments in a VORBIS_COMMENT block with a new one. + * + * For convenience, a trailing NUL is added to the entry if it doesn't have + * one already. + * + * Depending on the the value of \a all, either all or just the first comment + * whose field name(s) match the given entry's name will be replaced by the + * given entry. If no comments match, \a entry will simply be appended. + * + * If \a copy is \c true, a copy of the entry is stored; otherwise, the object + * takes ownership of the \c entry.entry pointer. + * + * \note If this function returns \c false, the caller still owns the + * pointer. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param entry The comment to insert. + * \param all If \c true, all comments whose field name matches + * \a entry's field name will be removed, and \a entry will + * be inserted at the position of the first matching + * comment. If \c false, only the first comment whose + * field name matches \a entry's field name will be + * replaced with \a entry. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code (entry.entry != NULL && entry.length > 0) || + * (entry.entry == NULL && entry.length == 0 && copy == false) \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_replace_comment(FLAC__StreamMetadata *object, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool all, FLAC__bool copy); + +/** Delete a comment in a VORBIS_COMMENT block at the given index. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param comment_num The index of the comment to delete. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code object->data.vorbis_comment.num_comments > comment_num \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_delete_comment(FLAC__StreamMetadata *object, unsigned comment_num); + +/** Creates a Vorbis comment entry from NUL-terminated name and value strings. + * + * On return, the filled-in \a entry->entry pointer will point to malloc()ed + * memory and shall be owned by the caller. For convenience the entry will + * have a terminating NUL. + * + * \param entry A pointer to a Vorbis comment entry. The entry's + * \c entry pointer should not point to allocated + * memory as it will be overwritten. + * \param field_name The field name in ASCII, \c NUL terminated. + * \param field_value The field value in UTF-8, \c NUL terminated. + * \assert + * \code entry != NULL \endcode + * \code field_name != NULL \endcode + * \code field_value != NULL \endcode + * \retval FLAC__bool + * \c false if malloc() fails, or if \a field_name or \a field_value does + * not comply with the Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_from_name_value_pair(FLAC__StreamMetadata_VorbisComment_Entry *entry, const char *field_name, const char *field_value); + +/** Splits a Vorbis comment entry into NUL-terminated name and value strings. + * + * The returned pointers to name and value will be allocated by malloc() + * and shall be owned by the caller. + * + * \param entry An existing Vorbis comment entry. + * \param field_name The address of where the returned pointer to the + * field name will be stored. + * \param field_value The address of where the returned pointer to the + * field value will be stored. + * \assert + * \code (entry.entry != NULL && entry.length > 0) \endcode + * \code memchr(entry.entry, '=', entry.length) != NULL \endcode + * \code field_name != NULL \endcode + * \code field_value != NULL \endcode + * \retval FLAC__bool + * \c false if memory allocation fails or \a entry does not comply with the + * Vorbis comment specification, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_to_name_value_pair(const FLAC__StreamMetadata_VorbisComment_Entry entry, char **field_name, char **field_value); + +/** Check if the given Vorbis comment entry's field name matches the given + * field name. + * + * \param entry An existing Vorbis comment entry. + * \param field_name The field name to check. + * \param field_name_length The length of \a field_name, not including the + * terminating \c NUL. + * \assert + * \code (entry.entry != NULL && entry.length > 0) \endcode + * \retval FLAC__bool + * \c true if the field names match, else \c false + */ +FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_entry_matches(const FLAC__StreamMetadata_VorbisComment_Entry entry, const char *field_name, unsigned field_name_length); + +/** Find a Vorbis comment with the given field name. + * + * The search begins at entry number \a offset; use an offset of 0 to + * search from the beginning of the comment array. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param offset The offset into the comment array from where to start + * the search. + * \param field_name The field name of the comment to find. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \code field_name != NULL \endcode + * \retval int + * The offset in the comment array of the first comment whose field + * name matches \a field_name, or \c -1 if no match was found. + */ +FLAC_API int FLAC__metadata_object_vorbiscomment_find_entry_from(const FLAC__StreamMetadata *object, unsigned offset, const char *field_name); + +/** Remove first Vorbis comment matching the given field name. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param field_name The field name of comment to delete. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \retval int + * \c -1 for memory allocation error, \c 0 for no matching entries, + * \c 1 for one matching entry deleted. + */ +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entry_matching(FLAC__StreamMetadata *object, const char *field_name); + +/** Remove all Vorbis comments matching the given field name. + * + * \param object A pointer to an existing VORBIS_COMMENT object. + * \param field_name The field name of comments to delete. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode + * \retval int + * \c -1 for memory allocation error, \c 0 for no matching entries, + * else the number of matching entries deleted. + */ +FLAC_API int FLAC__metadata_object_vorbiscomment_remove_entries_matching(FLAC__StreamMetadata *object, const char *field_name); + +/** Create a new CUESHEET track instance. + * + * The object will be "empty"; i.e. values and data pointers will be \c 0. + * + * \retval FLAC__StreamMetadata_CueSheet_Track* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_new(void); + +/** Create a copy of an existing CUESHEET track object. + * + * The copy is a "deep" copy, i.e. dynamically allocated data within the + * object is also copied. The caller takes ownership of the new object and + * is responsible for freeing it with + * FLAC__metadata_object_cuesheet_track_delete(). + * + * \param object Pointer to object to copy. + * \assert + * \code object != NULL \endcode + * \retval FLAC__StreamMetadata_CueSheet_Track* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__StreamMetadata_CueSheet_Track *FLAC__metadata_object_cuesheet_track_clone(const FLAC__StreamMetadata_CueSheet_Track *object); + +/** Delete a CUESHEET track object + * + * \param object A pointer to an existing CUESHEET track object. + * \assert + * \code object != NULL \endcode + */ +FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_CueSheet_Track *object); + +/** Resize a track's index point array. + * + * If the size shrinks, elements will truncated; if it grows, new blank + * indices will be added to the end. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index of the track to modify. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param new_num_indices The desired length of the array; may be \c 0. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code (object->data.cue_sheet.tracks[track_num].indices == NULL && object->data.cue_sheet.tracks[track_num].num_indices == 0) || + * (object->data.cue_sheet.tracks[track_num].indices != NULL && object->data.cue_sheet.tracks[track_num].num_indices > 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices); + +/** Insert an index point in a CUESHEET track at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index of the track to modify. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param index_num The index into the track's index array at which to + * insert the index point. NOTE: this is not necessarily + * the same as the index point's \a number field. The + * indices at and after \a index_num move right one + * position. To append an index point to the end, set + * \a index_num to + * \c object->data.cue_sheet.tracks[track_num].num_indices . + * \param index The index point to insert. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index); + +/** Insert a blank index point in a CUESHEET track at the given index. + * + * A blank index point is one in which all field values are zero. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index of the track to modify. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param index_num The index into the track's index array at which to + * insert the index point. NOTE: this is not necessarily + * the same as the index point's \a number field. The + * indices at and after \a index_num move right one + * position. To append an index point to the end, set + * \a index_num to + * \c object->data.cue_sheet.tracks[track_num].num_indices . + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); + +/** Delete an index point in a CUESHEET track at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index into the track array of the track to + * modify. NOTE: this is not necessarily the same + * as the track's \a number field. + * \param index_num The index into the track's index array of the index + * to delete. NOTE: this is not necessarily the same + * as the index's \a number field. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num); + +/** Resize the track array. + * + * If the size shrinks, elements will truncated; if it grows, new blank + * tracks will be added to the end. + * + * \param object A pointer to an existing CUESHEET object. + * \param new_num_tracks The desired length of the array; may be \c 0. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) || + * (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode + * \retval FLAC__bool + * \c false if memory allocation error, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks); + +/** Sets a track in a CUESHEET block. + * + * If \a copy is \c true, a copy of the track is stored; otherwise, the object + * takes ownership of the \a track pointer. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num Index into track array to set. NOTE: this is not + * necessarily the same as the track's \a number field. + * \param track The track to set the track to. You may safely pass in + * a const pointer if \a copy is \c true. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code track_num < object->data.cue_sheet.num_tracks \endcode + * \code (track->indices != NULL && track->num_indices > 0) || + * (track->indices == NULL && track->num_indices == 0) \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); + +/** Insert a track in a CUESHEET block at the given index. + * + * If \a copy is \c true, a copy of the track is stored; otherwise, the object + * takes ownership of the \a track pointer. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index at which to insert the track. NOTE: this + * is not necessarily the same as the track's \a number + * field. The tracks at and after \a track_num move right + * one position. To append a track to the end, set + * \a track_num to \c object->data.cue_sheet.num_tracks . + * \param track The track to insert. You may safely pass in a const + * pointer if \a copy is \c true. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks >= track_num \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy); + +/** Insert a blank track in a CUESHEET block at the given index. + * + * A blank track is one in which all field values are zero. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index at which to insert the track. NOTE: this + * is not necessarily the same as the track's \a number + * field. The tracks at and after \a track_num move right + * one position. To append a track to the end, set + * \a track_num to \c object->data.cue_sheet.num_tracks . + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks >= track_num \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num); + +/** Delete a track in a CUESHEET block at the given index. + * + * \param object A pointer to an existing CUESHEET object. + * \param track_num The index into the track array of the track to + * delete. NOTE: this is not necessarily the same + * as the track's \a number field. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \code object->data.cue_sheet.num_tracks > track_num \endcode + * \retval FLAC__bool + * \c false if realloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num); + +/** Check a cue sheet to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * cue sheet. + * + * \param object A pointer to an existing CUESHEET object. + * \param check_cd_da_subset If \c true, check CUESHEET against more + * stringent requirements for a CD-DA (audio) disc. + * \param violation Address of a pointer to a string. If there is a + * violation, a pointer to a string explanation of the + * violation will be returned here. \a violation may be + * \c NULL if you don't need the returned string. Do not + * free the returned string; it will always point to static + * data. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \retval FLAC__bool + * \c false if cue sheet is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_is_legal(const FLAC__StreamMetadata *object, FLAC__bool check_cd_da_subset, const char **violation); + +/** Calculate and return the CDDB/freedb ID for a cue sheet. The function + * assumes the cue sheet corresponds to a CD; the result is undefined + * if the cuesheet's is_cd bit is not set. + * + * \param object A pointer to an existing CUESHEET object. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode + * \retval FLAC__uint32 + * The unsigned integer representation of the CDDB/freedb ID + */ +FLAC_API FLAC__uint32 FLAC__metadata_object_cuesheet_calculate_cddb_id(const FLAC__StreamMetadata *object); + +/** Sets the MIME type of a PICTURE block. + * + * If \a copy is \c true, a copy of the string is stored; otherwise, the object + * takes ownership of the pointer. The existing string will be freed if this + * function is successful, otherwise the original string will remain if \a copy + * is \c true and malloc() fails. + * + * \note It is safe to pass a const pointer to \a mime_type if \a copy is \c true. + * + * \param object A pointer to an existing PICTURE object. + * \param mime_type A pointer to the MIME type string. The string must be + * ASCII characters 0x20-0x7e, NUL-terminated. No validation + * is done. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode + * \code (mime_type != NULL) \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_mime_type(FLAC__StreamMetadata *object, char *mime_type, FLAC__bool copy); + +/** Sets the description of a PICTURE block. + * + * If \a copy is \c true, a copy of the string is stored; otherwise, the object + * takes ownership of the pointer. The existing string will be freed if this + * function is successful, otherwise the original string will remain if \a copy + * is \c true and malloc() fails. + * + * \note It is safe to pass a const pointer to \a description if \a copy is \c true. + * + * \param object A pointer to an existing PICTURE object. + * \param description A pointer to the description string. The string must be + * valid UTF-8, NUL-terminated. No validation is done. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode + * \code (description != NULL) \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_description(FLAC__StreamMetadata *object, FLAC__byte *description, FLAC__bool copy); + +/** Sets the picture data of a PICTURE block. + * + * If \a copy is \c true, a copy of the data is stored; otherwise, the object + * takes ownership of the pointer. Also sets the \a data_length field of the + * metadata object to what is passed in as the \a length parameter. The + * existing data will be freed if this function is successful, otherwise the + * original data and data_length will remain if \a copy is \c true and + * malloc() fails. + * + * \note It is safe to pass a const pointer to \a data if \a copy is \c true. + * + * \param object A pointer to an existing PICTURE object. + * \param data A pointer to the data to set. + * \param length The length of \a data in bytes. + * \param copy See above. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode + * \code (data != NULL && length > 0) || + * (data == NULL && length == 0 && copy == false) \endcode + * \retval FLAC__bool + * \c false if \a copy is \c true and malloc() fails, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_picture_set_data(FLAC__StreamMetadata *object, FLAC__byte *data, FLAC__uint32 length, FLAC__bool copy); + +/** Check a PICTURE block to see if it conforms to the FLAC specification. + * See the format specification for limits on the contents of the + * PICTURE block. + * + * \param object A pointer to existing PICTURE block to be checked. + * \param violation Address of a pointer to a string. If there is a + * violation, a pointer to a string explanation of the + * violation will be returned here. \a violation may be + * \c NULL if you don't need the returned string. Do not + * free the returned string; it will always point to static + * data. + * \assert + * \code object != NULL \endcode + * \code object->type == FLAC__METADATA_TYPE_PICTURE \endcode + * \retval FLAC__bool + * \c false if PICTURE block is illegal, else \c true. + */ +FLAC_API FLAC__bool FLAC__metadata_object_picture_is_legal(const FLAC__StreamMetadata *object, const char **violation); + +/* \} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/flac/include/FLAC/ordinals.h b/flac/include/FLAC/ordinals.h new file mode 100644 index 00000000..b1e1acfc --- /dev/null +++ b/flac/include/FLAC/ordinals.h @@ -0,0 +1,86 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__ORDINALS_H +#define FLAC__ORDINALS_H + +#if defined(_MSC_VER) && _MSC_VER < 1600 + +/* Microsoft Visual Studio earlier than the 2010 version did not provide + * the 1999 ISO C Standard header file . + */ + +typedef __int8 FLAC__int8; +typedef unsigned __int8 FLAC__uint8; + +typedef __int16 FLAC__int16; +typedef __int32 FLAC__int32; +typedef __int64 FLAC__int64; +typedef unsigned __int16 FLAC__uint16; +typedef unsigned __int32 FLAC__uint32; +typedef unsigned __int64 FLAC__uint64; + +#else + +/* For MSVC 2010 and everything else which provides . */ + +#include + +typedef int8_t FLAC__int8; +typedef uint8_t FLAC__uint8; + +typedef int16_t FLAC__int16; +typedef int32_t FLAC__int32; +typedef int64_t FLAC__int64; +typedef uint16_t FLAC__uint16; +typedef uint32_t FLAC__uint32; +typedef uint64_t FLAC__uint64; + +#endif + +typedef int FLAC__bool; + +typedef FLAC__uint8 FLAC__byte; + + +#ifdef true +#undef true +#endif +#ifdef false +#undef false +#endif +#ifndef __cplusplus +#define true 1 +#define false 0 +#endif + +#endif diff --git a/flac/include/FLAC/stream_decoder.h b/flac/include/FLAC/stream_decoder.h new file mode 100644 index 00000000..9bfdd1f5 --- /dev/null +++ b/flac/include/FLAC/stream_decoder.h @@ -0,0 +1,1560 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__STREAM_DECODER_H +#define FLAC__STREAM_DECODER_H + +#include /* for FILE */ +#include "export.h" +#include "format.h" + +#ifdef __cplusplus +extern "C" { +#endif + + +/** \file include/FLAC/stream_decoder.h + * + * \brief + * This module contains the functions which implement the stream + * decoder. + * + * See the detailed documentation in the + * \link flac_stream_decoder stream decoder \endlink module. + */ + +/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces + * \ingroup flac + * + * \brief + * This module describes the decoder layers provided by libFLAC. + * + * The stream decoder can be used to decode complete streams either from + * the client via callbacks, or directly from a file, depending on how + * it is initialized. When decoding via callbacks, the client provides + * callbacks for reading FLAC data and writing decoded samples, and + * handling metadata and errors. If the client also supplies seek-related + * callback, the decoder function for sample-accurate seeking within the + * FLAC input is also available. When decoding from a file, the client + * needs only supply a filename or open \c FILE* and write/metadata/error + * callbacks; the rest of the callbacks are supplied internally. For more + * info see the \link flac_stream_decoder stream decoder \endlink module. + */ + +/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface + * \ingroup flac_decoder + * + * \brief + * This module contains the functions which implement the stream + * decoder. + * + * The stream decoder can decode native FLAC, and optionally Ogg FLAC + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files. + * + * The basic usage of this decoder is as follows: + * - The program creates an instance of a decoder using + * FLAC__stream_decoder_new(). + * - The program overrides the default settings using + * FLAC__stream_decoder_set_*() functions. + * - The program initializes the instance to validate the settings and + * prepare for decoding using + * - FLAC__stream_decoder_init_stream() or FLAC__stream_decoder_init_FILE() + * or FLAC__stream_decoder_init_file() for native FLAC, + * - FLAC__stream_decoder_init_ogg_stream() or FLAC__stream_decoder_init_ogg_FILE() + * or FLAC__stream_decoder_init_ogg_file() for Ogg FLAC + * - The program calls the FLAC__stream_decoder_process_*() functions + * to decode data, which subsequently calls the callbacks. + * - The program finishes the decoding with FLAC__stream_decoder_finish(), + * which flushes the input and output and resets the decoder to the + * uninitialized state. + * - The instance may be used again or deleted with + * FLAC__stream_decoder_delete(). + * + * In more detail, the program will create a new instance by calling + * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*() + * functions to override the default decoder options, and call + * one of the FLAC__stream_decoder_init_*() functions. + * + * There are three initialization functions for native FLAC, one for + * setting up the decoder to decode FLAC data from the client via + * callbacks, and two for decoding directly from a FLAC file. + * + * For decoding via callbacks, use FLAC__stream_decoder_init_stream(). + * You must also supply several callbacks for handling I/O. Some (like + * seeking) are optional, depending on the capabilities of the input. + * + * For decoding directly from a file, use FLAC__stream_decoder_init_FILE() + * or FLAC__stream_decoder_init_file(). Then you must only supply an open + * \c FILE* or filename and fewer callbacks; the decoder will handle + * the other callbacks internally. + * + * There are three similarly-named init functions for decoding from Ogg + * FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the + * library has been built with Ogg support. + * + * Once the decoder is initialized, your program will call one of several + * functions to start the decoding process: + * + * - FLAC__stream_decoder_process_single() - Tells the decoder to process at + * most one metadata block or audio frame and return, calling either the + * metadata callback or write callback, respectively, once. If the decoder + * loses sync it will return with only the error callback being called. + * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder + * to process the stream from the current location and stop upon reaching + * the first audio frame. The client will get one metadata, write, or error + * callback per metadata block, audio frame, or sync error, respectively. + * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder + * to process the stream from the current location until the read callback + * returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or + * FLAC__STREAM_DECODER_READ_STATUS_ABORT. The client will get one metadata, + * write, or error callback per metadata block, audio frame, or sync error, + * respectively. + * + * When the decoder has finished decoding (normally or through an abort), + * the instance is finished by calling FLAC__stream_decoder_finish(), which + * ensures the decoder is in the correct state and frees memory. Then the + * instance may be deleted with FLAC__stream_decoder_delete() or initialized + * again to decode another stream. + * + * Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method. + * At any point after the stream decoder has been initialized, the client can + * call this function to seek to an exact sample within the stream. + * Subsequently, the first time the write callback is called it will be + * passed a (possibly partial) block starting at that sample. + * + * If the client cannot seek via the callback interface provided, but still + * has another way of seeking, it can flush the decoder using + * FLAC__stream_decoder_flush() and start feeding data from the new position + * through the read callback. + * + * The stream decoder also provides MD5 signature checking. If this is + * turned on before initialization, FLAC__stream_decoder_finish() will + * report when the decoded MD5 signature does not match the one stored + * in the STREAMINFO block. MD5 checking is automatically turned off + * (until the next FLAC__stream_decoder_reset()) if there is no signature + * in the STREAMINFO block or when a seek is attempted. + * + * The FLAC__stream_decoder_set_metadata_*() functions deserve special + * attention. By default, the decoder only calls the metadata_callback for + * the STREAMINFO block. These functions allow you to tell the decoder + * explicitly which blocks to parse and return via the metadata_callback + * and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(), + * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(), + * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify + * which blocks to return. Remember that metadata blocks can potentially + * be big (for example, cover art) so filtering out the ones you don't + * use can reduce the memory requirements of the decoder. Also note the + * special forms FLAC__stream_decoder_set_metadata_respond_application(id) + * and FLAC__stream_decoder_set_metadata_ignore_application(id) for + * filtering APPLICATION blocks based on the application ID. + * + * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but + * they still can legally be filtered from the metadata_callback. + * + * \note + * The "set" functions may only be called when the decoder is in the + * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after + * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but + * before FLAC__stream_decoder_init_*(). If this is the case they will + * return \c true, otherwise \c false. + * + * \note + * FLAC__stream_decoder_finish() resets all settings to the constructor + * defaults, including the callbacks. + * + * \{ + */ + + +/** State values for a FLAC__StreamDecoder + * + * The decoder's state can be obtained by calling FLAC__stream_decoder_get_state(). + */ +typedef enum { + + FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, + /**< The decoder is ready to search for metadata. */ + + FLAC__STREAM_DECODER_READ_METADATA, + /**< The decoder is ready to or is in the process of reading metadata. */ + + FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, + /**< The decoder is ready to or is in the process of searching for the + * frame sync code. + */ + + FLAC__STREAM_DECODER_READ_FRAME, + /**< The decoder is ready to or is in the process of reading a frame. */ + + FLAC__STREAM_DECODER_END_OF_STREAM, + /**< The decoder has reached the end of the stream. */ + + FLAC__STREAM_DECODER_OGG_ERROR, + /**< An error occurred in the underlying Ogg layer. */ + + FLAC__STREAM_DECODER_SEEK_ERROR, + /**< An error occurred while seeking. The decoder must be flushed + * with FLAC__stream_decoder_flush() or reset with + * FLAC__stream_decoder_reset() before decoding can continue. + */ + + FLAC__STREAM_DECODER_ABORTED, + /**< The decoder was aborted by the read callback. */ + + FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, + /**< An error occurred allocating memory. The decoder is in an invalid + * state and can no longer be used. + */ + + FLAC__STREAM_DECODER_UNINITIALIZED + /**< The decoder is in the uninitialized state; one of the + * FLAC__stream_decoder_init_*() functions must be called before samples + * can be processed. + */ + +} FLAC__StreamDecoderState; + +/** Maps a FLAC__StreamDecoderState to a C string. + * + * Using a FLAC__StreamDecoderState as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderStateString[]; + + +/** Possible return values for the FLAC__stream_decoder_init_*() functions. + */ +typedef enum { + + FLAC__STREAM_DECODER_INIT_STATUS_OK = 0, + /**< Initialization was successful. */ + + FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER, + /**< The library was not compiled with support for the given container + * format. + */ + + FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS, + /**< A required callback was not supplied. */ + + FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR, + /**< An error occurred allocating memory. */ + + FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE, + /**< fopen() failed in FLAC__stream_decoder_init_file() or + * FLAC__stream_decoder_init_ogg_file(). */ + + FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED + /**< FLAC__stream_decoder_init_*() was called when the decoder was + * already initialized, usually because + * FLAC__stream_decoder_finish() was not called. + */ + +} FLAC__StreamDecoderInitStatus; + +/** Maps a FLAC__StreamDecoderInitStatus to a C string. + * + * Using a FLAC__StreamDecoderInitStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[]; + + +/** Return values for the FLAC__StreamDecoder read callback. + */ +typedef enum { + + FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, + /**< The read was OK and decoding can continue. */ + + FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, + /**< The read was attempted while at the end of the stream. Note that + * the client must only return this value when the read callback was + * called when already at the end of the stream. Otherwise, if the read + * itself moves to the end of the stream, the client should still return + * the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on + * the next read callback it should return + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count + * of \c 0. + */ + + FLAC__STREAM_DECODER_READ_STATUS_ABORT + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + +} FLAC__StreamDecoderReadStatus; + +/** Maps a FLAC__StreamDecoderReadStatus to a C string. + * + * Using a FLAC__StreamDecoderReadStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[]; + + +/** Return values for the FLAC__StreamDecoder seek callback. + */ +typedef enum { + + FLAC__STREAM_DECODER_SEEK_STATUS_OK, + /**< The seek was OK and decoding can continue. */ + + FLAC__STREAM_DECODER_SEEK_STATUS_ERROR, + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + + FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED + /**< Client does not support seeking. */ + +} FLAC__StreamDecoderSeekStatus; + +/** Maps a FLAC__StreamDecoderSeekStatus to a C string. + * + * Using a FLAC__StreamDecoderSeekStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[]; + + +/** Return values for the FLAC__StreamDecoder tell callback. + */ +typedef enum { + + FLAC__STREAM_DECODER_TELL_STATUS_OK, + /**< The tell was OK and decoding can continue. */ + + FLAC__STREAM_DECODER_TELL_STATUS_ERROR, + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + + FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED + /**< Client does not support telling the position. */ + +} FLAC__StreamDecoderTellStatus; + +/** Maps a FLAC__StreamDecoderTellStatus to a C string. + * + * Using a FLAC__StreamDecoderTellStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[]; + + +/** Return values for the FLAC__StreamDecoder length callback. + */ +typedef enum { + + FLAC__STREAM_DECODER_LENGTH_STATUS_OK, + /**< The length call was OK and decoding can continue. */ + + FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR, + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + + FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED + /**< Client does not support reporting the length. */ + +} FLAC__StreamDecoderLengthStatus; + +/** Maps a FLAC__StreamDecoderLengthStatus to a C string. + * + * Using a FLAC__StreamDecoderLengthStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[]; + + +/** Return values for the FLAC__StreamDecoder write callback. + */ +typedef enum { + + FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, + /**< The write was OK and decoding can continue. */ + + FLAC__STREAM_DECODER_WRITE_STATUS_ABORT + /**< An unrecoverable error occurred. The decoder will return from the process call. */ + +} FLAC__StreamDecoderWriteStatus; + +/** Maps a FLAC__StreamDecoderWriteStatus to a C string. + * + * Using a FLAC__StreamDecoderWriteStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[]; + + +/** Possible values passed back to the FLAC__StreamDecoder error callback. + * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch- + * all. The rest could be caused by bad sync (false synchronization on + * data that is not the start of a frame) or corrupted data. The error + * itself is the decoder's best guess at what happened assuming a correct + * sync. For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER + * could be caused by a correct sync on the start of a frame, but some + * data in the frame header was corrupted. Or it could be the result of + * syncing on a point the stream that looked like the starting of a frame + * but was not. \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM + * could be because the decoder encountered a valid frame made by a future + * version of the encoder which it cannot parse, or because of a false + * sync making it appear as though an encountered frame was generated by + * a future encoder. + */ +typedef enum { + + FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, + /**< An error in the stream caused the decoder to lose synchronization. */ + + FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, + /**< The decoder encountered a corrupted frame header. */ + + FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH, + /**< The frame's data did not match the CRC in the footer. */ + + FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM + /**< The decoder encountered reserved fields in use in the stream. */ + +} FLAC__StreamDecoderErrorStatus; + +/** Maps a FLAC__StreamDecoderErrorStatus to a C string. + * + * Using a FLAC__StreamDecoderErrorStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[]; + + +/*********************************************************************** + * + * class FLAC__StreamDecoder + * + ***********************************************************************/ + +struct FLAC__StreamDecoderProtected; +struct FLAC__StreamDecoderPrivate; +/** The opaque structure definition for the stream decoder type. + * See the \link flac_stream_decoder stream decoder module \endlink + * for a detailed description. + */ +typedef struct { + struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */ + struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */ +} FLAC__StreamDecoder; + +/** Signature for the read callback. + * + * A function pointer matching this signature must be passed to + * FLAC__stream_decoder_init*_stream(). The supplied function will be + * called when the decoder needs more input data. The address of the + * buffer to be filled is supplied, along with the number of bytes the + * buffer can hold. The callback may choose to supply less data and + * modify the byte count but must be careful not to overflow the buffer. + * The callback then returns a status code chosen from + * FLAC__StreamDecoderReadStatus. + * + * Here is an example of a read callback for stdio streams: + * \code + * FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * if(*bytes > 0) { + * *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file); + * if(ferror(file)) + * return FLAC__STREAM_DECODER_READ_STATUS_ABORT; + * else if(*bytes == 0) + * return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM; + * else + * return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE; + * } + * else + * return FLAC__STREAM_DECODER_READ_STATUS_ABORT; + * } + * \endcode + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param buffer A pointer to a location for the callee to store + * data to be decoded. + * \param bytes A pointer to the size of the buffer. On entry + * to the callback, it contains the maximum number + * of bytes that may be stored in \a buffer. The + * callee must set it to the actual number of bytes + * stored (0 in case of error or end-of-stream) before + * returning. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__StreamDecoderReadStatus + * The callee's return status. Note that the callback should return + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if + * zero bytes were read and there is no more data to be read. + */ +typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data); + +/** Signature for the seek callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_decoder_init*_stream(). The supplied function will be + * called when the decoder needs to seek the input stream. The decoder + * will pass the absolute byte offset to seek to, 0 meaning the + * beginning of the stream. + * + * Here is an example of a seek callback for stdio streams: + * \code + * FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * if(file == stdin) + * return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED; + * else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0) + * return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR; + * else + * return FLAC__STREAM_DECODER_SEEK_STATUS_OK; + * } + * \endcode + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param absolute_byte_offset The offset from the beginning of the stream + * to seek to. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__StreamDecoderSeekStatus + * The callee's return status. + */ +typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data); + +/** Signature for the tell callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_decoder_init*_stream(). The supplied function will be + * called when the decoder wants to know the current position of the + * stream. The callback should return the byte offset from the + * beginning of the stream. + * + * Here is an example of a tell callback for stdio streams: + * \code + * FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * off_t pos; + * if(file == stdin) + * return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED; + * else if((pos = ftello(file)) < 0) + * return FLAC__STREAM_DECODER_TELL_STATUS_ERROR; + * else { + * *absolute_byte_offset = (FLAC__uint64)pos; + * return FLAC__STREAM_DECODER_TELL_STATUS_OK; + * } + * } + * \endcode + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param absolute_byte_offset A pointer to storage for the current offset + * from the beginning of the stream. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__StreamDecoderTellStatus + * The callee's return status. + */ +typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data); + +/** Signature for the length callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_decoder_init*_stream(). The supplied function will be + * called when the decoder wants to know the total length of the stream + * in bytes. + * + * Here is an example of a length callback for stdio streams: + * \code + * FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * struct stat filestats; + * + * if(file == stdin) + * return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED; + * else if(fstat(fileno(file), &filestats) != 0) + * return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR; + * else { + * *stream_length = (FLAC__uint64)filestats.st_size; + * return FLAC__STREAM_DECODER_LENGTH_STATUS_OK; + * } + * } + * \endcode + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param stream_length A pointer to storage for the length of the stream + * in bytes. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__StreamDecoderLengthStatus + * The callee's return status. + */ +typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data); + +/** Signature for the EOF callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_decoder_init*_stream(). The supplied function will be + * called when the decoder needs to know if the end of the stream has + * been reached. + * + * Here is an example of a EOF callback for stdio streams: + * FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data) + * \code + * { + * FILE *file = ((MyClientData*)client_data)->file; + * return feof(file)? true : false; + * } + * \endcode + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__bool + * \c true if the currently at the end of the stream, else \c false. + */ +typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data); + +/** Signature for the write callback. + * + * A function pointer matching this signature must be passed to one of + * the FLAC__stream_decoder_init_*() functions. + * The supplied function will be called when the decoder has decoded a + * single audio frame. The decoder will pass the frame metadata as well + * as an array of pointers (one for each channel) pointing to the + * decoded audio. + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param frame The description of the decoded frame. See + * FLAC__Frame. + * \param buffer An array of pointers to decoded channels of data. + * Each pointer will point to an array of signed + * samples of length \a frame->header.blocksize. + * Channels will be ordered according to the FLAC + * specification; see the documentation for the + * frame header. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + * \retval FLAC__StreamDecoderWriteStatus + * The callee's return status. + */ +typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data); + +/** Signature for the metadata callback. + * + * A function pointer matching this signature must be passed to one of + * the FLAC__stream_decoder_init_*() functions. + * The supplied function will be called when the decoder has decoded a + * metadata block. In a valid FLAC file there will always be one + * \c STREAMINFO block, followed by zero or more other metadata blocks. + * These will be supplied by the decoder in the same order as they + * appear in the stream and always before the first audio frame (i.e. + * write callback). The metadata block that is passed in must not be + * modified, and it doesn't live beyond the callback, so you should make + * a copy of it with FLAC__metadata_object_clone() if you will need it + * elsewhere. Since metadata blocks can potentially be large, by + * default the decoder only calls the metadata callback for the + * \c STREAMINFO block; you can instruct the decoder to pass or filter + * other blocks with FLAC__stream_decoder_set_metadata_*() calls. + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param metadata The decoded metadata block. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + */ +typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data); + +/** Signature for the error callback. + * + * A function pointer matching this signature must be passed to one of + * the FLAC__stream_decoder_init_*() functions. + * The supplied function will be called whenever an error occurs during + * decoding. + * + * \note In general, FLAC__StreamDecoder functions which change the + * state should not be called on the \a decoder while in the callback. + * + * \param decoder The decoder instance calling the callback. + * \param status The error encountered by the decoder. + * \param client_data The callee's client data set through + * FLAC__stream_decoder_init_*(). + */ +typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data); + + +/*********************************************************************** + * + * Class constructor/destructor + * + ***********************************************************************/ + +/** Create a new stream decoder instance. The instance is created with + * default settings; see the individual FLAC__stream_decoder_set_*() + * functions for each setting's default. + * + * \retval FLAC__StreamDecoder* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new(void); + +/** Free a decoder instance. Deletes the object pointed to by \a decoder. + * + * \param decoder A pointer to an existing decoder. + * \assert + * \code decoder != NULL \endcode + */ +FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder); + + +/*********************************************************************** + * + * Public class method prototypes + * + ***********************************************************************/ + +/** Set the serial number for the FLAC stream within the Ogg container. + * The default behavior is to use the serial number of the first Ogg + * page. Setting a serial number here will explicitly specify which + * stream is to be decoded. + * + * \note + * This does not need to be set for native FLAC decoding. + * + * \default \c use serial number of first page + * \param decoder A decoder instance to set. + * \param serial_number See above. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_ogg_serial_number(FLAC__StreamDecoder *decoder, long serial_number); + +/** Set the "MD5 signature checking" flag. If \c true, the decoder will + * compute the MD5 signature of the unencoded audio data while decoding + * and compare it to the signature from the STREAMINFO block, if it + * exists, during FLAC__stream_decoder_finish(). + * + * MD5 signature checking will be turned off (until the next + * FLAC__stream_decoder_reset()) if there is no signature in the + * STREAMINFO block or when a seek is attempted. + * + * Clients that do not use the MD5 check should leave this off to speed + * up decoding. + * + * \default \c false + * \param decoder A decoder instance to set. + * \param value Flag value (see above). + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value); + +/** Direct the decoder to pass on all metadata blocks of type \a type. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \param type See above. + * \assert + * \code decoder != NULL \endcode + * \a type is valid + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type); + +/** Direct the decoder to pass on all APPLICATION metadata blocks of the + * given \a id. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \param id See above. + * \assert + * \code decoder != NULL \endcode + * \code id != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]); + +/** Direct the decoder to pass on all metadata blocks of any type. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder); + +/** Direct the decoder to filter out all metadata blocks of type \a type. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \param type See above. + * \assert + * \code decoder != NULL \endcode + * \a type is valid + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type); + +/** Direct the decoder to filter out all APPLICATION metadata blocks of + * the given \a id. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \param id See above. + * \assert + * \code decoder != NULL \endcode + * \code id != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]); + +/** Direct the decoder to filter out all metadata blocks of any type. + * + * \default By default, only the \c STREAMINFO block is returned via the + * metadata callback. + * \param decoder A decoder instance to set. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if the decoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder); + +/** Get the current decoder state. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The current decoder state. + */ +FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder); + +/** Get the current decoder state as a C string. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval const char * + * The decoder state as a C string. Do not modify the contents. + */ +FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *decoder); + +/** Get the "MD5 signature checking" flag. + * This is the value of the setting, not whether or not the decoder is + * currently checking the MD5 (remember, it can be turned off automatically + * by a seek). When the decoder is reset the flag will be restored to the + * value returned by this function. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * See above. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder); + +/** Get the total number of samples in the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the \c STREAMINFO block. A value of \c 0 means "unknown". + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval unsigned + * See above. + */ +FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__StreamDecoder *decoder); + +/** Get the current number of channels in the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the most recently decoded frame header. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval unsigned + * See above. + */ +FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder); + +/** Get the current channel assignment in the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the most recently decoded frame header. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__ChannelAssignment + * See above. + */ +FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder); + +/** Get the current sample resolution in the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the most recently decoded frame header. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval unsigned + * See above. + */ +FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder); + +/** Get the current sample rate in Hz of the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the most recently decoded frame header. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval unsigned + * See above. + */ +FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder); + +/** Get the current blocksize of the stream being decoded. + * Will only be valid after decoding has started and will contain the + * value from the most recently decoded frame header. + * + * \param decoder A decoder instance to query. + * \assert + * \code decoder != NULL \endcode + * \retval unsigned + * See above. + */ +FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder); + +/** Returns the decoder's current read position within the stream. + * The position is the byte offset from the start of the stream. + * Bytes before this position have been fully decoded. Note that + * there may still be undecoded bytes in the decoder's read FIFO. + * The returned position is correct even after a seek. + * + * \warning This function currently only works for native FLAC, + * not Ogg FLAC streams. + * + * \param decoder A decoder instance to query. + * \param position Address at which to return the desired position. + * \assert + * \code decoder != NULL \endcode + * \code position != NULL \endcode + * \retval FLAC__bool + * \c true if successful, \c false if the stream is not native FLAC, + * or there was an error from the 'tell' callback or it returned + * \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position); + +/** Initialize the decoder instance to decode native FLAC streams. + * + * This flavor of initialization sets up the decoder to decode from a + * native FLAC stream. I/O is performed via callbacks to the client. + * For decoding from a plain file via filename or open FILE*, + * FLAC__stream_decoder_init_file() and FLAC__stream_decoder_init_FILE() + * provide a simpler interface. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \param decoder An uninitialized decoder instance. + * \param read_callback See FLAC__StreamDecoderReadCallback. This + * pointer must not be \c NULL. + * \param seek_callback See FLAC__StreamDecoderSeekCallback. This + * pointer may be \c NULL if seeking is not + * supported. If \a seek_callback is not \c NULL then a + * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied. + * Alternatively, a dummy seek callback that just + * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param tell_callback See FLAC__StreamDecoderTellCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a tell_callback must also be supplied. + * Alternatively, a dummy tell callback that just + * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param length_callback See FLAC__StreamDecoderLengthCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a length_callback must also be supplied. + * Alternatively, a dummy length callback that just + * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param eof_callback See FLAC__StreamDecoderEofCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a eof_callback must also be supplied. + * Alternatively, a dummy length callback that just + * returns \c false + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream( + FLAC__StreamDecoder *decoder, + FLAC__StreamDecoderReadCallback read_callback, + FLAC__StreamDecoderSeekCallback seek_callback, + FLAC__StreamDecoderTellCallback tell_callback, + FLAC__StreamDecoderLengthCallback length_callback, + FLAC__StreamDecoderEofCallback eof_callback, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Initialize the decoder instance to decode Ogg FLAC streams. + * + * This flavor of initialization sets up the decoder to decode from a + * FLAC stream in an Ogg container. I/O is performed via callbacks to the + * client. For decoding from a plain file via filename or open FILE*, + * FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_FILE() + * provide a simpler interface. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \note Support for Ogg FLAC in the library is optional. If this + * library has been built without support for Ogg FLAC, this function + * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER. + * + * \param decoder An uninitialized decoder instance. + * \param read_callback See FLAC__StreamDecoderReadCallback. This + * pointer must not be \c NULL. + * \param seek_callback See FLAC__StreamDecoderSeekCallback. This + * pointer may be \c NULL if seeking is not + * supported. If \a seek_callback is not \c NULL then a + * \a tell_callback, \a length_callback, and \a eof_callback must also be supplied. + * Alternatively, a dummy seek callback that just + * returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param tell_callback See FLAC__StreamDecoderTellCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a tell_callback must also be supplied. + * Alternatively, a dummy tell callback that just + * returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param length_callback See FLAC__StreamDecoderLengthCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a length_callback must also be supplied. + * Alternatively, a dummy length callback that just + * returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param eof_callback See FLAC__StreamDecoderEofCallback. This + * pointer may be \c NULL if not supported by the client. If + * \a seek_callback is not \c NULL then a + * \a eof_callback must also be supplied. + * Alternatively, a dummy length callback that just + * returns \c false + * may also be supplied, all though this is slightly + * less efficient for the decoder. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream( + FLAC__StreamDecoder *decoder, + FLAC__StreamDecoderReadCallback read_callback, + FLAC__StreamDecoderSeekCallback seek_callback, + FLAC__StreamDecoderTellCallback tell_callback, + FLAC__StreamDecoderLengthCallback length_callback, + FLAC__StreamDecoderEofCallback eof_callback, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Initialize the decoder instance to decode native FLAC files. + * + * This flavor of initialization sets up the decoder to decode from a + * plain native FLAC file. For non-stdio streams, you must use + * FLAC__stream_decoder_init_stream() and provide callbacks for the I/O. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \param decoder An uninitialized decoder instance. + * \param file An open FLAC file. The file should have been + * opened with mode \c "rb" and rewound. The file + * becomes owned by the decoder and should not be + * manipulated by the client while decoding. + * Unless \a file is \c stdin, it will be closed + * when FLAC__stream_decoder_finish() is called. + * Note however that seeking will not work when + * decoding from \c stdout since it is not seekable. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \code file != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE( + FLAC__StreamDecoder *decoder, + FILE *file, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Initialize the decoder instance to decode Ogg FLAC files. + * + * This flavor of initialization sets up the decoder to decode from a + * plain Ogg FLAC file. For non-stdio streams, you must use + * FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \note Support for Ogg FLAC in the library is optional. If this + * library has been built without support for Ogg FLAC, this function + * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER. + * + * \param decoder An uninitialized decoder instance. + * \param file An open FLAC file. The file should have been + * opened with mode \c "rb" and rewound. The file + * becomes owned by the decoder and should not be + * manipulated by the client while decoding. + * Unless \a file is \c stdin, it will be closed + * when FLAC__stream_decoder_finish() is called. + * Note however that seeking will not work when + * decoding from \c stdout since it is not seekable. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \code file != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE( + FLAC__StreamDecoder *decoder, + FILE *file, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Initialize the decoder instance to decode native FLAC files. + * + * This flavor of initialization sets up the decoder to decode from a plain + * native FLAC file. If POSIX fopen() semantics are not sufficient, (for + * example, with Unicode filenames on Windows), you must use + * FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream() + * and provide callbacks for the I/O. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \param decoder An uninitialized decoder instance. + * \param filename The name of the file to decode from. The file will + * be opened with fopen(). Use \c NULL to decode from + * \c stdin. Note that \c stdin is not seekable. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file( + FLAC__StreamDecoder *decoder, + const char *filename, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Initialize the decoder instance to decode Ogg FLAC files. + * + * This flavor of initialization sets up the decoder to decode from a plain + * Ogg FLAC file. If POSIX fopen() semantics are not sufficient, (for + * example, with Unicode filenames on Windows), you must use + * FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream() + * and provide callbacks for the I/O. + * + * This function should be called after FLAC__stream_decoder_new() and + * FLAC__stream_decoder_set_*() but before any of the + * FLAC__stream_decoder_process_*() functions. Will set and return the + * decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA + * if initialization succeeded. + * + * \note Support for Ogg FLAC in the library is optional. If this + * library has been built without support for Ogg FLAC, this function + * will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER. + * + * \param decoder An uninitialized decoder instance. + * \param filename The name of the file to decode from. The file will + * be opened with fopen(). Use \c NULL to decode from + * \c stdin. Note that \c stdin is not seekable. + * \param write_callback See FLAC__StreamDecoderWriteCallback. This + * pointer must not be \c NULL. + * \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This + * pointer may be \c NULL if the callback is not + * desired. + * \param error_callback See FLAC__StreamDecoderErrorCallback. This + * pointer must not be \c NULL. + * \param client_data This value will be supplied to callbacks in their + * \a client_data argument. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__StreamDecoderInitStatus + * \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; + * see FLAC__StreamDecoderInitStatus for the meanings of other return values. + */ +FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file( + FLAC__StreamDecoder *decoder, + const char *filename, + FLAC__StreamDecoderWriteCallback write_callback, + FLAC__StreamDecoderMetadataCallback metadata_callback, + FLAC__StreamDecoderErrorCallback error_callback, + void *client_data +); + +/** Finish the decoding process. + * Flushes the decoding buffer, releases resources, resets the decoder + * settings to their defaults, and returns the decoder state to + * FLAC__STREAM_DECODER_UNINITIALIZED. + * + * In the event of a prematurely-terminated decode, it is not strictly + * necessary to call this immediately before FLAC__stream_decoder_delete() + * but it is good practice to match every FLAC__stream_decoder_init_*() + * with a FLAC__stream_decoder_finish(). + * + * \param decoder An uninitialized decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if MD5 checking is on AND a STREAMINFO block was available + * AND the MD5 signature in the STREAMINFO block was non-zero AND the + * signature does not match the one computed by the decoder; else + * \c true. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder); + +/** Flush the stream input. + * The decoder's input buffer will be cleared and the state set to + * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn + * off MD5 checking. + * + * \param decoder A decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c true if successful, else \c false if a memory allocation + * error occurs (in which case the state will be set to + * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder); + +/** Reset the decoding process. + * The decoder's input buffer will be cleared and the state set to + * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to + * FLAC__stream_decoder_finish() except that the settings are + * preserved; there is no need to call FLAC__stream_decoder_init_*() + * before decoding again. MD5 checking will be restored to its original + * setting. + * + * If the decoder is seekable, or was initialized with + * FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(), + * the decoder will also attempt to seek to the beginning of the file. + * If this rewind fails, this function will return \c false. It follows + * that FLAC__stream_decoder_reset() cannot be used when decoding from + * \c stdin. + * + * If the decoder was initialized with FLAC__stream_encoder_init*_stream() + * and is not seekable (i.e. no seek callback was provided or the seek + * callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it + * is the duty of the client to start feeding data from the beginning of + * the stream on the next FLAC__stream_decoder_process() or + * FLAC__stream_decoder_process_interleaved() call. + * + * \param decoder A decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c true if successful, else \c false if a memory allocation occurs + * (in which case the state will be set to + * \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error + * occurs (the state will be unchanged). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder); + +/** Decode one metadata block or audio frame. + * This version instructs the decoder to decode a either a single metadata + * block or a single frame and stop, unless the callbacks return a fatal + * error or the read callback returns + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. + * + * As the decoder needs more input it will call the read callback. + * Depending on what was decoded, the metadata or write callback will be + * called with the decoded metadata block or audio frame. + * + * Unless there is a fatal read error or end of stream, this function + * will return once one whole frame is decoded. In other words, if the + * stream is not synchronized or points to a corrupt frame header, the + * decoder will continue to try and resync until it gets to a valid + * frame, then decode one frame, then return. If the decoder points to + * a frame whose frame CRC in the frame footer does not match the + * computed frame CRC, this function will issue a + * FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the + * error callback, and return, having decoded one complete, although + * corrupt, frame. (Such corrupted frames are sent as silence of the + * correct length to the write callback.) + * + * \param decoder An initialized decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if any fatal read, write, or memory allocation error + * occurred (meaning decoding must stop), else \c true; for more + * information about the decoder, check the decoder state with + * FLAC__stream_decoder_get_state(). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder); + +/** Decode until the end of the metadata. + * This version instructs the decoder to decode from the current position + * and continue until all the metadata has been read, or until the + * callbacks return a fatal error or the read callback returns + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. + * + * As the decoder needs more input it will call the read callback. + * As each metadata block is decoded, the metadata callback will be called + * with the decoded metadata. + * + * \param decoder An initialized decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if any fatal read, write, or memory allocation error + * occurred (meaning decoding must stop), else \c true; for more + * information about the decoder, check the decoder state with + * FLAC__stream_decoder_get_state(). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder); + +/** Decode until the end of the stream. + * This version instructs the decoder to decode from the current position + * and continue until the end of stream (the read callback returns + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the + * callbacks return a fatal error. + * + * As the decoder needs more input it will call the read callback. + * As each metadata block and frame is decoded, the metadata or write + * callback will be called with the decoded metadata or frame. + * + * \param decoder An initialized decoder instance. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if any fatal read, write, or memory allocation error + * occurred (meaning decoding must stop), else \c true; for more + * information about the decoder, check the decoder state with + * FLAC__stream_decoder_get_state(). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder); + +/** Skip one audio frame. + * This version instructs the decoder to 'skip' a single frame and stop, + * unless the callbacks return a fatal error or the read callback returns + * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM. + * + * The decoding flow is the same as what occurs when + * FLAC__stream_decoder_process_single() is called to process an audio + * frame, except that this function does not decode the parsed data into + * PCM or call the write callback. The integrity of the frame is still + * checked the same way as in the other process functions. + * + * This function will return once one whole frame is skipped, in the + * same way that FLAC__stream_decoder_process_single() will return once + * one whole frame is decoded. + * + * This function can be used in more quickly determining FLAC frame + * boundaries when decoding of the actual data is not needed, for + * example when an application is separating a FLAC stream into frames + * for editing or storing in a container. To do this, the application + * can use FLAC__stream_decoder_skip_single_frame() to quickly advance + * to the next frame, then use + * FLAC__stream_decoder_get_decode_position() to find the new frame + * boundary. + * + * This function should only be called when the stream has advanced + * past all the metadata, otherwise it will return \c false. + * + * \param decoder An initialized decoder instance not in a metadata + * state. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c false if any fatal read, write, or memory allocation error + * occurred (meaning decoding must stop), or if the decoder + * is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or + * FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more + * information about the decoder, check the decoder state with + * FLAC__stream_decoder_get_state(). + */ +FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder); + +/** Flush the input and seek to an absolute sample. + * Decoding will resume at the given sample. Note that because of + * this, the next write callback may contain a partial block. The + * client must support seeking the input or this function will fail + * and return \c false. Furthermore, if the decoder state is + * \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed + * with FLAC__stream_decoder_flush() or reset with + * FLAC__stream_decoder_reset() before decoding can continue. + * + * \param decoder A decoder instance. + * \param sample The target sample number to seek to. + * \assert + * \code decoder != NULL \endcode + * \retval FLAC__bool + * \c true if successful, else \c false. + */ +FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample); + +/* \} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/flac/include/FLAC/stream_encoder.h b/flac/include/FLAC/stream_encoder.h new file mode 100644 index 00000000..efc213ae --- /dev/null +++ b/flac/include/FLAC/stream_encoder.h @@ -0,0 +1,1790 @@ +/* libFLAC - Free Lossless Audio Codec library + * Copyright (C) 2000-2009 Josh Coalson + * Copyright (C) 2011-2014 Xiph.Org Foundation + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * - Neither the name of the Xiph.org Foundation nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef FLAC__STREAM_ENCODER_H +#define FLAC__STREAM_ENCODER_H + +#include /* for FILE */ +#include "export.h" +#include "format.h" +#include "stream_decoder.h" + +#ifdef __cplusplus +extern "C" { +#endif + + +/** \file include/FLAC/stream_encoder.h + * + * \brief + * This module contains the functions which implement the stream + * encoder. + * + * See the detailed documentation in the + * \link flac_stream_encoder stream encoder \endlink module. + */ + +/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces + * \ingroup flac + * + * \brief + * This module describes the encoder layers provided by libFLAC. + * + * The stream encoder can be used to encode complete streams either to the + * client via callbacks, or directly to a file, depending on how it is + * initialized. When encoding via callbacks, the client provides a write + * callback which will be called whenever FLAC data is ready to be written. + * If the client also supplies a seek callback, the encoder will also + * automatically handle the writing back of metadata discovered while + * encoding, like stream info, seek points offsets, etc. When encoding to + * a file, the client needs only supply a filename or open \c FILE* and an + * optional progress callback for periodic notification of progress; the + * write and seek callbacks are supplied internally. For more info see the + * \link flac_stream_encoder stream encoder \endlink module. + */ + +/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface + * \ingroup flac_encoder + * + * \brief + * This module contains the functions which implement the stream + * encoder. + * + * The stream encoder can encode to native FLAC, and optionally Ogg FLAC + * (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files. + * + * The basic usage of this encoder is as follows: + * - The program creates an instance of an encoder using + * FLAC__stream_encoder_new(). + * - The program overrides the default settings using + * FLAC__stream_encoder_set_*() functions. At a minimum, the following + * functions should be called: + * - FLAC__stream_encoder_set_channels() + * - FLAC__stream_encoder_set_bits_per_sample() + * - FLAC__stream_encoder_set_sample_rate() + * - FLAC__stream_encoder_set_ogg_serial_number() (if encoding to Ogg FLAC) + * - FLAC__stream_encoder_set_total_samples_estimate() (if known) + * - If the application wants to control the compression level or set its own + * metadata, then the following should also be called: + * - FLAC__stream_encoder_set_compression_level() + * - FLAC__stream_encoder_set_verify() + * - FLAC__stream_encoder_set_metadata() + * - The rest of the set functions should only be called if the client needs + * exact control over how the audio is compressed; thorough understanding + * of the FLAC format is necessary to achieve good results. + * - The program initializes the instance to validate the settings and + * prepare for encoding using + * - FLAC__stream_encoder_init_stream() or FLAC__stream_encoder_init_FILE() + * or FLAC__stream_encoder_init_file() for native FLAC + * - FLAC__stream_encoder_init_ogg_stream() or FLAC__stream_encoder_init_ogg_FILE() + * or FLAC__stream_encoder_init_ogg_file() for Ogg FLAC + * - The program calls FLAC__stream_encoder_process() or + * FLAC__stream_encoder_process_interleaved() to encode data, which + * subsequently calls the callbacks when there is encoder data ready + * to be written. + * - The program finishes the encoding with FLAC__stream_encoder_finish(), + * which causes the encoder to encode any data still in its input pipe, + * update the metadata with the final encoding statistics if output + * seeking is possible, and finally reset the encoder to the + * uninitialized state. + * - The instance may be used again or deleted with + * FLAC__stream_encoder_delete(). + * + * In more detail, the stream encoder functions similarly to the + * \link flac_stream_decoder stream decoder \endlink, but has fewer + * callbacks and more options. Typically the client will create a new + * instance by calling FLAC__stream_encoder_new(), then set the necessary + * parameters with FLAC__stream_encoder_set_*(), and initialize it by + * calling one of the FLAC__stream_encoder_init_*() functions. + * + * Unlike the decoders, the stream encoder has many options that can + * affect the speed and compression ratio. When setting these parameters + * you should have some basic knowledge of the format (see the + * user-level documentation + * or the formal description). The + * FLAC__stream_encoder_set_*() functions themselves do not validate the + * values as many are interdependent. The FLAC__stream_encoder_init_*() + * functions will do this, so make sure to pay attention to the state + * returned by FLAC__stream_encoder_init_*() to make sure that it is + * FLAC__STREAM_ENCODER_INIT_STATUS_OK. Any parameters that are not set + * before FLAC__stream_encoder_init_*() will take on the defaults from + * the constructor. + * + * There are three initialization functions for native FLAC, one for + * setting up the encoder to encode FLAC data to the client via + * callbacks, and two for encoding directly to a file. + * + * For encoding via callbacks, use FLAC__stream_encoder_init_stream(). + * You must also supply a write callback which will be called anytime + * there is raw encoded data to write. If the client can seek the output + * it is best to also supply seek and tell callbacks, as this allows the + * encoder to go back after encoding is finished to write back + * information that was collected while encoding, like seek point offsets, + * frame sizes, etc. + * + * For encoding directly to a file, use FLAC__stream_encoder_init_FILE() + * or FLAC__stream_encoder_init_file(). Then you must only supply a + * filename or open \c FILE*; the encoder will handle all the callbacks + * internally. You may also supply a progress callback for periodic + * notification of the encoding progress. + * + * There are three similarly-named init functions for encoding to Ogg + * FLAC streams. Check \c FLAC_API_SUPPORTS_OGG_FLAC to find out if the + * library has been built with Ogg support. + * + * The call to FLAC__stream_encoder_init_*() currently will also immediately + * call the write callback several times, once with the \c fLaC signature, + * and once for each encoded metadata block. Note that for Ogg FLAC + * encoding you will usually get at least twice the number of callbacks than + * with native FLAC, one for the Ogg page header and one for the page body. + * + * After initializing the instance, the client may feed audio data to the + * encoder in one of two ways: + * + * - Channel separate, through FLAC__stream_encoder_process() - The client + * will pass an array of pointers to buffers, one for each channel, to + * the encoder, each of the same length. The samples need not be + * block-aligned, but each channel should have the same number of samples. + * - Channel interleaved, through + * FLAC__stream_encoder_process_interleaved() - The client will pass a single + * pointer to data that is channel-interleaved (i.e. channel0_sample0, + * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). + * Again, the samples need not be block-aligned but they must be + * sample-aligned, i.e. the first value should be channel0_sample0 and + * the last value channelN_sampleM. + * + * Note that for either process call, each sample in the buffers should be a + * signed integer, right-justified to the resolution set by + * FLAC__stream_encoder_set_bits_per_sample(). For example, if the resolution + * is 16 bits per sample, the samples should all be in the range [-32768,32767]. + * + * When the client is finished encoding data, it calls + * FLAC__stream_encoder_finish(), which causes the encoder to encode any + * data still in its input pipe, and call the metadata callback with the + * final encoding statistics. Then the instance may be deleted with + * FLAC__stream_encoder_delete() or initialized again to encode another + * stream. + * + * For programs that write their own metadata, but that do not know the + * actual metadata until after encoding, it is advantageous to instruct + * the encoder to write a PADDING block of the correct size, so that + * instead of rewriting the whole stream after encoding, the program can + * just overwrite the PADDING block. If only the maximum size of the + * metadata is known, the program can write a slightly larger padding + * block, then split it after encoding. + * + * Make sure you understand how lengths are calculated. All FLAC metadata + * blocks have a 4 byte header which contains the type and length. This + * length does not include the 4 bytes of the header. See the format page + * for the specification of metadata blocks and their lengths. + * + * \note + * If you are writing the FLAC data to a file via callbacks, make sure it + * is open for update (e.g. mode "w+" for stdio streams). This is because + * after the first encoding pass, the encoder will try to seek back to the + * beginning of the stream, to the STREAMINFO block, to write some data + * there. (If using FLAC__stream_encoder_init*_file() or + * FLAC__stream_encoder_init*_FILE(), the file is managed internally.) + * + * \note + * The "set" functions may only be called when the encoder is in the + * state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after + * FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but + * before FLAC__stream_encoder_init_*(). If this is the case they will + * return \c true, otherwise \c false. + * + * \note + * FLAC__stream_encoder_finish() resets all settings to the constructor + * defaults. + * + * \{ + */ + + +/** State values for a FLAC__StreamEncoder. + * + * The encoder's state can be obtained by calling FLAC__stream_encoder_get_state(). + * + * If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK + * or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and + * must be deleted with FLAC__stream_encoder_delete(). + */ +typedef enum { + + FLAC__STREAM_ENCODER_OK = 0, + /**< The encoder is in the normal OK state and samples can be processed. */ + + FLAC__STREAM_ENCODER_UNINITIALIZED, + /**< The encoder is in the uninitialized state; one of the + * FLAC__stream_encoder_init_*() functions must be called before samples + * can be processed. + */ + + FLAC__STREAM_ENCODER_OGG_ERROR, + /**< An error occurred in the underlying Ogg layer. */ + + FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR, + /**< An error occurred in the underlying verify stream decoder; + * check FLAC__stream_encoder_get_verify_decoder_state(). + */ + + FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA, + /**< The verify decoder detected a mismatch between the original + * audio signal and the decoded audio signal. + */ + + FLAC__STREAM_ENCODER_CLIENT_ERROR, + /**< One of the callbacks returned a fatal error. */ + + FLAC__STREAM_ENCODER_IO_ERROR, + /**< An I/O error occurred while opening/reading/writing a file. + * Check \c errno. + */ + + FLAC__STREAM_ENCODER_FRAMING_ERROR, + /**< An error occurred while writing the stream; usually, the + * write_callback returned an error. + */ + + FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR + /**< Memory allocation failed. */ + +} FLAC__StreamEncoderState; + +/** Maps a FLAC__StreamEncoderState to a C string. + * + * Using a FLAC__StreamEncoderState as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderStateString[]; + + +/** Possible return values for the FLAC__stream_encoder_init_*() functions. + */ +typedef enum { + + FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0, + /**< Initialization was successful. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR, + /**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_UNSUPPORTED_CONTAINER, + /**< The library was not compiled with support for the given container + * format. + */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS, + /**< A required callback was not supplied. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS, + /**< The encoder has an invalid setting for number of channels. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE, + /**< The encoder has an invalid setting for bits-per-sample. + * FLAC supports 4-32 bps but the reference encoder currently supports + * only up to 24 bps. + */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE, + /**< The encoder has an invalid setting for the input sample rate. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE, + /**< The encoder has an invalid setting for the block size. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER, + /**< The encoder has an invalid setting for the maximum LPC order. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION, + /**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER, + /**< The specified block size is less than the maximum LPC order. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE, + /**< The encoder is bound to the Subset but other settings violate it. */ + + FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA, + /**< The metadata input to the encoder is invalid, in one of the following ways: + * - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0 + * - One of the metadata blocks contains an undefined type + * - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal() + * - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal() + * - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block + */ + + FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED + /**< FLAC__stream_encoder_init_*() was called when the encoder was + * already initialized, usually because + * FLAC__stream_encoder_finish() was not called. + */ + +} FLAC__StreamEncoderInitStatus; + +/** Maps a FLAC__StreamEncoderInitStatus to a C string. + * + * Using a FLAC__StreamEncoderInitStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[]; + + +/** Return values for the FLAC__StreamEncoder read callback. + */ +typedef enum { + + FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE, + /**< The read was OK and decoding can continue. */ + + FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM, + /**< The read was attempted at the end of the stream. */ + + FLAC__STREAM_ENCODER_READ_STATUS_ABORT, + /**< An unrecoverable error occurred. */ + + FLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED + /**< Client does not support reading back from the output. */ + +} FLAC__StreamEncoderReadStatus; + +/** Maps a FLAC__StreamEncoderReadStatus to a C string. + * + * Using a FLAC__StreamEncoderReadStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderReadStatusString[]; + + +/** Return values for the FLAC__StreamEncoder write callback. + */ +typedef enum { + + FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0, + /**< The write was OK and encoding can continue. */ + + FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR + /**< An unrecoverable error occurred. The encoder will return from the process call. */ + +} FLAC__StreamEncoderWriteStatus; + +/** Maps a FLAC__StreamEncoderWriteStatus to a C string. + * + * Using a FLAC__StreamEncoderWriteStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[]; + + +/** Return values for the FLAC__StreamEncoder seek callback. + */ +typedef enum { + + FLAC__STREAM_ENCODER_SEEK_STATUS_OK, + /**< The seek was OK and encoding can continue. */ + + FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR, + /**< An unrecoverable error occurred. */ + + FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED + /**< Client does not support seeking. */ + +} FLAC__StreamEncoderSeekStatus; + +/** Maps a FLAC__StreamEncoderSeekStatus to a C string. + * + * Using a FLAC__StreamEncoderSeekStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[]; + + +/** Return values for the FLAC__StreamEncoder tell callback. + */ +typedef enum { + + FLAC__STREAM_ENCODER_TELL_STATUS_OK, + /**< The tell was OK and encoding can continue. */ + + FLAC__STREAM_ENCODER_TELL_STATUS_ERROR, + /**< An unrecoverable error occurred. */ + + FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED + /**< Client does not support seeking. */ + +} FLAC__StreamEncoderTellStatus; + +/** Maps a FLAC__StreamEncoderTellStatus to a C string. + * + * Using a FLAC__StreamEncoderTellStatus as the index to this array + * will give the string equivalent. The contents should not be modified. + */ +extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[]; + + +/*********************************************************************** + * + * class FLAC__StreamEncoder + * + ***********************************************************************/ + +struct FLAC__StreamEncoderProtected; +struct FLAC__StreamEncoderPrivate; +/** The opaque structure definition for the stream encoder type. + * See the \link flac_stream_encoder stream encoder module \endlink + * for a detailed description. + */ +typedef struct { + struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */ + struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */ +} FLAC__StreamEncoder; + +/** Signature for the read callback. + * + * A function pointer matching this signature must be passed to + * FLAC__stream_encoder_init_ogg_stream() if seeking is supported. + * The supplied function will be called when the encoder needs to read back + * encoded data. This happens during the metadata callback, when the encoder + * has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered + * while encoding. The address of the buffer to be filled is supplied, along + * with the number of bytes the buffer can hold. The callback may choose to + * supply less data and modify the byte count but must be careful not to + * overflow the buffer. The callback then returns a status code chosen from + * FLAC__StreamEncoderReadStatus. + * + * Here is an example of a read callback for stdio streams: + * \code + * FLAC__StreamEncoderReadStatus read_cb(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * if(*bytes > 0) { + * *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file); + * if(ferror(file)) + * return FLAC__STREAM_ENCODER_READ_STATUS_ABORT; + * else if(*bytes == 0) + * return FLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM; + * else + * return FLAC__STREAM_ENCODER_READ_STATUS_CONTINUE; + * } + * else + * return FLAC__STREAM_ENCODER_READ_STATUS_ABORT; + * } + * \endcode + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param buffer A pointer to a location for the callee to store + * data to be encoded. + * \param bytes A pointer to the size of the buffer. On entry + * to the callback, it contains the maximum number + * of bytes that may be stored in \a buffer. The + * callee must set it to the actual number of bytes + * stored (0 in case of error or end-of-stream) before + * returning. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_set_client_data(). + * \retval FLAC__StreamEncoderReadStatus + * The callee's return status. + */ +typedef FLAC__StreamEncoderReadStatus (*FLAC__StreamEncoderReadCallback)(const FLAC__StreamEncoder *encoder, FLAC__byte buffer[], size_t *bytes, void *client_data); + +/** Signature for the write callback. + * + * A function pointer matching this signature must be passed to + * FLAC__stream_encoder_init*_stream(). The supplied function will be called + * by the encoder anytime there is raw encoded data ready to write. It may + * include metadata mixed with encoded audio frames and the data is not + * guaranteed to be aligned on frame or metadata block boundaries. + * + * The only duty of the callback is to write out the \a bytes worth of data + * in \a buffer to the current position in the output stream. The arguments + * \a samples and \a current_frame are purely informational. If \a samples + * is greater than \c 0, then \a current_frame will hold the current frame + * number that is being written; otherwise it indicates that the write + * callback is being called to write metadata. + * + * \note + * Unlike when writing to native FLAC, when writing to Ogg FLAC the + * write callback will be called twice when writing each audio + * frame; once for the page header, and once for the page body. + * When writing the page header, the \a samples argument to the + * write callback will be \c 0. + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param buffer An array of encoded data of length \a bytes. + * \param bytes The byte length of \a buffer. + * \param samples The number of samples encoded by \a buffer. + * \c 0 has a special meaning; see above. + * \param current_frame The number of the current frame being encoded. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_init_*(). + * \retval FLAC__StreamEncoderWriteStatus + * The callee's return status. + */ +typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], size_t bytes, unsigned samples, unsigned current_frame, void *client_data); + +/** Signature for the seek callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_encoder_init*_stream(). The supplied function will be called + * when the encoder needs to seek the output stream. The encoder will pass + * the absolute byte offset to seek to, 0 meaning the beginning of the stream. + * + * Here is an example of a seek callback for stdio streams: + * \code + * FLAC__StreamEncoderSeekStatus seek_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * if(file == stdin) + * return FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED; + * else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0) + * return FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR; + * else + * return FLAC__STREAM_ENCODER_SEEK_STATUS_OK; + * } + * \endcode + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param absolute_byte_offset The offset from the beginning of the stream + * to seek to. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_init_*(). + * \retval FLAC__StreamEncoderSeekStatus + * The callee's return status. + */ +typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data); + +/** Signature for the tell callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_encoder_init*_stream(). The supplied function will be called + * when the encoder needs to know the current position of the output stream. + * + * \warning + * The callback must return the true current byte offset of the output to + * which the encoder is writing. If you are buffering the output, make + * sure and take this into account. If you are writing directly to a + * FILE* from your write callback, ftell() is sufficient. If you are + * writing directly to a file descriptor from your write callback, you + * can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to + * these points to rewrite metadata after encoding. + * + * Here is an example of a tell callback for stdio streams: + * \code + * FLAC__StreamEncoderTellStatus tell_cb(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data) + * { + * FILE *file = ((MyClientData*)client_data)->file; + * off_t pos; + * if(file == stdin) + * return FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED; + * else if((pos = ftello(file)) < 0) + * return FLAC__STREAM_ENCODER_TELL_STATUS_ERROR; + * else { + * *absolute_byte_offset = (FLAC__uint64)pos; + * return FLAC__STREAM_ENCODER_TELL_STATUS_OK; + * } + * } + * \endcode + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param absolute_byte_offset The address at which to store the current + * position of the output. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_init_*(). + * \retval FLAC__StreamEncoderTellStatus + * The callee's return status. + */ +typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data); + +/** Signature for the metadata callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_encoder_init*_stream(). The supplied function will be called + * once at the end of encoding with the populated STREAMINFO structure. This + * is so the client can seek back to the beginning of the file and write the + * STREAMINFO block with the correct statistics after encoding (like + * minimum/maximum frame size and total samples). + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param metadata The final populated STREAMINFO block. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_init_*(). + */ +typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data); + +/** Signature for the progress callback. + * + * A function pointer matching this signature may be passed to + * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE(). + * The supplied function will be called when the encoder has finished + * writing a frame. The \c total_frames_estimate argument to the + * callback will be based on the value from + * FLAC__stream_encoder_set_total_samples_estimate(). + * + * \note In general, FLAC__StreamEncoder functions which change the + * state should not be called on the \a encoder while in the callback. + * + * \param encoder The encoder instance calling the callback. + * \param bytes_written Bytes written so far. + * \param samples_written Samples written so far. + * \param frames_written Frames written so far. + * \param total_frames_estimate The estimate of the total number of + * frames to be written. + * \param client_data The callee's client data set through + * FLAC__stream_encoder_init_*(). + */ +typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data); + + +/*********************************************************************** + * + * Class constructor/destructor + * + ***********************************************************************/ + +/** Create a new stream encoder instance. The instance is created with + * default settings; see the individual FLAC__stream_encoder_set_*() + * functions for each setting's default. + * + * \retval FLAC__StreamEncoder* + * \c NULL if there was an error allocating memory, else the new instance. + */ +FLAC_API FLAC__StreamEncoder *FLAC__stream_encoder_new(void); + +/** Free an encoder instance. Deletes the object pointed to by \a encoder. + * + * \param encoder A pointer to an existing encoder. + * \assert + * \code encoder != NULL \endcode + */ +FLAC_API void FLAC__stream_encoder_delete(FLAC__StreamEncoder *encoder); + + +/*********************************************************************** + * + * Public class method prototypes + * + ***********************************************************************/ + +/** Set the serial number for the FLAC stream to use in the Ogg container. + * + * \note + * This does not need to be set for native FLAC encoding. + * + * \note + * It is recommended to set a serial number explicitly as the default of '0' + * may collide with other streams. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param serial_number See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_ogg_serial_number(FLAC__StreamEncoder *encoder, long serial_number); + +/** Set the "verify" flag. If \c true, the encoder will verify it's own + * encoded output by feeding it through an internal decoder and comparing + * the original signal against the decoded signal. If a mismatch occurs, + * the process call will return \c false. Note that this will slow the + * encoding process by the extra time required for decoding and comparison. + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_verify(FLAC__StreamEncoder *encoder, FLAC__bool value); + +/** Set the Subset flag. If \c true, + * the encoder will comply with the Subset and will check the + * settings during FLAC__stream_encoder_init_*() to see if all settings + * comply. If \c false, the settings may take advantage of the full + * range that the format allows. + * + * Make sure you know what it entails before setting this to \c false. + * + * \default \c true + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_streamable_subset(FLAC__StreamEncoder *encoder, FLAC__bool value); + +/** Set the number of channels to be encoded. + * + * \default \c 2 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_channels(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set the sample resolution of the input to be encoded. + * + * \warning + * Do not feed the encoder data that is wider than the value you + * set here or you will generate an invalid stream. + * + * \default \c 16 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_bits_per_sample(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set the sample rate (in Hz) of the input to be encoded. + * + * \default \c 44100 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set the compression level + * + * The compression level is roughly proportional to the amount of effort + * the encoder expends to compress the file. A higher level usually + * means more computation but higher compression. The default level is + * suitable for most applications. + * + * Currently the levels range from \c 0 (fastest, least compression) to + * \c 8 (slowest, most compression). A value larger than \c 8 will be + * treated as \c 8. + * + * This function automatically calls the following other \c _set_ + * functions with appropriate values, so the client does not need to + * unless it specifically wants to override them: + * - FLAC__stream_encoder_set_do_mid_side_stereo() + * - FLAC__stream_encoder_set_loose_mid_side_stereo() + * - FLAC__stream_encoder_set_apodization() + * - FLAC__stream_encoder_set_max_lpc_order() + * - FLAC__stream_encoder_set_qlp_coeff_precision() + * - FLAC__stream_encoder_set_do_qlp_coeff_prec_search() + * - FLAC__stream_encoder_set_do_escape_coding() + * - FLAC__stream_encoder_set_do_exhaustive_model_search() + * - FLAC__stream_encoder_set_min_residual_partition_order() + * - FLAC__stream_encoder_set_max_residual_partition_order() + * - FLAC__stream_encoder_set_rice_parameter_search_dist() + * + * The actual values set for each level are: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
leveldo mid-side stereoloose mid-side stereoapodizationmax lpc orderqlp coeff precisionqlp coeff prec searchescape codingexhaustive model searchmin residual partition ordermax residual partition orderrice parameter search dist
0 false false tukey(0.5) 0 0 false false false 0 3 0
1 true true tukey(0.5) 0 0 false false false 0 3 0
2 true false tukey(0.5) 0 0 false false false 0 3 0
3 false false tukey(0.5) 6 0 false false false 0 4 0
4 true true tukey(0.5) 8 0 false false false 0 4 0
5 true false tukey(0.5) 8 0 false false false 0 5 0
6 true false tukey(0.5);partial_tukey(2) 8 0 false false false 0 6 0
7 true false tukey(0.5);partial_tukey(2) 12 0 false false false 0 6 0
8 true false tukey(0.5);partial_tukey(2);punchout_tukey(3) 12 0 false false false 0 6 0
+ * + * \default \c 5 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_compression_level(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set the blocksize to use while encoding. + * + * The number of samples to use per frame. Use \c 0 to let the encoder + * estimate a blocksize; this is usually best. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_blocksize(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set to \c true to enable mid-side encoding on stereo input. The + * number of channels must be 2 for this to have any effect. Set to + * \c false to use only independent channel coding. + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value); + +/** Set to \c true to enable adaptive switching between mid-side and + * left-right encoding on stereo input. Set to \c false to use + * exhaustive searching. Setting this to \c true requires + * FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to + * \c true in order to have any effect. + * + * \default \c false + * \param encoder An encoder instance to set. + * \param value Flag value (see above). + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamEncoder *encoder, FLAC__bool value); + +/** Sets the apodization function(s) the encoder will use when windowing + * audio data for LPC analysis. + * + * The \a specification is a plain ASCII string which specifies exactly + * which functions to use. There may be more than one (up to 32), + * separated by \c ';' characters. Some functions take one or more + * comma-separated arguments in parentheses. + * + * The available functions are \c bartlett, \c bartlett_hann, + * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop, + * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall, + * \c rectangle, \c triangle, \c tukey(P), \c partial_tukey(n[/ov[/P]]), + * \c punchout_tukey(n[/ov[/P]]), \c welch. + * + * For \c gauss(STDDEV), STDDEV specifies the standard deviation + * (0blocksize / (2 ^ order). + * + * Set both min and max values to \c 0 to force a single context, + * whose Rice parameter is based on the residual signal variance. + * Otherwise, set a min and max order, and the encoder will search + * all orders, using the mean of each context for its Rice parameter, + * and use the best. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set the maximum partition order to search when coding the residual. + * This is used in tandem with + * FLAC__stream_encoder_set_min_residual_partition_order(). + * + * The partition order determines the context size in the residual. + * The context size will be approximately blocksize / (2 ^ order). + * + * Set both min and max values to \c 0 to force a single context, + * whose Rice parameter is based on the residual signal variance. + * Otherwise, set a min and max order, and the encoder will search + * all orders, using the mean of each context for its Rice parameter, + * and use the best. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, unsigned value); + +/** Deprecated. Setting this value has no effect. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist(FLAC__StreamEncoder *encoder, unsigned value); + +/** Set an estimate of the total samples that will be encoded. + * This is merely an estimate and may be set to \c 0 if unknown. + * This value will be written to the STREAMINFO block before encoding, + * and can remove the need for the caller to rewrite the value later + * if the value is known before encoding. + * + * \default \c 0 + * \param encoder An encoder instance to set. + * \param value See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *encoder, FLAC__uint64 value); + +/** Set the metadata blocks to be emitted to the stream before encoding. + * A value of \c NULL, \c 0 implies no metadata; otherwise, supply an + * array of pointers to metadata blocks. The array is non-const since + * the encoder may need to change the \a is_last flag inside them, and + * in some cases update seek point offsets. Otherwise, the encoder will + * not modify or free the blocks. It is up to the caller to free the + * metadata blocks after encoding finishes. + * + * \note + * The encoder stores only copies of the pointers in the \a metadata array; + * the metadata blocks themselves must survive at least until after + * FLAC__stream_encoder_finish() returns. Do not free the blocks until then. + * + * \note + * The STREAMINFO block is always written and no STREAMINFO block may + * occur in the supplied array. + * + * \note + * By default the encoder does not create a SEEKTABLE. If one is supplied + * in the \a metadata array, but the client has specified that it does not + * support seeking, then the SEEKTABLE will be written verbatim. However + * by itself this is not very useful as the client will not know the stream + * offsets for the seekpoints ahead of time. In order to get a proper + * seektable the client must support seeking. See next note. + * + * \note + * SEEKTABLE blocks are handled specially. Since you will not know + * the values for the seek point stream offsets, you should pass in + * a SEEKTABLE 'template', that is, a SEEKTABLE object with the + * required sample numbers (or placeholder points), with \c 0 for the + * \a frame_samples and \a stream_offset fields for each point. If the + * client has specified that it supports seeking by providing a seek + * callback to FLAC__stream_encoder_init_stream() or both seek AND read + * callback to FLAC__stream_encoder_init_ogg_stream() (or by using + * FLAC__stream_encoder_init*_file() or FLAC__stream_encoder_init*_FILE()), + * then while it is encoding the encoder will fill the stream offsets in + * for you and when encoding is finished, it will seek back and write the + * real values into the SEEKTABLE block in the stream. There are helper + * routines for manipulating seektable template blocks; see metadata.h: + * FLAC__metadata_object_seektable_template_*(). If the client does + * not support seeking, the SEEKTABLE will have inaccurate offsets which + * will slow down or remove the ability to seek in the FLAC stream. + * + * \note + * The encoder instance \b will modify the first \c SEEKTABLE block + * as it transforms the template to a valid seektable while encoding, + * but it is still up to the caller to free all metadata blocks after + * encoding. + * + * \note + * A VORBIS_COMMENT block may be supplied. The vendor string in it + * will be ignored. libFLAC will use it's own vendor string. libFLAC + * will not modify the passed-in VORBIS_COMMENT's vendor string, it + * will simply write it's own into the stream. If no VORBIS_COMMENT + * block is present in the \a metadata array, libFLAC will write an + * empty one, containing only the vendor string. + * + * \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be + * the second metadata block of the stream. The encoder already supplies + * the STREAMINFO block automatically. If \a metadata does not contain a + * VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if + * \a metadata does contain a VORBIS_COMMENT block and it is not the + * first, the init function will reorder \a metadata by moving the + * VORBIS_COMMENT block to the front; the relative ordering of the other + * blocks will remain as they were. + * + * \note The Ogg FLAC mapping limits the number of metadata blocks per + * stream to \c 65535. If \a num_blocks exceeds this the function will + * return \c false. + * + * \default \c NULL, 0 + * \param encoder An encoder instance to set. + * \param metadata See above. + * \param num_blocks See above. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * \c false if the encoder is already initialized, else \c true. + * \c false if the encoder is already initialized, or if + * \a num_blocks > 65535 if encoding to Ogg FLAC, else \c true. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks); + +/** Get the current encoder state. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__StreamEncoderState + * The current encoder state. + */ +FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_get_state(const FLAC__StreamEncoder *encoder); + +/** Get the state of the verify stream decoder. + * Useful when the stream encoder state is + * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__StreamDecoderState + * The verify stream decoder state. + */ +FLAC_API FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state(const FLAC__StreamEncoder *encoder); + +/** Get the current encoder state as a C string. + * This version automatically resolves + * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the + * verify decoder's state. + * + * \param encoder A encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval const char * + * The encoder state as a C string. Do not modify the contents. + */ +FLAC_API const char *FLAC__stream_encoder_get_resolved_state_string(const FLAC__StreamEncoder *encoder); + +/** Get relevant values about the nature of a verify decoder error. + * Useful when the stream encoder state is + * \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should + * be addresses in which the stats will be returned, or NULL if value + * is not desired. + * + * \param encoder An encoder instance to query. + * \param absolute_sample The absolute sample number of the mismatch. + * \param frame_number The number of the frame in which the mismatch occurred. + * \param channel The channel in which the mismatch occurred. + * \param sample The number of the sample (relative to the frame) in + * which the mismatch occurred. + * \param expected The expected value for the sample in question. + * \param got The actual value returned by the decoder. + * \assert + * \code encoder != NULL \endcode + */ +FLAC_API void FLAC__stream_encoder_get_verify_decoder_error_stats(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); + +/** Get the "verify" flag. + * + * \param encoder An encoder instance to query. + * \assert + * \code encoder != NULL \endcode + * \retval FLAC__bool + * See FLAC__stream_encoder_set_verify(). + */ +FLAC_API FLAC__bool FLAC__stream_encoder_get_verify(const FLAC__StreamEncoder *encoder); + +/** Get the frame header. + * + * \param encoder An initialized encoder instance in the OK state. + * \param buffer An array of pointers to each channel's signal. + * \param samples The number of samples in one channel. + * \assert + * \code encoder != NULL \endcode + * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with FLAC__stream_encoder_get_state() to see what + * went wrong. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_process(FLAC__StreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples); + +/** Submit data for encoding. + * This version allows you to supply the input data where the channels + * are interleaved into a single array (i.e. channel0_sample0, + * channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). + * The samples need not be block-aligned but they must be + * sample-aligned, i.e. the first value should be channel0_sample0 + * and the last value channelN_sampleM. Each sample should be a signed + * integer, right-justified to the resolution set by + * FLAC__stream_encoder_set_bits_per_sample(). For example, if the + * resolution is 16 bits per sample, the samples should all be in the + * range [-32768,32767]. + * + * For applications where channel order is important, channels must + * follow the order as described in the + * frame header. + * + * \param encoder An initialized encoder instance in the OK state. + * \param buffer An array of channel-interleaved data (see above). + * \param samples The number of samples in one channel, the same as for + * FLAC__stream_encoder_process(). For example, if + * encoding two channels, \c 1000 \a samples corresponds + * to a \a buffer of 2000 values. + * \assert + * \code encoder != NULL \endcode + * \code FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK \endcode + * \retval FLAC__bool + * \c true if successful, else \c false; in this case, check the + * encoder state with FLAC__stream_encoder_get_state() to see what + * went wrong. + */ +FLAC_API FLAC__bool FLAC__stream_encoder_process_interleaved(FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples); + +/* \} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/flac/lib/libFLAC.a b/flac/lib/libFLAC.a new file mode 100644 index 0000000000000000000000000000000000000000..7b290313e029fb86a14d1eb57f08d5361334684b GIT binary patch literal 331624 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�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

l!_%)_5n2*Q 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 VQX;vp>l?}PW}+`TUt|LH{{WUQ3=RMQ literal 0 HcmV?d00001