libfishsound 1.0.0
|
The libfishsound C API. More...
#include <fishsound/constants.h>
#include <fishsound/decode.h>
#include <fishsound/encode.h>
#include <fishsound/comments.h>
#include <fishsound/deprecated.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. | |
Functions | |
int | fish_sound_identify (unsigned char *buf, long bytes) |
Identify a codec based on the first few bytes of data. | |
FishSound * | fish_sound_new (int mode, FishSoundInfo *fsinfo) |
Instantiate a new FishSound* handle. | |
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. | |
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. | |
The libfishsound C API.
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.
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 FLAC, Speex and Ogg Vorbis files is provided in the Decoding audio data section.
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 FLAC, Speex and Ogg Vorbis files is provided in the Encoding audio data section.
typedef void* FishSound |
An opaque handle to a FishSound.
This is returned by fishsound_new() and is passed to all other fish_sound_*() functions.
int fish_sound_command | ( | FishSound * | fsound, |
int | command, | ||
void * | data, | ||
int | datasize | ||
) |
Command interface.
fsound | A FishSound* handle |
command | The command action |
data | Command data |
datasize | Size of the data in bytes |
int fish_sound_delete | ( | FishSound * | fsound | ) |
Delete a FishSound object.
fsound | A FishSound* handle |
long fish_sound_flush | ( | FishSound * | fsound | ) |
Flush any internally buffered data, forcing encode.
fsound | A FishSound* handle |
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.
fsound | A FishSound* handle |
-1 | Invalid fsound |
int fish_sound_get_interleave | ( | FishSound * | fsound | ) |
Query whether a FishSound object is using interleaved PCM.
fsound | A FishSound* handle |
0 | fsound uses non-interleaved PCM |
1 | fsound uses interleaved PCM |
-1 | Invalid fsound, or out of memory. |
int fish_sound_identify | ( | unsigned char * | buf, |
long | bytes | ||
) |
Identify a codec based on the first few bytes of data.
buf | A pointer to the first few bytes of the data |
bytes | The count of bytes available at buf |
FISH_SOUND_xxxxxx | FISH_SOUND_VORBIS, FISH_SOUND_SPEEX or FISH_SOUND_FLAC 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 |
FishSound * fish_sound_new | ( | int | mode, |
FishSoundInfo * | fsinfo | ||
) |
Instantiate a new FishSound* handle.
mode | FISH_SOUND_DECODE or FISH_SOUND_ENCODE |
fsinfo | Encoder configuration, may be NULL for FISH_SOUND_DECODE |
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.
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. |
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().
fsound | A FishSound* handle |
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().
fsound | A FishSound* handle |
frameno | The current frame number. |
0 | Success |
-1 | Invalid fsound |