constants.h   constants.h 
skipping to change at line 58 skipping to change at line 58
/** Identifiers for supported codecs */ /** Identifiers for supported codecs */
typedef enum _FishSoundCodecID { typedef enum _FishSoundCodecID {
/** Unknown */ /** Unknown */
FISH_SOUND_UNKNOWN = 0x00, FISH_SOUND_UNKNOWN = 0x00,
/** Vorbis */ /** Vorbis */
FISH_SOUND_VORBIS = 0x01, FISH_SOUND_VORBIS = 0x01,
/** Speex */ /** Speex */
FISH_SOUND_SPEEX = 0x02 FISH_SOUND_SPEEX = 0x02,
/** Flac */
FISH_SOUND_FLAC = 0x03
} FishSoundCodecID; } FishSoundCodecID;
/** Decode callback return values */ /** Decode callback return values */
typedef enum _FishSoundStopCtl { typedef enum _FishSoundStopCtl {
/** Continue calling decode callbacks */ /** Continue calling decode callbacks */
FISH_SOUND_CONTINUE = 0, FISH_SOUND_CONTINUE = 0,
/** Stop calling callbacks, but retain buffered data */ /** Stop calling callbacks, but retain buffered data */
FISH_SOUND_STOP_OK = 1, FISH_SOUND_STOP_OK = 1,
skipping to change at line 82 skipping to change at line 85
/** Command codes */ /** Command codes */
typedef enum _FishSoundCommand { typedef enum _FishSoundCommand {
/** No operation */ /** No operation */
FISH_SOUND_COMMAND_NOP = 0x0000, FISH_SOUND_COMMAND_NOP = 0x0000,
/** Retrieve the FishSoundInfo */ /** Retrieve the FishSoundInfo */
FISH_SOUND_GET_INFO = 0x1000, FISH_SOUND_GET_INFO = 0x1000,
/** Query if multichannel audio should be interpreted as interleaved */ /** Query if multichannel audio should be interpreted as interleaved */
FISH_SOUND_GET_INTERLEAVE = 0x2000, FISH_SOUND_GET_INTERLEAVE = 0x2000,
/** Set to 1 to interleave, 0 to non-interleave */ /** Set to 1 to interleave, 0 to non-interleave */
FISH_SOUND_SET_INTERLEAVE = 0x2001, FISH_SOUND_SET_INTERLEAVE = 0x2001,
FISH_SOUND_SET_ENCODE_VBR = 0x4000, FISH_SOUND_SET_ENCODE_VBR = 0x4000,
FISH_SOUND_COMMAND_MAX FISH_SOUND_COMMAND_MAX
} FishSoundCommand; } FishSoundCommand;
/** Error values */ /** Error values */
typedef enum _FishSoundError { typedef enum _FishSoundError {
/** No error */ /** No error */
FISH_SOUND_OK = 0, FISH_SOUND_OK = 0,
 End of changes. 3 change blocks. 
3 lines changed or deleted 6 lines changed or added


 fishsound.h   fishsound.h 
skipping to change at line 44 skipping to change at line 44
#define __FISH_SOUND_H__ #define __FISH_SOUND_H__
#include <fishsound/constants.h> #include <fishsound/constants.h>
/** \mainpage /** \mainpage
* *
* \section intro FishSound, the sound of fish! * \section intro FishSound, the sound of fish!
* *
* This is the documentation for the FishSound C API. FishSound provides * This is the documentation for the FishSound C API. FishSound provides
* a simple programming interface for decoding and encoding audio data * a simple programming interface for decoding and encoding audio data
* using Xiph.Org codecs (Vorbis and Speex). * using Xiph.Org codecs (FLAC, Speex and Vorbis).
* *
* libfishsound by itself is designed to handle raw codec streams from * libfishsound by itself is designed to handle raw codec streams from
* a lower level layer such as UDP datagrams. * a lower level layer such as UDP datagrams.
* When these codecs are used in files, they are commonly encapsulated in * When these codecs are used in files, they are commonly encapsulated in
* <a href="http://www.xiph.org/ogg/">Ogg</a> to produce * <a href="http://www.xiph.org/ogg/">Ogg</a> to produce
* <em>Ogg Vorbis</em> and <em>Speex</em> files. * <em>Ogg FLAC</em>, <em>Speex</em> and <em>Ogg Vorbis</em> files.
* Example C programs using * Example C programs using
* <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to * <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to
* read and write these files are provided in the libfishsound sources. * read and write these files are provided in the libfishsound sources.
* *
* For more information on the design and history of libfishsound, see the * For more information on the design and history of libfishsound, see the
* \link about About \endlink section of this documentation, and the * \link about About \endlink section of this documentation, and the
* <a href="http://www.annodex.net/software/libfishsound/">libfishsound</a> * <a href="http://www.annodex.net/software/libfishsound/">libfishsound</a>
* homepage. * homepage.
* *
* \subsection contents Contents * \subsection contents Contents
* *
* - \link fishsound.h fishsound.h \endlink: * - \link fishsound.h fishsound.h \endlink:
* Documentation of the FishSound API. * Documentation of the FishSound API.
* *
* - \link comments.h Handling comments \endlink: * - \link comments.h Handling comments \endlink:
* How to add and retrieve \a name = \a value metadata in Vorbis and Speex * How to add and retrieve \a name = \a value metadata in Vorbis and Speex
* streams. * streams.
* *
* - \link decode Decoding audio data \endlink: * - \link decode Decoding audio data \endlink:
* How to decode audio data with FishSound, including source for a fully * How to decode audio data with FishSound, including source for a fully
* working Ogg Vorbis and Ogg Speex decoder. * working Ogg FLAC, Speex and Ogg Vorbis decoder.
* *
* - \link encode Encoding audio data \endlink: * - \link encode Encoding audio data \endlink:
* How to encode audio data with FishSound, including source for a fully * How to encode audio data with FishSound, including source for a fully
* working Ogg Vorbis and Ogg Speex encoder. * working Ogg FLAC, Speex and Ogg Vorbis encoder.
* *
* - \link configuration Configuration \endlink: * - \link configuration Configuration \endlink:
* Customizing libfishsound to only decode or encode, * Customizing libfishsound to only decode or encode,
* or to disable support for a particular codec. * or to disable support for a particular codec.
* *
* - \link building Building \endlink: * - \link building Building \endlink:
* Information related to building software that uses libfishsound. * Information related to building software that uses libfishsound.
* *
* - \link about About \endlink: * - \link about About \endlink:
* Design, motivation, history and acknowledgements. * Design, motivation, history and acknowledgements.
skipping to change at line 106 skipping to change at line 106
* *
* \section design Design * \section design Design
* libfishsound provides a simple programming interface for decoding and * libfishsound provides a simple programming interface for decoding and
* encoding audio data using codecs from * encoding audio data using codecs from
* <a href="http://www.xiph.org/">Xiph.Org</a>. * <a href="http://www.xiph.org/">Xiph.Org</a>.
* *
* libfishsound by itself is designed to handle raw codec streams from * libfishsound by itself is designed to handle raw codec streams from
* a lower level layer such as UDP datagrams. * a lower level layer such as UDP datagrams.
* When these codecs are used in files, they are commonly encapsulated in * When these codecs are used in files, they are commonly encapsulated in
* <a href="http://www.xiph.org/ogg/">Ogg</a> to produce * <a href="http://www.xiph.org/ogg/">Ogg</a> to produce
* <em>Ogg Vorbis</em> and <em>Speex</em> files. * <em>Ogg FLAC</em>, <em>Speex</em> and <em>Ogg Vorbis</em> files.
* Example C programs using * Example C programs using
* <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to * <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to
* read and write these files are provided in the libfishsound sources. * read and write these files are provided in the libfishsound sources.
* *
* libfishsound is implemented as a wrapper around the existing codec * libfishsound is implemented as a wrapper around the existing codec
* libraries and provides a consistent, higher-level programming * libraries and provides a consistent, higher-level programming
* interface. The motivation for this is twofold: to simplify the task * interface. The motivation for this is twofold: to simplify the task
* of developing application software that supports these codecs, * of developing application software that supports these codecs,
* and to ensure that valid codec streams are generated. * and to ensure that valid codec streams are generated.
* *
skipping to change at line 199 skipping to change at line 199
* *
* \subsection no_decode Removing decoding support * \subsection no_decode Removing decoding support
* *
* Configuring with \a --disable-decode will remove all support for decodin g: * Configuring with \a --disable-decode will remove all support for decodin g:
* - All internal decoding related functions will not be built * - All internal decoding related functions will not be built
* - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_DECODE * - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_DECODE
* will fail, returning NULL * will fail, returning NULL
* - Any attempt to call fish_sound_decode() will return * - Any attempt to call fish_sound_decode() will return
* FISH_SOUND_ERR_DISABLED * FISH_SOUND_ERR_DISABLED
* *
* \subsection no_vorbis Removing Vorbis support * \subsection no_flac Removing FLAC support
* *
* Configuring with \a --disable-vorbis will remove all support for Vorbis: * Configuring with \a --disable-flac will remove all support for FLAC:
* - All internal Vorbis related functions will not be built * - All internal FLAC related functions will not be built
* - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_ENCODE * - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_ENCODE
* and \a fsinfo->format == FISH_SOUND_VORBIS will fail, returning NULL * and \a fsinfo->format == FISH_SOUND_FLAC will fail, returning NULL
* - The resulting library will not be linked against libvorbis or libvorbi * - The resulting library will not be linked against libFLAC
senc
* *
* \subsection no_speex Removing Speex support * \subsection no_speex Removing Speex support
* *
* Configuring with \a --disable-speex will remove all support for Speex: * Configuring with \a --disable-speex will remove all support for Speex:
* - All internal Speex related functions will not be built * - All internal Speex related functions will not be built
* - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_ENCODE * - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_ENCODE
* and \a fsinfo->format == FISH_SOUND_SPEEX will fail, returning NULL * and \a fsinfo->format == FISH_SOUND_SPEEX will fail, returning NULL
* - The resulting library will not be linked against libspeex * - The resulting library will not be linked against libspeex
* *
* \subsection no_vorbis Removing Vorbis support
*
* Configuring with \a --disable-vorbis will remove all support for Vorbis:
* - All internal Vorbis related functions will not be built
* - Any attempt to call fish_sound_new() with \a mode == FISH_SOUND_ENCODE
* and \a fsinfo->format == FISH_SOUND_VORBIS will fail, returning NULL
* - The resulting library will not be linked against libvorbis or libvorbi
senc
*
* \subsection summary Configuration summary * \subsection summary Configuration summary
* *
* Upon successful configuration, you should see something like this: * Upon successful configuration, you should see something like this:
<pre> <pre>
------------------------------------------------------------------------ ------------------------------------------------------------------------
libfishsound 0.6.0: Automatic configuration OK. libfishsound 0.9.0: Automatic configuration OK.
General configuration: General configuration:
Experimental code: ........... no Experimental code: ........... no
Decoding support: ............ yes Decoding support: ............ yes
Encoding support: ............ yes Encoding support: ............ yes
Library configuration (./src/libfishsound): Library configuration (./src/libfishsound):
FLAC support: ................ yes
Speex support: ............... yes (1.1.x)
Vorbis support: .............. yes Vorbis support: .............. yes
Speex support: ............... yes
Example programs (./src/examples): Example programs (./src/examples):
identify decode encode fishsound-identify fishsound-decode fishsound-encode
Installation paths: Installation paths:
libfishsound: ................ /usr/local/lib libfishsound: ................ /usr/local/lib
C header files: .............. /usr/local/include/fishsound C header files: .............. /usr/local/include/fishsound
Documentation: ............... /usr/local/share/doc/libfishsound Documentation: ............... /usr/local/share/doc/libfishsound
Building:
Type 'make' to compile libfishsound.
Type 'make install' to install libfishsound.
Type 'make check' to run test suite (Valgrind testing not enabled)
Example programs will be built but not installed. Example programs will be built but not installed.
------------------------------------------------------------------------ ------------------------------------------------------------------------
</pre> </pre>
*/ */
/** \defgroup install Installation /** \defgroup install Installation
* \section install INSTALL * \section install INSTALL
* *
* \include INSTALL * \include INSTALL
*/ */
skipping to change at line 277 skipping to change at line 294
* available: * available:
* *
<pre> <pre>
PKG_CHECK_MODULES(FISHSOUND, fishsound >= 0.6.0, PKG_CHECK_MODULES(FISHSOUND, fishsound >= 0.6.0,
HAVE_FISHSOUND="yes", HAVE_FISHSOUND="no") HAVE_FISHSOUND="yes", HAVE_FISHSOUND="no")
if test "x$HAVE_FISHSOUND" = "xyes" ; then if test "x$HAVE_FISHSOUND" = "xyes" ; then
AC_SUBST(FISHSOUND_CFLAGS) AC_SUBST(FISHSOUND_CFLAGS)
AC_SUBST(FISHSOUND_LIBS) AC_SUBST(FISHSOUND_LIBS)
fi fi
</pre> </pre>
* (Note that if your application requires FLAC support, you should check
* for a version of fishsound >= 0.9.0).
* *
* If libfishsound is found, HAVE_FISHSOUND will be set to "yes", and * If libfishsound is found, HAVE_FISHSOUND will be set to "yes", and
* the autoconf variables FISHSOUND_CFLAGS and FISHSOUND_LIBS will * the autoconf variables FISHSOUND_CFLAGS and FISHSOUND_LIBS will
* be set appropriately. * be set appropriately.
* *
* \section pkg-config Determining compiler options with pkg-config * \section pkg-config Determining compiler options with pkg-config
* *
* If you are not using GNU autoconf in your project, you can use the * If you are not using GNU autoconf in your project, you can use the
* pkg-config tool directly to determine the correct compiler options. * pkg-config tool directly to determine the correct compiler options.
* *
skipping to change at line 310 skipping to change at line 329
* All access is managed via a FishSound* handle. This is instantiated * All access is managed via a FishSound* handle. This is instantiated
* using fish_sound_new() and should be deleted with fish_sound_delete() * using fish_sound_new() and should be deleted with fish_sound_delete()
* when no longer required. If there is a discontinuity in the input * when no longer required. If there is a discontinuity in the input
* data (eg. after seeking in an input file), call fish_sound_reset() to * data (eg. after seeking in an input file), call fish_sound_reset() to
* reset the internal codec state. * reset the internal codec state.
* *
* \section decoding Decoding * \section decoding Decoding
* *
* libfishsound provides callback based decoding: you feed it encoded audio * libfishsound provides callback based decoding: you feed it encoded audio
* data, and it will call your callback with decoded PCM. A more detailed * data, and it will call your callback with decoded PCM. A more detailed
* explanation and a full example of decoding Ogg Vorbis and Speex files is * explanation and a full example of decoding Ogg FLAC, Speex and Ogg Vorbi
* provided in the \link decode Decoding audio data \endlink section. s
* files is provided in the \link decode Decoding audio data \endlink secti
on.
* *
* \section encoding Encoding * \section encoding Encoding
* *
* libfishsound provides callback based encoding: you feed it PCM audio, * libfishsound provides callback based encoding: you feed it PCM audio,
* and it will call your callback with encoded audio data. A more detailed * and it will call your callback with encoded audio data. A more detailed
* explanation and a full example of encoding Ogg Vorbis and Speex files is * explanation and a full example of encoding Ogg FLAC, Speex and Ogg Vorbi
* provided in the \link encode Encoding audio data \endlink section. s
* files is provided in the \link encode Encoding audio data \endlink secti
on.
*/ */
/** \defgroup decode Decoding audio data /** \defgroup decode Decoding audio data
* *
* To decode audio data using libfishsound: * To decode audio data using libfishsound:
* *
* - create a FishSound* object with mode FISH_SOUND_DECODE. fish_sound_new () * - create a FishSound* object with mode FISH_SOUND_DECODE. fish_sound_new ()
* will return a new FishSound* object, initialised for decoding, and the * will return a new FishSound* object, initialised for decoding, and the
* FishSoundInfo structure will be cleared. * FishSoundInfo structure will be cleared.
* - provide a FishSoundDecoded_* callback for libfishsound to call when it has * - provide a FishSoundDecoded_* callback for libfishsound to call when it has
skipping to change at line 341 skipping to change at line 360
* per-channel PCM data, using a fish_sound_set_interleave(). * per-channel PCM data, using a fish_sound_set_interleave().
* The default is for per-channel (non-interleaved) PCM. * The default is for per-channel (non-interleaved) PCM.
* - feed encoded audio data to libfishsound via fish_sound_decode(). * - feed encoded audio data to libfishsound via fish_sound_decode().
* libfishsound will decode the audio for you, calling the FishSoundDecoded _* * libfishsound will decode the audio for you, calling the FishSoundDecoded _*
* callback you provided earlier each time it has a block of audio ready. * callback you provided earlier each time it has a block of audio ready.
* - when finished, call fish_sound_delete(). * - when finished, call fish_sound_delete().
* *
* This procedure is illustrated in src/examples/fishsound-decode.c. * This procedure is illustrated in src/examples/fishsound-decode.c.
* Note that this example additionally: * Note that this example additionally:
* - uses <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to * - uses <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to
* demultiplex audio data from an Ogg encapsulated Vorbis or Speex stream. * demultiplex audio data from an Ogg encapsulated FLAC, Speex or Vorbis
* Hence, the step of feeding encoded data to libfishsound is done within * stream. The step of feeding encoded data to libfishsound is done within
* the OggzReadPacket callback. * the OggzReadPacket callback.
* - uses <a href="http://www.mega-nerd.com/libsndfile/">libsndfile</a> to * - uses <a href="http://www.mega-nerd.com/libsndfile/">libsndfile</a> to
* write the decoded audio to a WAV file. * write the decoded audio to a WAV file.
* *
* Hence this example code demonstrates all that is needed to decode both * Hence this example code demonstrates all that is needed to decode
* Ogg Vorbis and Ogg Speex files: * Ogg FLAC, Speex or Ogg Vorbis files:
* *
* \include fishsound-decode.c * \include fishsound-decode.c
*/ */
/** \defgroup encode Encoding audio data /** \defgroup encode Encoding audio data
* *
* To encode audio data using libfishsound: * To encode audio data using libfishsound:
* *
* - create a FishSound* object with mode FISH_SOUND_ENCODE, and with a * - create a FishSound* object with mode FISH_SOUND_ENCODE, and with a
* FishSoundInfo structure filled in with the required encoding parameters. * FishSoundInfo structure filled in with the required encoding parameters.
skipping to change at line 374 skipping to change at line 393
* libfishsound will encode the audio for you, calling the FishSoundEncoded * libfishsound will encode the audio for you, calling the FishSoundEncoded
* callback you provided earlier each time it has a block of encoded audio * callback you provided earlier each time it has a block of encoded audio
* ready. * ready.
* - when finished, call fish_sound_delete(). * - when finished, call fish_sound_delete().
* *
* This procedure is illustrated in src/examples/fishsound-encode.c. * This procedure is illustrated in src/examples/fishsound-encode.c.
* Note that this example additionally: * Note that this example additionally:
* - uses <a href="http://www.mega-nerd.com/libsndfile/">libsndfile</a> to * - uses <a href="http://www.mega-nerd.com/libsndfile/">libsndfile</a> to
* read input from a PCM audio file (WAV, AIFF, etc.) * read input from a PCM audio file (WAV, AIFF, etc.)
* - uses <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to * - uses <a href="http://www.annodex.net/software/liboggz/">liboggz</a> to
* encapsulate the encoded Vorbis or Speex data in an Ogg stream. * encapsulate the encoded FLAC, Speex or Vorbis data in an Ogg stream.
* *
* Hence this example code demonstrates all that is needed to encode * Hence this example code demonstrates all that is needed to encode
* Ogg Vorbis and Ogg Speex files: * Ogg FLAC, Speex and Ogg Vorbis files:
* *
* \include fishsound-encode.c * \include fishsound-encode.c
*/ */
/** /**
* Info about a particular encoder/decoder instance * Info about a particular encoder/decoder instance
*/ */
typedef struct { typedef struct {
/** Sample rate of audio data in Hz */ /** Sample rate of audio data in Hz */
int samplerate; int samplerate;
/** Count of channels */ /** Count of channels */
int channels; int channels;
/** FISH_SOUND_VORBIS, FISH_SOUND_SPEEX etc. */ /** FISH_SOUND_VORBIS, FISH_SOUND_SPEEX, FISH_SOUND_FLAC etc. */
int format; int format;
} FishSoundInfo; } FishSoundInfo;
/** /**
* Info about a particular sound format * Info about a particular sound format
*/ */
typedef struct { typedef struct {
/** FISH_SOUND_VORBIS, FISH_SOUND_SPEEX etc. */ /** FISH_SOUND_VORBIS, FISH_SOUND_SPEEX, FISH_SOUND_FLAC etc. */
int format; int format;
/** Printable name */ /** Printable name */
const char * name; const char * name;
/** Commonly used file extension */ /** Commonly used file extension */
const char * extension; const char * extension;
} FishSoundFormat; } FishSoundFormat;
/** /**
skipping to change at line 424 skipping to change at line 443
typedef void * FishSound; typedef void * FishSound;
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** /**
* Identify a codec based on the first few bytes of data. * Identify a codec based on the first few bytes of data.
* \param buf A pointer to the first few bytes of the data * \param buf A pointer to the first few bytes of the data
* \param bytes The count of bytes available at buf * \param bytes The count of bytes available at buf
* \retval FISH_SOUND_xxxxxx FISH_SOUND_VORBIS, FISH_SOUND_SPEEX if * \retval FISH_SOUND_xxxxxx FISH_SOUND_VORBIS, FISH_SOUND_SPEEX or
* \a buf was identified as the initial bytes of a supported codec * FISH_SOUND_FLAC if \a buf was identified as the initial bytes of a
* supported codec
* \retval FISH_SOUND_UNKNOWN if the codec could not be identified * \retval FISH_SOUND_UNKNOWN if the codec could not be identified
* \retval FISH_SOUND_ERR_SHORT_IDENTIFY if \a bytes is less than 8 * \retval FISH_SOUND_ERR_SHORT_IDENTIFY if \a bytes is less than 8
* \note If \a bytes is exactly 8, then only a weak check is performed, * \note If \a bytes is exactly 8, then only a weak check is performed,
* which is fast but may return a false positive. * which is fast but may return a false positive.
* \note If \a bytes is greater than 8, then a stronger check is performed * \note If \a bytes is greater than 8, then a stronger check is performed
* in which an attempt is made to decode \a buf as the initial header of * in which an attempt is made to decode \a buf as the initial header of
* each supported codec. This is unlikely to return a false positive but * each supported codec. This is unlikely to return a false positive but
* is only useful if \a buf is the entire payload of a packet derived from * is only useful if \a buf is the entire payload of a packet derived from
* a lower layer such as Ogg framing or UDP datagrams. * a lower layer such as Ogg framing or UDP datagrams.
*/ */
 End of changes. 24 change blocks. 
28 lines changed or deleted 52 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/