Main Page | Modules | Data Structures | File List | Data Fields | Globals

fishsound.h File Reference

The libfishsound C API. More...

#include <fishsound/constants.h>
#include <fishsound/comments.h>

Go to the source code of this file.

Data Structures

struct  FishSoundFormat
 Info about a particular sound format. More...

struct  FishSoundInfo
 Info about a particular encoder/decoder instance. More...


Typedefs

typedef void * FishSound
 An opaque handle to a FishSound.

typedef int(* FishSoundDecoded )(FishSound *fsound, float **pcm, long frames, void *user_data)
 Signature of a callback for libfishsound to call when it has decoded audio PCM data.

typedef int(* FishSoundEncoded )(FishSound *fsound, unsigned char *buf, long bytes, void *user_data)
 Signature of a callback for libfishsound to call when it has encoded data.


Functions

int fish_sound_identify (unsigned char *buf, long bytes)
 Identify a codec based on the first few bytes of data.

FishSoundfish_sound_new (int mode, FishSoundInfo *fsinfo)
 Instantiate a new FishSound* handle.

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 decoded audio ready.

int fish_sound_set_encoded_callback (FishSound *fsound, FishSoundEncoded encoded, void *user_data)
 Set the callback for libfishsound to call when it has a block of encoded data ready.

long fish_sound_decode (FishSound *fsound, unsigned char *buf, long bytes)
 Decode a block of data.

long fish_sound_encode (FishSound *fsound, float **pcm, long frames)
 Encode a block of audio.

long fish_sound_flush (FishSound *fsound)
 Flush any internally buffered data, forcing encode.

int fish_sound_reset (FishSound *fsound)
 Reset the codec state of a FishSound object.

int fish_sound_delete (FishSound *fsound)
 Delete a FishSound object.

int fish_sound_command (FishSound *fsound, int command, void *data, int datasize)
 Command interface.

int fish_sound_get_interleave (FishSound *fsound)
 Query whether a FishSound object is using interleaved PCM.

int fish_sound_set_interleave (FishSound *fsound, int interleave)
 Set the PCM format used by a FishSound object.

long fish_sound_get_frameno (FishSound *fsound)
 Query the current frame number of a FishSound object.

int fish_sound_set_frameno (FishSound *fsound, long frameno)
 Set the current frame number of a FishSound object.

int fish_sound_prepare_truncation (FishSound *fsound, long next_granulepos, int next_eos)
 Prepare truncation details for the next block of data.


Detailed Description

The libfishsound C API.

General usage

All access is managed via a FishSound* handle. This is instantiated using fish_sound_new() and should be deleted with fish_sound_delete() 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 reset the internal codec state.

Decoding

libfishsound provides callback based decoding: you feed it encoded audio 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 provided in the Decoding audio data section.

Encoding

libfishsound provides callback based encoding: you feed it PCM audio, 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 provided in the Encoding audio data section.

Typedef Documentation

typedef void* FishSound
 

An opaque handle to a FishSound.

This is returned by fishsound_new() and is passed to all other fish_sound_*() functions.

typedef int(* FishSoundDecoded)(FishSound * fsound, float ** pcm, long frames, void * user_data)
 

Signature of a callback for libfishsound to call when it has decoded audio PCM data.

Parameters:
fsound The FishSound* handle
pcm The decoded audio
frames The count of frames decoded
user_data Arbitrary user data
Return values:
0 to continue
non-zero to stop decoding immediately and return control to the fish_sound_decode() caller

typedef int(* FishSoundEncoded)(FishSound * fsound, unsigned char * buf, long bytes, void * user_data)
 

Signature of a callback for libfishsound to call when it has encoded data.

Parameters:
fsound The FishSound* handle
buf The encoded data
bytes The count of bytes encoded
user_data Arbitrary user data
Return values:
0 to continue
non-zero to stop encoding immediately and return control to the fish_sound_encode() caller


Function Documentation

int fish_sound_command FishSound fsound,
int  command,
void *  data,
int  datasize
 

Command interface.

Parameters:
fsound A FishSound* handle
command The command action
data Command data
datasize Size of the data in bytes
Returns:
0 on success, -1 on failure

long fish_sound_decode FishSound fsound,
unsigned char *  buf,
long  bytes
 

Decode a block of data.

Parameters:
fsound A FishSound* handle (created with mode FISH_SOUND_DECODE)
buf A buffer of data
bytes A count of bytes to decode (ie. the length of buf)
Returns:
The number of bytes consumed

int fish_sound_delete FishSound fsound  ) 
 

Delete a FishSound object.

Parameters:
fsound A FishSound* handle
Returns:
0 on success, -1 on failure

long fish_sound_encode FishSound fsound,
float **  pcm,
long  frames
 

Encode a block of audio.

Parameters:
fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
pcm The audio data to encode
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_flush FishSound fsound  ) 
 

