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

fishsound.h File Reference

The libfishsound C API. More...

#include <fishsound/constants.h>

Go to the source code of this file.

Data Structures

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

struct  FishSoundFormat
 Info about a particular sound format. 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.


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

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_reset FishSound fsound  ) 
 

Reset the codec state of a FishSound object.

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_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 Wed Mar 24 19:38:27 2004 for libfishsound by doxygen 1.3.6-20040222