comments.h   comments.h 
skipping to change at line 51 skipping to change at line 50
* use a comment format called "Vorbiscomment", defined * use a comment format called "Vorbiscomment", defined
* <a href="http://www.xiph.org/ogg/vorbis/doc/v-comment.html">here</a>. * <a href="http://www.xiph.org/ogg/vorbis/doc/v-comment.html">here</a>.
* Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are * Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are
* defined in that document. * defined in that document.
* *
* The following general features of Vorbiscomment are relevant to this API : * The following general features of Vorbiscomment are relevant to this API :
* - Each stream has one comment packet, which occurs before any encoded * - Each stream has one comment packet, which occurs before any encoded
* audio data in the stream. * audio data in the stream.
* - When encoding, FishSound will generate the comment block and pass it * - When encoding, FishSound will generate the comment block and pass it
* to the encoded() callback in sequence, just like any other packet. * to the encoded() callback in sequence, just like any other packet.
* Hence, all comments must be set before any call to fish_sound_encode() . * Hence, all comments must be set before any call to fish_sound_encode_* ().
* - When decoding, FishSound will decode the comment block before calling * - When decoding, FishSound will decode the comment block before calling
* the first decoded() callback. Hence, retrieving comment data is possib le * the first decoded() callback. Hence, retrieving comment data is possib le
* from as soon as the decoded() callback is first called. * from as soon as the decoded() callback is first called.
* *
* Each comment block contains one Vendor string, which can be retrieved * Each comment block contains one Vendor string, which can be retrieved
* with fish_sound_comment_get_vendor(). When encoding, this string is * with fish_sound_comment_get_vendor(). When encoding, this string is
* effectively fixed by the codec libraries; it cannot be set by the * effectively fixed by the codec libraries; it cannot be set by the
* application. * application.
* *
* The rest of a comment block consists of \a name = \a value pairs, with * The rest of a comment block consists of \a name = \a value pairs, with
 End of changes. 1 change blocks. 
1 lines changed or deleted 1 lines changed or added


 constants.h   constants.h 