Flush any internally buffered data, forcing encode.

Parameters:
fsound A FishSound* handle
Returns:
0 on success, -1 on failure

long fish_sound_get_frameno FishSound fsound  ) 
 

Query the current frame number of a FishSound object.

For decoding, this is the greatest frame index that has been decoded and made available to a FishSoundDecoded callback. This function is safe to call from within a FishSoundDecoded callback, and corresponds to the frame number of the last frame in the current decoded block.

For encoding, this is the greatest frame index that has been encoded. This function is safe to call from within a FishSoundEncoded callback, and corresponds to the frame number of the last frame encoded in the current block.

Parameters:
fsound A FishSound* handle
Returns:
The current frame number
Return values:
-1 Invalid fsound

int fish_sound_get_interleave FishSound fsound  ) 
 

Query whether a FishSound object is using interleaved PCM.

Parameters:
fsound A FishSound* handle
Return values:
0 fsound uses non-interleaved PCM
1 fsound uses interleaved PCM
-1 Invalid fsound

int fish_sound_identify unsigned char *  buf,
long  bytes
 

Identify a codec based on the first few bytes of data.

Parameters:
buf A pointer to the first few bytes of the data
bytes The count of bytes available at buf
Return values:
FISH_SOUND_xxxxxx FISH_SOUND_VORBIS, FISH_SOUND_SPEEX if buf was identified as the initial bytes of a supported codec
FISH_SOUND_UNKNOWN if the codec could not be identified
FISH_SOUND_ERR_SHORT_IDENTIFY if bytes is less than 8
Note:
If bytes is exactly 8, then only a weak check is performed, which is fast but may return a false positive.

If bytes is greater than 8, then a stronger check is performed in which an attempt is made to decode buf as the initial header of each supported codec. This is unlikely to return a false positive but is only useful if buf is the entire payload of a packet derived from a lower layer such as Ogg framing or UDP datagrams.

FishSound* fish_sound_new int  mode,
FishSoundInfo fsinfo
 

Instantiate a new FishSound* handle.

Parameters:
mode FISH_SOUND_DECODE or FISH_SOUND_ENCODE
fsinfo 
Returns:
A new FishSound* handle, or NULL on error

int fish_sound_prepare_truncation FishSound fsound,
long  next_granulepos,
int  next_eos
 

Prepare truncation details for the next block of data.

The semantics of these parameters derives directly from Ogg encapsulation of Vorbis, described here.

When decoding from Ogg, you should call this function with the granulepos and eos of the ogg_packet structure. This call should be made before 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 stream.

When encoding into Ogg, you should call this function with the granulepos and eos that will be used for the ogg_packet structure. This call should be made before passing the block of audio data to fish_sound_encode(). Failure to do so may result in minor encoding errors on the first and/or last packet of the stream.

Parameters:
fsound A FishSound* handle
next_granulepos The "granulepos" for the next block to decode. If unknown, set next_granulepos to -1. Otherwise, next_granulepos specifies the frameno of the final frame in the block. This is authoritative, hence can be used to indicate various forms of truncation at the beginning or end of a stream. Mid-stream, a later-than-expected "granulepos" indicates that some data was missing.
next_eos A boolean indicating whether the next data block will be the last in the stream.
Return values:
0 Success
-1 Invalid fsound

int fish_sound_reset FishSound fsound  ) 
 

Reset the codec state of a FishSound object.

When decoding from a seekable file, fish_sound_reset() should be called after any seek operations. See also fish_sound_set_frameno().

Parameters:
fsound A FishSound* handle
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 decoded audio ready.

Parameters:
fsound A FishSound* handle (created with mode FISH_SOUND_DECODE)
decoded The callback to call
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
 

Set the callback for libfishsound to call when it has a block of encoded data ready.

Parameters:
fsound A FishSound* handle (created with mode FISH_SOUND_ENCODE)
encoded The callback to call
user_data Arbitrary user data to pass to the callback
Returns:
0 on success, -1 on failure

int fish_sound_set_frameno FishSound fsound,
long  frameno
 

Set the current frame number of a FishSound object.

When decoding from a seekable file, fish_sound_set_frameno() should be called after any seek operations, otherwise the value returned by fish_sound_get_frameno() will simply continue to increment. See also fish_sound_reset().

Parameters:
fsound A FishSound* handle
frameno The current frame number.
Return values:
0 Success
-1 Invalid fsound

int fish_sound_set_interleave FishSound fsound,
int  interleave
 

Set the PCM format used by a FishSound object.

The default value is non-interleaved.

Parameters:
fsound A FishSound* handle
interleave Whether to use interleaved PCM or not. Valid values are 0 for non-interleaved, and 1 for interleaved.
Return values:
0 Success
-1 Invalid fsound


Generated on Thu Jun 24 18:46:04 2004 for libfishsound by doxygen 1.3.5