len0rd/rockbox
1
0
Fork 1
mirror of https://github.com/Rockbox/rockbox.git synced 2025-11-13 07:02:31 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Initial import of libFLAC from flac-1.1.2.tar.gz

Browse source 
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@5983 a1c6a512-1295-4272-9138-f99709370657
This commit is contained in:
Dave Chapman 2005-02-16 19:33:19 +00:00
parent 9b32a1988f
commit aa97e4d498
56 changed files with 29599 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

158
apps/codecs/libFLAC/include/FLAC/all.h Normal file
View file

@ -0,0 +1,158 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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 "file_decoder.h"
#include "file_encoder.h"
#include "format.h"
#include "metadata.h"
#include "ordinals.h"
#include "seekable_stream_decoder.h"
#include "seekable_stream_encoder.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
* <A HREF="../format.html">here</A>.
*
* \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 as <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 <A HREF="../license.html">Xiph's BSD license</A>.
* 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.
*
* There is also a new libOggFLAC library which wraps around libFLAC
* to provide routines for encoding to and decoding from FLAC streams
* inside an Ogg container. The interfaces are very similar or identical
* to their counterparts in libFLAC. libOggFLAC is also licensed under
* <A HREF="../license.html">Xiph's BSD license</A>.
*
* \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 as
* <include>/FLAC++/...
*
* There is also a new libOggFLAC++ library, which provides classes
* for encoding to and decoding from FLAC streams in an Ogg container.
* The classes are very similar to their counterparts in libFLAC++.
*
* Both libFLAC++ libOggFLAC++ are also licensed under
* <A HREF="../license.html">Xiph's BSD license</A>.
*
* \section getting_started Getting Started
*
* A good starting point for learning the API is to browse through
* the <A HREF="modules.html">modules</A>. 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.
*
* \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 are independent of each other.
* - The metadata interface requires the file decoder.
* - The decoder and encoder layers depend on the layers below them, but
* not above them; e.g. the seekable stream decoder depends on the stream
* decoder but not the file decoder
*
* For example, if your application only requires the stream decoder, no
* encoders, and no metadata interface, you can remove the seekable stream
* decoder, file decoder, all encoders, and the metadata interface, which
* will greatly reduce the size of the library.
*/
/** \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

45
apps/codecs/libFLAC/include/FLAC/assert.h Normal file
View file

@ -0,0 +1,45 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2001,2002,2003,2004,2005 Josh Coalson
*
* 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 <assert.h>
#define FLAC__ASSERT(x) assert(x)
#define FLAC__ASSERT_DECLARATION(x) x
#else
#define FLAC__ASSERT(x)
#define FLAC__ASSERT_DECLARATION(x)
#endif
#endif

181
apps/codecs/libFLAC/include/FLAC/callback.h Normal file
View file

@ -0,0 +1,181 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2004,2005 Josh Coalson
*
* 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 <stdlib.h> /* 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 can NOT 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
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

47
apps/codecs/libFLAC/include/FLAC/export.h Normal file
View file

@ -0,0 +1,47 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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
#if defined(FLAC__NO_DLL) || !defined(_MSC_VER)
#define FLAC_API
#else
#ifdef FLAC_API_EXPORTS
#define FLAC_API _declspec(dllexport)
#else
#define FLAC_API _declspec(dllimport)
#endif
#endif
#endif

660
apps/codecs/libFLAC/include/FLAC/file_decoder.h Normal file
View file

@ -0,0 +1,660 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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__FILE_DECODER_H
#define FLAC__FILE_DECODER_H
#include "export.h"
#include "seekable_stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/file_decoder.h
*
* \brief
* This module contains the functions which implement the file
* decoder.
*
* See the detailed documentation in the
* \link flac_file_decoder file decoder \endlink module.
*/
/** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
* \ingroup flac_decoder
*
* \brief
* This module contains the functions which implement the file
* decoder.
*
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* FLAC__file_decoder_new().
* - The program overrides the default settings and sets callbacks for
* writing, error reporting, and metadata reporting using
* FLAC__file_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__file_decoder_init().
* - The program calls the FLAC__file_decoder_process_*() functions
* to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with FLAC__file_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__file_decoder_delete().
*
* The file decoder is a trivial wrapper around the
* \link flac_seekable_stream_decoder seekable stream decoder \endlink
* meant to simplfy the process of decoding from a standard file. The
* file decoder supplies all but the Write/Metadata/Error callbacks.
* The user needs only to provide the path to the file and the file
* decoder handles the rest.
*
* Like the seekable stream decoder, seeking is exposed through the
* FLAC__file_decoder_seek_absolute() method. At any point after the file
* decoder has been initialized, the user can call this function to seek to
* an exact sample within the file. Subsequently, the first time the write
* callback is called it will be passed a (possibly partial) block starting
* at that sample.
*
* The file decoder also inherits MD5 signature checking from the seekable
* stream decoder. If this is turned on before initialization,
* FLAC__file_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 if there is no signature in the STREAMINFO
* block or when a seek is attempted.
*
* Make sure to read the detailed descriptions of the
* \link flac_seekable_stream_decoder seekable stream decoder module \endlink
* and \link flac_stream_decoder stream decoder module \endlink
* since the file decoder inherits much of its behavior from them.
*
* \note
* The "set" functions may only be called when the decoder is in the
* state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
* FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
* before FLAC__file_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__file_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
*
* \{
*/
/** State values for a FLAC__FileDecoder
*
* The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
*/
typedef enum {
FLAC__FILE_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
FLAC__FILE_DECODER_END_OF_FILE,
/**< The decoder has reached the end of the file. */
FLAC__FILE_DECODER_ERROR_OPENING_FILE,
/**< An error occurred opening the input file. */
FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__FILE_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. */
FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying seekable stream decoder. */
FLAC__FILE_DECODER_ALREADY_INITIALIZED,
/**< FLAC__file_decoder_init() was called when the decoder was already
* initialized, usually because FLAC__file_decoder_finish() was not
* called.
*/
FLAC__FILE_DECODER_INVALID_CALLBACK,
/**< FLAC__file_decoder_init() was called without all callbacks
* being set.
*/
FLAC__FILE_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} FLAC__FileDecoderState;
/** Maps a FLAC__FileDecoderState to a C string.
*
* Using a FLAC__FileDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__FileDecoderStateString[];
/***********************************************************************
*
* class FLAC__FileDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
struct FLAC__FileDecoderProtected;
struct FLAC__FileDecoderPrivate;
/** The opaque structure definition for the file decoder type. See the
* \link flac_file_decoder file decoder module \endlink for a detailed
* description.
*/
typedef struct {
struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileDecoder;
/** Signature for the write callback.
* See FLAC__file_decoder_set_write_callback()
* and FLAC__SeekableStreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* FLAC__file_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See FLAC__file_decoder_set_metadata_callback()
* and FLAC__SeekableStreamDecoderMetadataCallback for more info.
*
* \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__file_decoder_set_client_data().
*/
typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__file_decoder_set_error_callback()
* and FLAC__SeekableStreamDecoderErrorCallback for more info.
*
* \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__file_decoder_set_client_data().
*/
typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new file decoder instance. The instance is created with
* default settings; see the individual FLAC__file_decoder_set_*()
* functions for each setting's default.
*
* \retval FLAC__FileDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
/** 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__file_decoder_delete(FLAC__FileDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** Set the "MD5 signature checking" flag.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_md5_checking().
*
* \default \c false
* \param decoder A decoder instance to set.
* \param 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__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
/** Set the input file name to decode.
*
* \default \c "-"
* \param decoder A decoder instance to set.
* \param value The input file name, or "-" for \c stdin.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
/** Set the write callback.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_error_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param 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__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond().
*
* \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__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond_application().
*
* \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__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_respond_all().
*
* \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__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore().
*
* \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__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore_application().
*
* \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__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_set_metadata_ignore_all().
*
* \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__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__FileDecoderState
* The current decoder state.
*/
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
/** Get the state of the underlying seekable stream decoder.
* Useful when the file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* The seekable stream decoder state.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
/** Get the state of the underlying stream decoder.
* Useful when the file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
* decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The seekable stream decoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
* seekable stream decoder's state.
*
* \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__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
/** Get the "MD5 signature checking" flag.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_md5_checking().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__ChannelAssignment
* See above.
*/
FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_decode_position().
*
* \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 there was an error from
* the 'tell' callback.
*/
FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
* Should be called after FLAC__file_decoder_new() and
* FLAC__file_decoder_set_*() but before any of the
* FLAC__file_decoder_process_*() functions. Will set and return
* the decoder state, which will be FLAC__FILE_DECODER_OK if
* initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__FileDecoderState
* \c FLAC__FILE_DECODER_OK if initialization was successful; see
* FLAC__FileDecoderState for the meanings of other return values.
*/
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* FLAC__FILE_DECODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before FLAC__file_decoder_delete()
* but it is good practice to match every FLAC__file_decoder_init() with
* a FLAC__file_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__file_decoder_finish(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_skip_single_frame().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
/** Flush the input and seek to an absolute sample.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_seek_absolute().
*
* \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__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

871
apps/codecs/libFLAC/include/FLAC/file_encoder.h Normal file
View file

@ -0,0 +1,871 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2002,2003,2004,2005 Josh Coalson
*
* 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__FILE_ENCODER_H
#define FLAC__FILE_ENCODER_H
#include "export.h"
#include "seekable_stream_encoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/file_encoder.h
*
* \brief
* This module contains the functions which implement the file
* encoder.
*
* See the detailed documentation in the
* \link flac_file_encoder file encoder \endlink module.
*/
/** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
* \ingroup flac_encoder
*
* \brief
* This module contains the functions which implement the file
* encoder.
*
* The basic usage of this encoder is as follows:
* - The program creates an instance of an encoder using
* FLAC__file_encoder_new().
* - The program overrides the default settings using
* FLAC__file_encoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for encoding using FLAC__file_encoder_init().
* - The program calls FLAC__file_encoder_process() or
* FLAC__file_encoder_process_interleaved() to encode data, which
* subsequently writes data to the output file.
* - The program finishes the encoding with FLAC__file_encoder_finish(),
* which causes the encoder to encode any data still in its input pipe,
* rewind and write the STREAMINFO metadata to file, and finally reset
* the encoder to the uninitialized state.
* - The instance may be used again or deleted with
* FLAC__file_encoder_delete().
*
* The file encoder is a wrapper around the
* \link flac_seekable_stream_encoder seekable stream encoder \endlink which supplies all
* callbacks internally; the user need specify only the filename.
*
* Make sure to read the detailed description of the
* \link flac_seekable_stream_encoder seekable stream encoder module \endlink since the
* \link flac_stream_encoder stream encoder module \endlink since the
* file encoder inherits much of its behavior from them.
*
* \note
* The "set" functions may only be called when the encoder is in the
* state FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
* FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but
* before FLAC__file_encoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__file_encoder_finish() resets all settings to the constructor
* defaults.
*
* \{
*/
/** State values for a FLAC__FileEncoder
*
* The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
*/
typedef enum {
FLAC__FILE_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
FLAC__FILE_ENCODER_NO_FILENAME,
/**< FLAC__file_encoder_init() was called without first calling
* FLAC__file_encoder_set_filename().
*/
FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying seekable stream encoder;
* check FLAC__file_encoder_get_seekable_stream_encoder_state().
*/
FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
/**< A fatal error occurred while writing to the encoded file. */
FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
/**< An error occurred opening the output file for writing. */
FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
FLAC__FILE_ENCODER_ALREADY_INITIALIZED,
/**< FLAC__file_encoder_init() was called when the encoder was
* already initialized, usually because
* FLAC__file_encoder_finish() was not called.
*/
FLAC__FILE_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} FLAC__FileEncoderState;
/** Maps a FLAC__FileEncoderState to a C string.
*
* Using a FLAC__FileEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__FileEncoderStateString[];
/***********************************************************************
*
* class FLAC__FileEncoder
*
***********************************************************************/
struct FLAC__FileEncoderProtected;
struct FLAC__FileEncoderPrivate;
/** The opaque structure definition for the file encoder type.
* See the \link flac_file_encoder file encoder module \endlink
* for a detailed description.
*/
typedef struct {
struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileEncoder;
/** Signature for the progress callback.
* See FLAC__file_encoder_set_progress_callback() for more info.
*
* \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__file_encoder_set_client_data().
*/
typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *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 file encoder instance. The instance is created with
* default settings; see the individual FLAC__file_encoder_set_*()
* functions for each setting's default.
*
* \retval FLAC__FileEncoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
/** 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__file_encoder_delete(FLAC__FileEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_verify().
*
* \default \c true
* \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__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_streamable_subset().
*
* \default \c true
* \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__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_mid_side_stereo().
*
* \default \c false
* \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__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
*
* \default \c false
* \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__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_channels().
*
* \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__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_bits_per_sample().
*
* \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__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_sample_rate().
*
* \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__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_blocksize().
*
* \default \c 1152
* \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__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_max_lpc_order().
*
* \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__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
*
* \note
* In the current implementation, qlp_coeff_precision + bits_per_sample must
* be less than 32.
*
* \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__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
*
* \default \c false
* \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__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_escape_coding().
*
* \default \c false
* \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__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
*
* \default \c false
* \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__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_min_residual_partition_order().
*
* \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__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_max_residual_partition_order().
*
* \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__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
*
* \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__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_total_samples_estimate().
*
* \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__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_metadata().
*
* \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.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the output file name encode to.
*
* \note
* The filename is mandatory and must be set before initialization.
*
* \note
* Unlike the FLAC__FileDecoder, the filename does not interpret "-" for
* \c stdout; writing to \c stdout is not relevant in the file encoder.
*
* \default \c NULL
* \param encoder A encoder instance to set.
* \param value The output file name.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__FileEncoder *encoder, const char *value);
/** Set the progress callback.
* 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__file_encoder_set_total_samples_estimate().
*
* \note
* Unlike most other callbacks, the progress callback is \b not mandatory
* and need not be set before initialization.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \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__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__FileEncoderState
* The current encoder state.
*/
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying seekable stream encoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__SeekableStreamEncoderState
* The seekable stream encoder state.
*/
FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
* encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* The seekable stream encoder state.
*/
FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
* encoder state is \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and
* 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 stream encoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
/** Get the current encoder state as a C string.
* This version automatically resolves
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
* seekable stream encoder'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__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
/** Get relevant values about the nature of a verify decoder error.
* Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the seekable stream
* encoder state is
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
* stream encoder state is
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \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__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
/** Get the "verify" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_verify().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
/** Get the "streamable subset" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_streamable_subset().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_streamable_subset().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
/** Get the "mid/side stereo coding" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_get_do_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
/** Get the "adaptive mid/side switching" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_loose_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
/** Get the number of input channels being processed.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_channels().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_channels().
*/
FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
/** Get the input sample resolution setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_bits_per_sample().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_bits_per_sample().
*/
FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
/** Get the input sample rate setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_sample_rate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_sample_rate().
*/
FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
/** Get the blocksize setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_blocksize().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_blocksize().
*/
FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
/** Get the maximum LPC order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_lpc_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_max_lpc_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
/** Get the quantized linear predictor coefficient precision setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_qlp_coeff_precision().
*/
FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
/** Get the qlp coefficient precision search flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
/** Get the "escape coding" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_escape_coding().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_escape_coding().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
/** Get the exhaustive model search flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_exhaustive_model_search().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
/** Get the minimum residual partition order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_min_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_min_residual_partition_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
/** Get maximum residual partition order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_max_residual_partition_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
/** Get the Rice parameter search distance setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_rice_parameter_search_dist().
*/
FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
/** Get the previously set estimate of the total samples to be encoded.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_total_samples_estimate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__uint64
* See FLAC__file_encoder_set_total_samples_estimate().
*/
FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after FLAC__file_encoder_new() and
* FLAC__file_encoder_set_*() but before FLAC__file_encoder_process()
* or FLAC__file_encoder_process_interleaved(). Will set and return
* the encoder state, which will be FLAC__FILE_ENCODER_OK if
* initialization succeeded.
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__FileEncoderState
* \c FLAC__FILE_ENCODER_OK if initialization was successful; see
* FLAC__FileEncoderState for the meanings of other return values.
*/
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* FLAC__FILE_ENCODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before FLAC__file_encoder_delete()
* but it is good practice to match every FLAC__file_encoder_init()
* with a FLAC__file_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
/** Submit data for encoding.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_process().
*
* \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__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__file_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Submit data for encoding.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_process_interleaved().
*
* \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__file_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__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__file_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

861
apps/codecs/libFLAC/include/FLAC/format.h Normal file
View file

@ -0,0 +1,861 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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
* <A HREF="../format.html">FLAC format</A>. 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 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 <A HREF="../format.html">FLAC format</A>
* as to why.
*/
#define FLAC__MAX_SAMPLE_RATE (655350u)
/** The maximum LPC order permitted by the format. */
#define FLAC__MAX_LPC_ORDER (32u)
/** 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 nulL-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
* 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. */
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. <A HREF="../format.html#partitioned_rice">format specification</A>)
*/
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_RICE_RAW_LEN; /**< == 5 (bits) */
extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
/** Header for the entropy coding method. (c.f. <A HREF="../format.html#residual">format specification</A>)
*/
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. <A HREF="../format.html#subframe_constant">format specification</A>)
*/
typedef struct {
FLAC__int32 value; /**< The constant signal value. */
} FLAC__Subframe_Constant;
/** VERBATIM subframe. (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>)
*/
typedef struct {
const FLAC__int32 *data; /**< A pointer to verbatim signal. */
} FLAC__Subframe_Verbatim;
/** FIXED subframe. (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>)
*/
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. <A HREF="../format.html#subframe_lpc">format specification</A>)
*/
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. <A HREF="../format.html#subframe">format specification</A>)
*/
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;
extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /**< == 1 (bit) */
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. <A HREF="../format.html#frame_header">format specification</A>)
*/
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. */
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; /**< == 2 (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. <A HREF="../format.html#frame_footer">format specification</A>)
*/
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. <A HREF="../format.html#frame">format specification</A>)
*/
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,
/**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */
FLAC__METADATA_TYPE_PADDING = 1,
/**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */
FLAC__METADATA_TYPE_APPLICATION = 2,
/**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */
FLAC__METADATA_TYPE_SEEKTABLE = 3,
/**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
/**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block */
FLAC__METADATA_TYPE_CUESHEET = 5,
/**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
FLAC__METADATA_TYPE_UNDEFINED = 6
/**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
} 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. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>)
*/
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. <A HREF="../format.html#metadata_block_padding">format specification</A>)
*/
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. <A HREF="../format.html#metadata_block_application">format specification</A>)
*/
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. <A HREF="../format.html#seekpoint">format specification</A>)
*/
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. <A HREF="../format.html#metadata_block_seektable">format specification</A>)
*
* \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. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
*
* 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. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
*/
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
* <A HREF="../format.html#cuesheet_track_index">format specification</A> 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
* <A HREF="../format.html#cuesheet_track">format specification</A> 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 '\0' */
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
* <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
* 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) */
/** 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. <A HREF="../format.html#metadata_block">format specification</A>)
*/
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_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. Since the rules for valid
* sample rates are slightly complex, they are encapsulated in this function.
*
* \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);
/** 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 value A string to be checked.
* \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);
/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
/** 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);
/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
/** 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);
/* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
/** 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);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

1858
apps/codecs/libFLAC/include/FLAC/metadata.h Normal file
View file

File diff suppressed because it is too large Load diff

73
apps/codecs/libFLAC/include/FLAC/ordinals.h Normal file
View file

@ -0,0 +1,73 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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
#ifndef _MSC_VER
#include <inttypes.h>
#endif
typedef signed char FLAC__int8;
typedef unsigned char FLAC__uint8;
#if defined _MSC_VER
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
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

931
apps/codecs/libFLAC/include/FLAC/seekable_stream_decoder.h Normal file
View file

@ -0,0 +1,931 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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__SEEKABLE_STREAM_DECODER_H
#define FLAC__SEEKABLE_STREAM_DECODER_H
#include "export.h"
#include "stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/seekable_stream_decoder.h
*
* \brief
* This module contains the functions which implement the seekable stream
* decoder.
*
* See the detailed documentation in the
* \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
*/
/** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
* \ingroup flac_decoder
*
* \brief
* This module contains the functions which implement the seekable stream
* decoder.
*
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* FLAC__seekable_stream_decoder_new().
* - The program overrides the default settings and sets callbacks for
* reading, writing, seeking, error reporting, and metadata reporting
* using FLAC__seekable_stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__seekable_stream_decoder_init().
* - The program calls the FLAC__seekable_stream_decoder_process_*()
* functions to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with
* FLAC__seekable_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__seekable_stream_decoder_delete().
*
* The seekable stream decoder is a wrapper around the
* \link flac_stream_decoder stream decoder \endlink which also provides
* seeking capability. In addition to the Read/Write/Metadata/Error
* callbacks of the stream decoder, the user must also provide the following:
*
* - Seek callback - This function will be called when the decoder wants to
* seek to an absolute position in the stream.
* - Tell callback - This function will be called when the decoder wants to
* know the current absolute position of the stream.
* - Length callback - This function will be called when the decoder wants
* to know length of the stream. The seeking algorithm currently requires
* that the overall stream length be known.
* - EOF callback - This function will be called when the decoder wants to
* know if it is at the end of the stream. This could be synthesized from
* the tell and length callbacks but it may be more expensive that way, so
* there is a separate callback for it.
*
* Seeking is exposed through the
* FLAC__seekable_stream_decoder_seek_absolute() method. At any point after
* the seekable stream decoder has been initialized, the user 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.
*
* The seekable stream decoder also provides MD5 signature checking. If
* this is turned on before initialization,
* FLAC__seekable_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__seekable_stream_decoder_reset()) if there is no signature in the
* STREAMINFO block or when a seek is attempted.
*
* Make sure to read the detailed description of the
* \link flac_stream_decoder stream decoder module \endlink since the
* seekable stream decoder inherits much of its behavior.
*
* \note
* The "set" functions may only be called when the decoder is in the
* state FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
* FLAC__seekable_stream_decoder_new() or
* FLAC__seekable_stream_decoder_finish(), but before
* FLAC__seekable_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__SeekableStreamDecoder
*
* The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
/**< The decoder is in the process of seeking. */
FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying stream decoder. */
FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
/**< The read callback returned an error. */
FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking or the seek or tell
* callback returned an error.
*/
FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
/**< FLAC__seekable_stream_decoder_init() was called when the
* decoder was already initialized, usually because
* FLAC__seekable_stream_decoder_finish() was not called.
*/
FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
/**< FLAC__seekable_stream_decoder_init() was called without all
* callbacks being set.
*/
FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} FLAC__SeekableStreamDecoderState;
/** Maps a FLAC__SeekableStreamDecoderState to a C string.
*
* Using a FLAC__SeekableStreamDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
/** Return values for the FLAC__SeekableStreamDecoder read callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
/**< The read was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderReadStatus;
/** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder seek callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
/**< The seek was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderSeekStatus;
/** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder tell callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
/**< The tell was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderTellStatus;
/** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder length callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
/**< The length call was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderLengthStatus;
/** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
/***********************************************************************
*
* class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
struct FLAC__SeekableStreamDecoderProtected;
struct FLAC__SeekableStreamDecoderPrivate;
/** The opaque structure definition for the seekable stream decoder type.
* See the
* \link flac_seekable_stream_decoder seekable stream decoder module \endlink
* for a detailed description.
*/
typedef struct {
struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamDecoder;
/** Signature for the read callback.
* See FLAC__seekable_stream_decoder_set_read_callback()
* and FLAC__StreamDecoderReadCallback for more info.
*
* \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.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderReadStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the seek callback.
* See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
*
* \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__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderSeekStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
* See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
*
* \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__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderTellStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the length callback.
* See FLAC__seekable_stream_decoder_set_length_callback() for more info.
*
* \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__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderLengthStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
/** Signature for the EOF callback.
* See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__bool
* \c true if the currently at the end of the stream, else \c false.
*/
typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
/** Signature for the write callback.
* See FLAC__seekable_stream_decoder_set_write_callback()
* and FLAC__StreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See FLAC__seekable_stream_decoder_set_metadata_callback()
* and FLAC__StreamDecoderMetadataCallback for more info.
*
* \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__seekable_stream_decoder_set_client_data().
*/
typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__seekable_stream_decoder_set_error_callback()
* and FLAC__StreamDecoderErrorCallback for more info.
*
* \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__seekable_stream_decoder_set_client_data().
*/
typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new seekable stream decoder instance. The instance is created
* with default settings; see the individual
* FLAC__seekable_stream_decoder_set_*() functions for each setting's
* default.
*
* \retval FLAC__SeekableStreamDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
/** 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__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** 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__seekable_stream_decoder_finish().
*
* MD5 signature checking will be turned off (until the next
* FLAC__seekable_stream_decoder_reset()) if there is no signature in
* the STREAMINFO block or when a seek is attempted.
*
* \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__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
/** Set the read callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_read_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderReadCallback value);
/** Set the seek callback.
* 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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderSeekCallback value);
/** Set the tell callback.
* 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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderTellCallback value);
/** Set the length callback.
* The supplied function will be called when the decoder wants to know
* the total length of the stream in bytes.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderLengthCallback value);
/** Set the eof callback.
* The supplied function will be called when the decoder needs to know
* if the end of the stream has been reached.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_error_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param 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__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_respond().
*
* \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__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_respond_application().
*
* \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__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_respond_all().
*
* \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__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_ignore().
*
* \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__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_ignore_application().
*
* \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__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_ignore_all().
*
* \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__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* The current decoder state.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
/** Get the state of the underlying stream decoder.
* Useful when the seekable stream decoder state is
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The stream decoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
* stream decoder's state.
*
* \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__seekable_stream_decoder_get_resolved_state_string(const FLAC__SeekableStreamDecoder *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__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__ChannelAssignment
* See above.
*/
FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *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.
*
* \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 there was an error from
* the 'tell' callback.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
* Should be called after FLAC__seekable_stream_decoder_new() and
* FLAC__seekable_stream_decoder_set_*() but before any of the
* FLAC__seekable_stream_decoder_process_*() functions. Will set and return
* the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
* successful; see FLAC__SeekableStreamDecoderState for the meanings
* of other return values.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before
* FLAC__seekable_stream_decoder_delete() but it is good practice to match
* every FLAC__seekable_stream_decoder_init() with a
* FLAC__seekable_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__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
/** Flush the stream input.
* The decoder's input buffer will be cleared and the state set to
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. 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
* or stream decoder error occurs.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
/** Reset the decoding process.
* The decoder's input buffer will be cleared and the state set to
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to
* FLAC__seekable_stream_decoder_finish() except that the settings are
* preserved; there is no need to call FLAC__seekable_stream_decoder_init()
* before decoding again. MD5 checking will be restored to its original
* setting.
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* or stream decoder error occurs.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_skip_single_frame().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__SeekableStreamDecoder *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.
*
* \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__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

992
apps/codecs/libFLAC/include/FLAC/seekable_stream_encoder.h Normal file
View file

@ -0,0 +1,992 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2002,2003,2004,2005 Josh Coalson
*
* 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__SEEKABLE_STREAM_ENCODER_H
#define FLAC__SEEKABLE_STREAM_ENCODER_H
#include "export.h"
#include "stream_encoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/seekable_stream_encoder.h
*
* \brief
* This module contains the functions which implement the seekable stream
* encoder.
*
* See the detailed documentation in the
* \link flac_seekable_stream_encoder seekable stream encoder \endlink module.
*/
/** \defgroup flac_seekable_stream_encoder FLAC/seekable_stream_encoder.h: seekable stream encoder interface
* \ingroup flac_encoder
*
* \brief
* This module contains the functions which implement the seekable stream
* encoder.
*
* The basic usage of this encoder is as follows:
* - The program creates an instance of an encoder using
* FLAC__seekable_stream_encoder_new().
* - The program overrides the default settings and sets callbacks using
* FLAC__seekable_stream_encoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for encoding using FLAC__seekable_stream_encoder_init().
* - The program calls FLAC__seekable_stream_encoder_process() or
* FLAC__seekable_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__seekable_stream_encoder_finish(),
* which causes the encoder to encode any data still in its input pipe,
* rewrite the metadata with the final encoding statistics, and finally
* reset the encoder to the uninitialized state.
* - The instance may be used again or deleted with
* FLAC__seekable_stream_encoder_delete().
*
* The seekable stream encoder is a wrapper around the
* \link flac_stream_encoder stream encoder \endlink with callbacks for
* seeking the output and reporting the output stream position. This
* allows the encoder to go back and rewrite some of the metadata after
* encoding if necessary, and provides the metadata callback of the stream
* encoder internally. However, you must provide seek and tell callbacks
* (see FLAC__seekable_stream_encoder_set_seek_callback() and
* FLAC__seekable_stream_encoder_set_tell_callback()).
*
* Make sure to read the detailed description of the
* \link flac_stream_encoder stream encoder module \endlink since the
* seekable stream encoder inherits much of its behavior.
*
* \note
* If you are writing the FLAC data to a file, 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.
*
* \note
* The "set" functions may only be called when the encoder is in the
* state FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED, i.e. after
* FLAC__seekable_stream_encoder_new() or FLAC__seekable_stream_encoder_finish(), but
* before FLAC__seekable_stream_encoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__seekable_stream_encoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
*
* \{
*/
/** State values for a FLAC__SeekableStreamEncoder
*
* The encoder's state can be obtained by calling FLAC__seekable_stream_encoder_get_state().
*/
typedef enum {
FLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying stream encoder;
* check FLAC__seekable_stream_encoder_get_stream_encoder_state().
*/
FLAC__SEEKABLE_STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
FLAC__SEEKABLE_STREAM_ENCODER_WRITE_ERROR,
/**< The write callback returned an error. */
FLAC__SEEKABLE_STREAM_ENCODER_READ_ERROR,
/**< The read callback returned an error. */
FLAC__SEEKABLE_STREAM_ENCODER_SEEK_ERROR,
/**< The seek callback returned an error. */
FLAC__SEEKABLE_STREAM_ENCODER_TELL_ERROR,
/**< The tell callback returned an error. */
FLAC__SEEKABLE_STREAM_ENCODER_ALREADY_INITIALIZED,
/**< FLAC__seekable_stream_encoder_init() was called when the encoder was
* already initialized, usually because
* FLAC__seekable_stream_encoder_finish() was not called.
*/
FLAC__SEEKABLE_STREAM_ENCODER_INVALID_CALLBACK,
/**< FLAC__seekable_stream_encoder_init() was called without all
* callbacks being set.
*/
FLAC__SEEKABLE_STREAM_ENCODER_INVALID_SEEKTABLE,
/**< An invalid seek table was passed is the metadata to
* FLAC__seekable_stream_encoder_set_metadata().
*/
FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} FLAC__SeekableStreamEncoderState;
/** Maps a FLAC__SeekableStreamEncoderState to a C string.
*
* Using a FLAC__SeekableStreamEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamEncoderStateString[];
/** Return values for the FLAC__SeekableStreamEncoder seek callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_OK,
/**< The seek was OK and encoding can continue. */
FLAC__SEEKABLE_STREAM_ENCODER_SEEK_STATUS_ERROR
/**< An unrecoverable error occurred. The encoder will return from the process call. */
} FLAC__SeekableStreamEncoderSeekStatus;
/** Maps a FLAC__SeekableStreamEncoderSeekStatus to a C string.
*
* Using a FLAC__SeekableStreamEncoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamEncoderSeekStatusString[];
/** Return values for the FLAC__SeekableStreamEncoder tell callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_OK,
/**< The tell was OK and encoding can continue. */
FLAC__SEEKABLE_STREAM_ENCODER_TELL_STATUS_ERROR
/**< An unrecoverable error occurred. The encoder will return from the process call. */
} FLAC__SeekableStreamEncoderTellStatus;
/** Maps a FLAC__SeekableStreamEncoderTellStatus to a C string.
*
* Using a FLAC__SeekableStreamEncoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamEncoderTellStatusString[];
/***********************************************************************
*
* class FLAC__SeekableStreamEncoder
*
***********************************************************************/
struct FLAC__SeekableStreamEncoderProtected;
struct FLAC__SeekableStreamEncoderPrivate;
/** The opaque structure definition for the seekable stream encoder type.
* See the \link flac_seekable_stream_encoder seekable stream encoder module \endlink
* for a detailed description.
*/
typedef struct {
struct FLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamEncoder;
/** Signature for the seek callback.
* See FLAC__seekable_stream_encoder_set_seek_callback() for more info.
*
* \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__seekable_stream_encoder_set_client_data().
* \retval FLAC__SeekableStreamEncoderSeekStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamEncoderSeekStatus (*FLAC__SeekableStreamEncoderSeekCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
* See FLAC__seekable_stream_encoder_set_tell_callback() for more info.
*
* \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.
*
* \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__seekable_stream_encoder_set_client_data().
* \retval FLAC__SeekableStreamEncoderTellStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamEncoderTellStatus (*FLAC__SeekableStreamEncoderTellCallback)(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the write callback.
* See FLAC__seekable_stream_encoder_set_write_callback()
* and FLAC__StreamEncoderWriteCallback for more info.
*
* \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
* FLAC__stream_encoder_set_write_callback().
* \param current_frame The number of current frame being encoded.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_encoder_set_client_data().
* \retval FLAC__StreamEncoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderWriteStatus (*FLAC__SeekableStreamEncoderWriteCallback)(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new seekable stream encoder instance. The instance is created with
* default settings; see the individual FLAC__seekable_stream_encoder_set_*()
* functions for each setting's default.
*
* \retval FLAC__SeekableStreamEncoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__SeekableStreamEncoder *FLAC__seekable_stream_encoder_new();
/** 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__seekable_stream_encoder_delete(FLAC__SeekableStreamEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_verify().
*
* \default \c true
* \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__seekable_stream_encoder_set_verify(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_streamable_subset().
*
* \default \c true
* \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__seekable_stream_encoder_set_streamable_subset(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_do_mid_side_stereo().
*
* \default \c false
* \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__seekable_stream_encoder_set_do_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_loose_mid_side_stereo().
*
* \default \c false
* \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__seekable_stream_encoder_set_loose_mid_side_stereo(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_channels().
*
* \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__seekable_stream_encoder_set_channels(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_bits_per_sample().
*
* \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__seekable_stream_encoder_set_bits_per_sample(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_sample_rate().
*
* \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__seekable_stream_encoder_set_sample_rate(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_blocksize().
*
* \default \c 1152
* \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__seekable_stream_encoder_set_blocksize(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_max_lpc_order().
*
* \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__seekable_stream_encoder_set_max_lpc_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_qlp_coeff_precision().
*
* \note
* In the current implementation, qlp_coeff_precision + bits_per_sample must
* be less than 32.
*
* \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__seekable_stream_encoder_set_qlp_coeff_precision(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_do_qlp_coeff_prec_search().
*
* \default \c false
* \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__seekable_stream_encoder_set_do_qlp_coeff_prec_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_do_escape_coding().
*
* \default \c false
* \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__seekable_stream_encoder_set_do_escape_coding(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_do_exhaustive_model_search().
*
* \default \c false
* \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__seekable_stream_encoder_set_do_exhaustive_model_search(FLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_min_residual_partition_order().
*
* \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__seekable_stream_encoder_set_min_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_max_residual_partition_order().
*
* \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__seekable_stream_encoder_set_max_residual_partition_order(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_rice_parameter_search_dist().
*
* \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__seekable_stream_encoder_set_rice_parameter_search_dist(FLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_total_samples_estimate().
*
* \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__seekable_stream_encoder_set_total_samples_estimate(FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
/** This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_metadata().
*
* \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. While
* encoding, the encoder will fill them 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_*().
*
* \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.
*
* \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.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_metadata(FLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the seek callback.
* 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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_seek_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderSeekCallback value);
/** Set the tell callback.
* The supplied function will be called when the encoder needs to know
* the current position of the output stream.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_tell_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderTellCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param encoder An encoder instance to set.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_set_write_callback(FLAC__SeekableStreamEncoder *encoder, FLAC__SeekableStreamEncoderWriteCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \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__seekable_stream_encoder_set_client_data(FLAC__SeekableStreamEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__SeekableStreamEncoderState
* The current encoder state.
*/
FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_get_state(const FLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying stream encoder.
* Useful when the seekable stream encoder state is
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* The stream encoder state.
*/
FLAC_API FLAC__StreamEncoderState FLAC__seekable_stream_encoder_get_stream_encoder_state(const FLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
* Useful when the seekable stream encoder state is
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and 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 stream encoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_encoder_get_verify_decoder_state(const FLAC__SeekableStreamEncoder *encoder);
/** Get the current encoder state as a C string.
* This version automatically resolves
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR by getting the
* stream encoder'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__seekable_stream_encoder_get_resolved_state_string(const FLAC__SeekableStreamEncoder *encoder);
/** Get relevant values about the nature of a verify decoder error.
* Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
* Useful when the seekable stream encoder state is
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR and the
* stream encoder state is
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \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__seekable_stream_encoder_get_verify_decoder_error_stats(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
/** Get the "verify" flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_verify().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_verify(const FLAC__SeekableStreamEncoder *encoder);
/** Get the "streamable subset" flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_streamable_subset().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_streamable_subset().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_streamable_subset(const FLAC__SeekableStreamEncoder *encoder);
/** Get the "mid/side stereo coding" flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_do_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
/** Get the "adaptive mid/side switching" flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_loose_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_loose_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const FLAC__SeekableStreamEncoder *encoder);
/** Get the number of input channels being processed.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_channels().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_channels().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_channels(const FLAC__SeekableStreamEncoder *encoder);
/** Get the input sample resolution setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_bits_per_sample().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_bits_per_sample().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_bits_per_sample(const FLAC__SeekableStreamEncoder *encoder);
/** Get the input sample rate setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_sample_rate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_sample_rate().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_sample_rate(const FLAC__SeekableStreamEncoder *encoder);
/** Get the blocksize setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_blocksize().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_blocksize().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_blocksize(const FLAC__SeekableStreamEncoder *encoder);
/** Get the maximum LPC order setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_max_lpc_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_max_lpc_order().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_lpc_order(const FLAC__SeekableStreamEncoder *encoder);
/** Get the quantized linear predictor coefficient precision setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_qlp_coeff_precision().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_qlp_coeff_precision().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_qlp_coeff_precision(const FLAC__SeekableStreamEncoder *encoder);
/** Get the qlp coefficient precision search flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_do_qlp_coeff_prec_search().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const FLAC__SeekableStreamEncoder *encoder);
/** Get the "escape coding" flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_do_escape_coding().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_do_escape_coding().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_escape_coding(const FLAC__SeekableStreamEncoder *encoder);
/** Get the exhaustive model search flag.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_do_exhaustive_model_search().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__seekable_stream_encoder_set_do_exhaustive_model_search().
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const FLAC__SeekableStreamEncoder *encoder);
/** Get the minimum residual partition order setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_min_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_min_residual_partition_order().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_min_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
/** Get maximum residual partition order setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_max_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_max_residual_partition_order().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_max_residual_partition_order(const FLAC__SeekableStreamEncoder *encoder);
/** Get the Rice parameter search distance setting.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_rice_parameter_search_dist().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__seekable_stream_encoder_set_rice_parameter_search_dist().
*/
FLAC_API unsigned FLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const FLAC__SeekableStreamEncoder *encoder);
/** Get the previously set estimate of the total samples to be encoded.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_get_total_samples_estimate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__uint64
* See FLAC__seekable_stream_encoder_set_total_samples_estimate().
*/
FLAC_API FLAC__uint64 FLAC__seekable_stream_encoder_get_total_samples_estimate(const FLAC__SeekableStreamEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after FLAC__seekable_stream_encoder_new() and
* FLAC__seekable_stream_encoder_set_*() but before FLAC__seekable_stream_encoder_process()
* or FLAC__seekable_stream_encoder_process_interleaved(). Will set and return
* the encoder state, which will be FLAC__SEEKABLE_STREAM_ENCODER_OK if
* initialization succeeded.
*
* The call to FLAC__seekable_stream_encoder_init() currently will also immediately
* call the write callback with the \c fLaC signature and all the encoded
* metadata.
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__SeekableStreamEncoderState
* \c FLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
* FLAC__SeekableStreamEncoderState for the meanings of other return values.
*/
FLAC_API FLAC__SeekableStreamEncoderState FLAC__seekable_stream_encoder_init(FLAC__SeekableStreamEncoder *encoder);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* FLAC__SEEKABLE_STREAM_ENCODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before FLAC__seekable_stream_encoder_delete()
* but it is good practice to match every FLAC__seekable_stream_encoder_init()
* with a FLAC__seekable_stream_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
FLAC_API void FLAC__seekable_stream_encoder_finish(FLAC__SeekableStreamEncoder *encoder);
/** Submit data for encoding.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_process().
*
* \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__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__seekable_stream_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Submit data for encoding.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_process_interleaved().
*
* \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__seekable_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__seekable_stream_encoder_get_state(encoder) == FLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__seekable_stream_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_encoder_process_interleaved(FLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

873
apps/codecs/libFLAC/include/FLAC/stream_decoder.h Normal file
View file

@ -0,0 +1,873 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005 Josh Coalson
*
* 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 "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 three decoder layers provided by libFLAC.
*
* For decoding FLAC streams, libFLAC provides three layers of access. The
* lowest layer is non-seekable stream-level decoding, the next is seekable
* stream-level decoding, and the highest layer is file-level decoding. The
* interfaces are described in the \link flac_stream_decoder stream decoder
* \endlink, \link flac_seekable_stream_decoder seekable stream decoder
* \endlink, and \link flac_file_decoder file decoder \endlink modules
* respectively. Typically you will choose the highest layer that your input
* source will support.
*
* The stream decoder relies on callbacks for all input and output and has no
* provisions for seeking. The seekable stream decoder wraps the stream
* decoder and exposes functions for seeking. However, you must provide
* extra callbacks for seek-related operations on your stream, like seek and
* tell. The file decoder wraps the seekable stream decoder and supplies
* most of the callbacks internally, simplifying the processing of standard
* files.
*/
/** \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 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 and sets callbacks for
* reading, writing, error reporting, and metadata reporting using
* FLAC__stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__stream_decoder_init().
* - 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 set the callbacks and client data, and call
* FLAC__stream_decoder_init(). The required callbacks are:
*
* - Read callback - This 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.
* - Write callback - This function will be called when the decoder has
* decoded a single frame of data. The decoder will pass the frame
* metadata as well as an array of pointers (one for each channel)
* pointing to the decoded audio.
* - Metadata callback - This function will be called when the decoder has
* decoded a metadata block. In a valid FLAC file there will always be
* one 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 STREAMINFO
* block; you can instruct the decoder to pass or filter other blocks with
* FLAC__stream_decoder_set_metadata_*() calls.
* - Error callback - This function will be called whenever an error occurs
* during decoding.
*
* 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 user 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 user 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.
*
* Note that the stream decoder has no real concept of stream position, it
* just converts data. To seek within a stream the callbacks have only to
* flush the decoder using FLAC__stream_decoder_flush() and start feeding
* data from the new position through the read callback. The seekable
* stream decoder does just this.
*
* 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 some metadata blocks can be big 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_ABORTED,
/**< The decoder was aborted by the read callback. */
FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
/**< The decoder encountered reserved fields in use in the stream. */
FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
/**< FLAC__stream_decoder_init() was called when the decoder was
* already initialized, usually because
* FLAC__stream_decoder_finish() was not called.
*/
FLAC__STREAM_DECODER_INVALID_CALLBACK,
/**< FLAC__stream_decoder_init() was called without all callbacks being set. */
FLAC__STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} 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[];
/** 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 at the end of the stream. */
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 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 in to the FLAC__StreamDecoder error callback.
*/
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__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.
* See FLAC__stream_decoder_set_read_callback() for more info.
*
* \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_set_client_data().
* \retval FLAC__StreamDecoderReadStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the write callback.
* See FLAC__stream_decoder_set_write_callback() for more info.
*
* \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.
* Currently, the channel order has no meaning
* except for stereo streams; in this case channel
* 0 is left and 1 is right.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_set_client_data().
* \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.
* See FLAC__stream_decoder_set_metadata_callback() for more info.
*
* \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_set_client_data().
*/
typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__stream_decoder_set_error_callback() for more info.
*
* \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_set_client_data().
*/
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();
/** 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 read callback.
* 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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
/** Set the write callback.
* The supplied function will be called when the decoder has decoded a
* single frame of data. The decoder will pass the frame metadata as
* well as an array of pointers (one for each channel) pointing to the
* decoded audio.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
/** Set the metadata callback.
* The supplied function will be called when the decoder has decoded a metadata
* block. In a valid FLAC file there will always be one 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 STREAMINFO block; you can instruct
* the decoder to pass or filter other blocks with
* FLAC__stream_decoder_set_metadata_*() calls.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != 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_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
/** Set the error callback.
* The supplied function will be called whenever an error occurs during
* decoding.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
/** Set the client data to be passed back to callbacks.
* This value will be supplied to callbacks in their \a client_data
* argument.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param 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_client_data(FLAC__StreamDecoder *decoder, void *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 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);
/** Initialize the decoder instance.
* 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.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
* successful; see FLAC__StreamDecoderState for the meanings of other
* return values.
*/
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
/** 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
*/
FLAC_API void 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.
*
* \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.
*/
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.
*
* \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.
*/
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 an error
* occurred. If the decoder loses sync it will call the error callback
* instead.
*
* 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
* 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 read or write error occurred (except
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
*/
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. If the decoder loses sync it will call the
* error callback.
*
* \param decoder An initialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
*/
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. If the
* decoder loses sync it will call the error callback.
*
* \param decoder An initialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if any read or write error occurred (except
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
*/
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, when used from the higher FLAC__SeekableStreamDecoder
* layer, 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__seekable_stream_decoder_skip_single_frame() to quickly advance
* to the next frame, then use
* FLAC__seekable_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 read or write error occurred (except
* \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), or if the decoder
* is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
* FLAC__STREAM_DECODER_READ_METADATA state, else \c true;
* in any case, check the decoder state with
* FLAC__stream_decoder_get_state() to see what went wrong or to
* check for lost synchronization (a sign of stream corruption).
*/
FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

1064
apps/codecs/libFLAC/include/FLAC/stream_encoder.h Normal file
View file

File diff suppressed because it is too large Load diff