skipping to change at line 61 skipping to change at line 61
/** 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
} FishSoundCodecID; } FishSoundCodecID;
/** Decode callback return values */
typedef enum _FishSoundStopCtl {
/** Continue calling decode callbacks */
FISH_SOUND_CONTINUE = 0,
/** Stop calling callbacks, but retain buffered data */
FISH_SOUND_STOP_OK = 1,
/** Stop calling callbacks, and purge buffered data */
FISH_SOUND_STOP_ERR = -1
} FishSoundStopCtl;
/** 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,
 End of changes. 1 change blocks. 
0 lines changed or deleted 12 lines changed or added


 fishsound.h   fishsound.h 
skipping to change at line 186 skipping to change at line 186
* *
* For general information about using ./configure, see the file * For general information about using ./configure, see the file
* \link install INSTALL \endlink * \link install INSTALL \endlink
* *
* \subsection no_encode Removing encoding support * \subsection no_encode Removing encoding support
* *
* Configuring with \a --disable-encode will remove all support for encodin g: * Configuring with \a --disable-encode will remove all support for encodin g:
* - All internal encoding related functions will not be built * - All internal encoding 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
* will fail, returning NULL * will fail, returning NULL
* - Any attempt to call fish_sound_encode() will return * - Any attempt to call fish_sound_encode_*() will return
* FISH_SOUND_ERR_DISABLED * FISH_SOUND_ERR_DISABLED
* - The resulting library will not be linked against libvorbisenc * - The resulting library will not be linked against libvorbisenc
* *
* \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
skipping to change at line 328 skipping to change at line 328
* provided in the \link encode Encoding audio data \endlink section. * provided in the \link encode Encoding audio data \endlink section.
*/ */
/** \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 h as * - provide a FishSoundDecoded_* callback for libfishsound to call when it has
* decoded audio. * decoded audio.
* - (optionally) specify whether you want to receive interleaved or * - (optionally) specify whether you want to receive interleaved or
* 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 Vorbis or Speex stream.
* Hence, the step of feeding encoded data to libfishsound is done within * Hence, 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
skipping to change at line 363 skipping to change at line 363
/** \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.
* fish_sound_new() will return a new FishSound* object initialised for * fish_sound_new() will return a new FishSound* object initialised for
* encoding. * encoding.
* - provide a FishSoundEncoded callback for libfishsound to call when it * - provide a FishSoundEncoded callback for libfishsound to call when it
* has a block of encoded audio * has a block of encoded audio
* - (optionally) specify whether you will be providing interleaved or * - feed raw PCM audio data to libfishsound via fish_sound_encode_*().
* per-channel PCM data, using a fish_sound_set_interleave().
* The default is for per-channel (non-interleaved) PCM.
* - feed raw PCM audio data to libfishsound via fish_sound_encode().
* 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
skipping to change at line 419 skipping to change at line 416
/** Commonly used file extension */ /** Commonly used file extension */
const char * extension; const char * extension;
} FishSoundFormat; } FishSoundFormat;
/** /**
* An opaque handle to a FishSound. This is returned by fishsound_new() * An opaque handle to a FishSound. This is returned by fishsound_new()
* and is passed to all other fish_sound_*() functions. * and is passed to all other fish_sound_*() functions.
*/ */
typedef void * FishSound; typedef void * FishSound;
/**
* Signature of a callback for libfishsound to call when it has decoded
* audio PCM data.
* \param fsound The FishSound* handle
* \param pcm The decoded audio
* \param frames The count of frames decoded
* \param user_data Arbitrary user data
* \retval 0 to continue
* \retval non-zero to stop decoding immediately and
* return control to the fish_sound_decode() caller
*/
typedef int (*FishSoundDecoded) (FishSound * fsound, float ** pcm,
long frames, void * user_data);
/**
* Signature of a callback for libfishsound to call when it has encoded
* data.
* \param fsound The FishSound* handle
* \param buf The encoded data
* \param bytes The count of bytes encoded
* \param user_data Arbitrary user data
* \retval 0 to continue
* \retval non-zero to stop encoding immediately and
* return control to the fish_sound_encode() caller
*/
typedef int (*FishSoundEncoded) (FishSound * fsound, unsigned char * buf,
long bytes, void * user_data);
#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 if
* \a buf was identified as the initial bytes of a supported codec * \a buf was identified as the initial bytes of a supported codec
skipping to change at line 473 skipping to change at line 442
* 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.
*/ */
int int
fish_sound_identify (unsigned char * buf, long bytes); fish_sound_identify (unsigned char * buf, long bytes);
/** /**
* Instantiate a new FishSound* handle * Instantiate a new FishSound* handle
* \param mode FISH_SOUND_DECODE or FISH_SOUND_ENCODE * \param mode FISH_SOUND_DECODE or FISH_SOUND_ENCODE
* \param fsinfo * \param fsinfo Encoder configuration, may be NULL for FISH_SOUND_DECODE
* \returns A new FishSound* handle, or NULL on error * \returns A new FishSound* handle, or NULL on error
*/ */
FishSound * fish_sound_new (int mode, FishSoundInfo * fsinfo); FishSound * fish_sound_new (int mode, FishSoundInfo * fsinfo);
/** /**
* Set the callback for libfishsound to call when it has a block of
* decoded audio ready
* \param fsound A FishSound* handle (created with mode FISH_SOUND_DECODE)
* \param decoded The callback to call
* \param user_data Arbitrary user data to pass to the callback
* \returns 0 on success, -1 on failure
*/
int fish_sound_set_decoded_callback (FishSound * fsound,
FishSoundDecoded decoded,
void * user_data);
/**
* Set the callback for libfishsound to call when it has a block of
* encoded data ready
* \param fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
* \param encoded The callback to call
* \param user_data Arbitrary user data to pass to the callback
* \returns 0 on success, -1 on failure
*/
int fish_sound_set_encoded_callback (FishSound * fsound,
FishSoundEncoded encoded,
void * user_data);
/**
* Decode a block of data
* \param fsound A FishSound* handle (created with mode FISH_SOUND_DECODE)
* \param buf A buffer of data
* \param bytes A count of bytes to decode (ie. the length of buf)
* \returns The number of bytes consumed
*/
long fish_sound_decode (FishSound * fsound, unsigned char * buf, long bytes
);
/**
* Encode a block of audio
* \param fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
* \param pcm The audio data to encode
* \param frames A count of frames to encode
* \returns The number of frames encoded
* \note For multichannel audio, the audio data is interpreted according
* to the current PCM style
*/
long fish_sound_encode (FishSound * fsound, float ** pcm, long frames);
/**
* Flush any internally buffered data, forcing encode * Flush any internally buffered data, forcing encode
* \param fsound A FishSound* handle * \param fsound A FishSound* handle
* \returns 0 on success, -1 on failure * \returns 0 on success, -1 on failure
*/ */
long fish_sound_flush (FishSound * fsound); long fish_sound_flush (FishSound * fsound);
/** /**
* Reset the codec state of a FishSound object. * Reset the codec state of a FishSound object.
* *
* When decoding from a seekable file, fish_sound_reset() should be called * When decoding from a seekable file, fish_sound_reset() should be called
skipping to change at line 568 skipping to change at line 493
/** /**
* Query whether a FishSound object is using interleaved PCM * Query whether a FishSound object is using interleaved PCM
* \param fsound A FishSound* handle * \param fsound A FishSound* handle
* \retval 0 \a fsound uses non-interleaved PCM * \retval 0 \a fsound uses non-interleaved PCM
* \retval 1 \a fsound uses interleaved PCM * \retval 1 \a fsound uses interleaved PCM
* \retval -1 Invalid \a fsound * \retval -1 Invalid \a fsound
*/ */
int fish_sound_get_interleave (FishSound * fsound); int fish_sound_get_interleave (FishSound * fsound);
/** /**
* Set the PCM format used by a FishSound object. The default value is
* non-interleaved.
* \param fsound A FishSound* handle
* \param interleave Whether to use interleaved PCM or not. Valid values ar
e
* 0 for non-interleaved, and 1 for interleaved.
* \retval 0 Success
* \retval -1 Invalid \a fsound
*/
int fish_sound_set_interleave (FishSound * fsound, int interleave);
/**
* Query the current frame number of a FishSound object. * Query the current frame number of a FishSound object.
* *
* For decoding, this is the greatest frame index that has been decoded and * For decoding, this is the greatest frame index that has been decoded and
* made available to a FishSoundDecoded callback. This function is safe to * made available to a FishSoundDecoded callback. This function is safe to
* call from within a FishSoundDecoded callback, and corresponds to the fra me * call from within a FishSoundDecoded callback, and corresponds to the fra me
* number of the last frame in the current decoded block. * number of the last frame in the current decoded block.
* *
* For encoding, this is the greatest frame index that has been encoded. Th is * For encoding, this is the greatest frame index that has been encoded. Th is
* function is safe to call from within a FishSoundEncoded callback, and * function is safe to call from within a FishSoundEncoded callback, and
* corresponds to the frame number of the last frame encoded in the current * corresponds to the frame number of the last frame encoded in the current
skipping to change at line 626 skipping to change at line 540
* <a href="http://www.xiph.org/ogg/vorbis/doc/Vorbis_I_spec.html#vorbis-ov er-ogg">here</a>. * <a href="http://www.xiph.org/ogg/vorbis/doc/Vorbis_I_spec.html#vorbis-ov er-ogg">here</a>.
* *
* When decoding from Ogg, you should call this function with the \a granul epos * When decoding from Ogg, you should call this function with the \a granul epos
* and \a eos of the \a ogg_packet structure. This call should be made befo re * and \a eos of the \a ogg_packet structure. This call should be made befo re
* passing the packet's data to fish_sound_decode(). Failure to do so may * passing the packet's data to fish_sound_decode(). Failure to do so may
* result in minor decode errors on the first and/or last packet of the str eam. * result in minor decode errors on the first and/or last packet of the str eam.
* *
* When encoding into Ogg, you should call this function with the \a granul epos * When encoding into Ogg, you should call this function with the \a granul epos
* and \a eos that will be used for the \a ogg_packet structure. This call * and \a eos that will be used for the \a ogg_packet structure. This call
* should be made before passing the block of audio data to * should be made before passing the block of audio data to
* fish_sound_encode(). Failure to do so may result in minor encoding error s * fish_sound_encode_*(). Failure to do so may result in minor encoding err ors
* on the first and/or last packet of the stream. * on the first and/or last packet of the stream.
* *
* \param fsound A FishSound* handle * \param fsound A FishSound* handle
* \param next_granulepos The "granulepos" for the next block to decode. * \param next_granulepos The "granulepos" for the next block to decode.
* If unknown, set \a next_granulepos to -1. Otherwise, * If unknown, set \a next_granulepos to -1. Otherwise,
* \a next_granulepos specifies the frameno of the final frame in th e * \a next_granulepos specifies the frameno of the final frame in th e
* block. This is authoritative, hence can be used to indicate * block. This is authoritative, hence can be used to indicate
* various forms of truncation at the beginning or end of a stream. * various forms of truncation at the beginning or end of a stream.
* Mid-stream, a later-than-expected "granulepos" indicates that som e * Mid-stream, a later-than-expected "granulepos" indicates that som e
* data was missing. * data was missing.
skipping to change at line 649 skipping to change at line 563
* \retval 0 Success * \retval 0 Success
* \retval -1 Invalid \a fsound * \retval -1 Invalid \a fsound
*/ */
int fish_sound_prepare_truncation (FishSound * fsound, long next_granulepos , int fish_sound_prepare_truncation (FishSound * fsound, long next_granulepos ,
int next_eos); int next_eos);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#include <fishsound/decode.h>
#include <fishsound/encode.h>
#include <fishsound/comments.h> #include <fishsound/comments.h>
#include <fishsound/deprecated.h>
#endif /* __FISH_SOUND_H__ */ #endif /* __FISH_SOUND_H__ */
 End of changes. 11 change blocks. 
94 lines changed or deleted 10 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/