libgroove  5.0.0
groove.h File Reference

Go to the source code of this file.

Data Structures

struct  GrooveAudioFormat
 
struct  GrooveFile
 
struct  GroovePlaylistItem
 
struct  GroovePlaylist
 
struct  GrooveBuffer
 
struct  GrooveSink
 use this to get access to a realtime raw audio buffer for example you could use it to draw a waveform or other visualization GroovePlayer uses this internally to get the audio buffer for playback More...
 

Macros

#define GROOVE_LOG_QUIET   -8
 
#define GROOVE_LOG_ERROR   16
 
#define GROOVE_LOG_WARNING   24
 
#define GROOVE_LOG_INFO   32
 
#define GROOVE_TAG_MATCH_CASE   1
 flags to groove_file_metadata_* More...
 
#define GROOVE_TAG_DONT_OVERWRITE   16
 
#define GROOVE_TAG_APPEND   32
 If the entry already exists, append to it. More...
 
#define GROOVE_BUFFER_NO   0
 
#define GROOVE_BUFFER_YES   1
 
#define GROOVE_BUFFER_END   2
 

Enumerations

enum  GrooveError { GrooveErrorNone, GrooveErrorNoMem, GrooveErrorInvalidSampleFormat }
 See also groove_strerror. More...
 
enum  GrooveFillMode { GrooveFillModeAnySinkFull, GrooveFillModeEverySinkFull }
 Specifies when the sink will stop decoding. More...
 

Functions

int groove_init (void)
 call once at the beginning of your program from the main thread returns 0 on success, < 0 on error More...
 
void groove_finish (void)
 call at the end of your program to clean up. More...
 
const char * groove_strerror (int error)
 
void groove_set_logging (int level)
 enable/disable logging of errors More...
 
int groove_audio_formats_equal (const struct GrooveAudioFormat *a, const struct GrooveAudioFormat *b)
 returns 1 if the audio formats have the same sample rate, channel layout, and sample format. More...
 
int groove_version_major (void)
 
int groove_version_minor (void)
 
int groove_version_patch (void)
 
const char * groove_version (void)
 
char * groove_create_rand_name (int *out_len, const char *file, int file_len)
 given a file path and the length of the file path, allocates a new file path which is in the same directory but a random filename with the same extension. More...
 
const char * groove_tag_key (struct GrooveTag *tag)
 
const char * groove_tag_value (struct GrooveTag *tag)
 
struct GrooveFilegroove_file_open (const char *filename)
 you are responsible for calling groove_file_close on the returned GrooveFile. More...
 
void groove_file_close (struct GrooveFile *file)
 
struct GrooveTag * groove_file_metadata_get (struct GrooveFile *file, const char *key, const struct GrooveTag *prev, int flags)
 
int groove_file_metadata_set (struct GrooveFile *file, const char *key, const char *value, int flags)
 key entry to add to metadata. More...
 
const char * groove_file_short_names (struct GrooveFile *file)
 a comma separated list of short names for the format More...
 
int groove_file_save (struct GrooveFile *file)
 write changes made to metadata to disk. More...
 
int groove_file_save_as (struct GrooveFile *file, const char *filename)
 
double groove_file_duration (struct GrooveFile *file)
 main audio stream duration in seconds. More...
 
void groove_file_audio_format (struct GrooveFile *file, struct GrooveAudioFormat *audio_format)
 get the audio format of the main audio stream of a file More...
 
struct GroovePlaylistgroove_playlist_create (void)
 A playlist keeps its sinks full. More...
 
void groove_playlist_destroy (struct GroovePlaylist *playlist)
 This will not call groove_file_close on any files. More...
 
void groove_playlist_play (struct GroovePlaylist *playlist)
 
void groove_playlist_pause (struct GroovePlaylist *playlist)
 
void groove_playlist_seek (struct GroovePlaylist *playlist, struct GroovePlaylistItem *item, double seconds)
 
struct GroovePlaylistItemgroove_playlist_insert (struct GroovePlaylist *playlist, struct GrooveFile *file, double gain, double peak, struct GroovePlaylistItem *next)
 Once you add a file to the playlist, you must not destroy it until you first remove it from the playlist. More...
 
void groove_playlist_remove (struct GroovePlaylist *playlist, struct GroovePlaylistItem *item)
 This will not call groove_file_close on item->file Item is destroyed and the address it points to is no longer valid. More...
 
void groove_playlist_position (struct GroovePlaylist *playlist, struct GroovePlaylistItem **item, double *seconds)
 Get the position of the decode head both the current playlist item and the position in seconds in the playlist item are given. More...
 
int groove_playlist_playing (struct GroovePlaylist *playlist)
 return 1 if the playlist is playing; 0 if it is not. More...
 
void groove_playlist_clear (struct GroovePlaylist *playlist)
 Remove all playlist items. More...
 
int groove_playlist_count (struct GroovePlaylist *playlist)
 return the count of playlist items More...
 
void groove_playlist_set_gain (struct GroovePlaylist *playlist, double gain)
 
void groove_playlist_set_item_gain_peak (struct GroovePlaylist *playlist, struct GroovePlaylistItem *item, double gain, double peak)
 
void groove_playlist_set_fill_mode (struct GroovePlaylist *playlist, enum GrooveFillMode mode)
 Use this to set the fill mode using the constants above. More...
 
void groove_buffer_ref (struct GrooveBuffer *buffer)
 
void groove_buffer_unref (struct GrooveBuffer *buffer)
 
struct GrooveSinkgroove_sink_create (void)
 
void groove_sink_destroy (struct GrooveSink *sink)
 
int groove_sink_attach (struct GrooveSink *sink, struct GroovePlaylist *playlist)
 before calling this, set audio_format returns 0 on success, < 0 on error More...
 
int groove_sink_detach (struct GrooveSink *sink)
 returns 0 on success, < 0 on error More...
 
int groove_sink_buffer_get (struct GrooveSink *sink, struct GrooveBuffer **buffer, int block)
 returns < 0 on error, GROOVE_BUFFER_NO on aborted (block=1) or no buffer ready (block=0), GROOVE_BUFFER_YES on buffer returned, and GROOVE_BUFFER_END on end of playlist. More...
 
int groove_sink_buffer_peek (struct GrooveSink *sink, int block)
 returns < 0 on error, 0 on no buffer ready, 1 on buffer ready if block is 1, block until buffer is ready More...
 
int groove_sink_set_gain (struct GrooveSink *sink, double gain)
 See the gain property of GrooveSink. More...
 
int groove_sink_get_fill_level (struct GrooveSink *sink)
 Returns the number of bytes contained in this sink. More...
 
int groove_sink_contains_end_of_playlist (struct GrooveSink *sink)
 Returns 1 if the sink contains the end of playlist sentinel, 0 otherwise. More...
 

Macro Definition Documentation

#define GROOVE_BUFFER_END   2
#define GROOVE_BUFFER_NO   0
#define GROOVE_BUFFER_YES   1
Examples:
transcode.c.
#define GROOVE_LOG_ERROR   16
#define GROOVE_LOG_INFO   32
#define GROOVE_LOG_QUIET   -8
#define GROOVE_LOG_WARNING   24
#define GROOVE_TAG_APPEND   32

If the entry already exists, append to it.

Note that no delimiter is added, the strings are simply concatenated.

#define GROOVE_TAG_DONT_OVERWRITE   16
#define GROOVE_TAG_MATCH_CASE   1

flags to groove_file_metadata_*

Enumeration Type Documentation

See also groove_strerror.

Enumerator
GrooveErrorNone 
GrooveErrorNoMem 
GrooveErrorInvalidSampleFormat 

Specifies when the sink will stop decoding.

Enumerator
GrooveFillModeAnySinkFull 

With this behavior, the playlist will stop decoding audio when any attached sink is full, and then resume decoding audio when every sink is not full.

This is the default behavior.

GrooveFillModeEverySinkFull 

With this behavior, the playlist will decode audio if any sinks are not full.

If any sinks do not drain fast enough the data will buffer up in the playlist.

Function Documentation

int groove_audio_formats_equal ( const struct GrooveAudioFormat a,
const struct GrooveAudioFormat b 
)

returns 1 if the audio formats have the same sample rate, channel layout, and sample format.

returns 0 otherwise.

void groove_buffer_ref ( struct GrooveBuffer buffer)
void groove_buffer_unref ( struct GrooveBuffer buffer)
Examples:
transcode.c.
char* groove_create_rand_name ( int *  out_len,
const char *  file,
int  file_len 
)

given a file path and the length of the file path, allocates a new file path which is in the same directory but a random filename with the same extension.

the file name will start with a '.'. The caller owns the memory. The length of the returned path is returned in out_len. You can pass NULL for out_len.

void groove_file_audio_format ( struct GrooveFile file,
struct GrooveAudioFormat audio_format 
)

get the audio format of the main audio stream of a file

Examples:
metadata.c, and transcode.c.
void groove_file_close ( struct GrooveFile file)
double groove_file_duration ( struct GrooveFile file)

main audio stream duration in seconds.

note that this relies on a combination of format headers and heuristics. It can be inaccurate. The most accurate way to learn the duration of a file is to use GrooveLoudnessDetector

Examples:
metadata.c.
struct GrooveTag* groove_file_metadata_get ( struct GrooveFile file,
const char *  key,
const struct GrooveTag *  prev,
int  flags 
)
Examples:
metadata.c, playlist.c, and transcode.c.
int groove_file_metadata_set ( struct GrooveFile file,
const char *  key,
const char *  value,
int  flags 
)

key entry to add to metadata.

will be strdup'd value entry to add to metadata. will be strdup'd passing NULL causes existing entry to be deleted. return >= 0 on success otherwise an error code < 0 note that this will not save the file; you must call groove_file_save to do that.

Examples:
metadata.c.
struct GrooveFile* groove_file_open ( const char *  filename)

you are responsible for calling groove_file_close on the returned GrooveFile.

Examples:
fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.
int groove_file_save ( struct GrooveFile file)

write changes made to metadata to disk.

return < 0 on error

Examples:
metadata.c.
int groove_file_save_as ( struct GrooveFile file,
const char *  filename 
)
const char* groove_file_short_names ( struct GrooveFile file)

a comma separated list of short names for the format

void groove_finish ( void  )

call at the end of your program to clean up.

after calling this you may no longer use this API.

Examples:
fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.
int groove_init ( void  )

call once at the beginning of your program from the main thread returns 0 on success, < 0 on error

Examples:
fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.
void groove_playlist_clear ( struct GroovePlaylist playlist)

Remove all playlist items.

int groove_playlist_count ( struct GroovePlaylist playlist)

return the count of playlist items

Examples:
transcode.c.
struct GroovePlaylist* groove_playlist_create ( void  )

A playlist keeps its sinks full.

Examples:
fingerprint.c, playlist.c, replaygain.c, and transcode.c.
void groove_playlist_destroy ( struct GroovePlaylist playlist)

This will not call groove_file_close on any files.

It will remove all playlist items and sinks from the playlist

Examples:
fingerprint.c, playlist.c, replaygain.c, and transcode.c.
struct GroovePlaylistItem* groove_playlist_insert ( struct GroovePlaylist playlist,
struct GrooveFile file,
double  gain,
double  peak,
struct GroovePlaylistItem next 
)

Once you add a file to the playlist, you must not destroy it until you first remove it from the playlist.

next: the item to insert before. if NULL, you will append to the playlist. gain: see GroovePlaylistItem structure. use 1.0 for no adjustment. peak: see GroovePlaylistItem structure. use 1.0 for no adjustment. returns the newly created playlist item, or NULL if out of memory.

Examples:
fingerprint.c, playlist.c, replaygain.c, and transcode.c.
void groove_playlist_pause ( struct GroovePlaylist playlist)
void groove_playlist_play ( struct GroovePlaylist playlist)
int groove_playlist_playing ( struct GroovePlaylist playlist)

return 1 if the playlist is playing; 0 if it is not.

void groove_playlist_position ( struct GroovePlaylist playlist,
struct GroovePlaylistItem **  item,
double *  seconds 
)

Get the position of the decode head both the current playlist item and the position in seconds in the playlist item are given.

item will be set to NULL if the playlist is empty seconds will be set to -1.0 if item is NULL. you may pass NULL for item or seconds Note that typically you are more interested in the position of the play head, not the decode head. For example, if you have a GroovePlayer attached, groove_player_position will give you the position of the play head.

void groove_playlist_remove ( struct GroovePlaylist playlist,
struct GroovePlaylistItem item 
)

This will not call groove_file_close on item->file Item is destroyed and the address it points to is no longer valid.

Examples:
fingerprint.c, playlist.c, replaygain.c, and transcode.c.
void groove_playlist_seek ( struct GroovePlaylist playlist,
struct GroovePlaylistItem item,
double  seconds 
)
void groove_playlist_set_fill_mode ( struct GroovePlaylist playlist,
enum GrooveFillMode  mode 
)

Use this to set the fill mode using the constants above.

void groove_playlist_set_gain ( struct GroovePlaylist playlist,
double  gain 
)
Examples:
playlist.c.
void groove_playlist_set_item_gain_peak ( struct GroovePlaylist playlist,
struct GroovePlaylistItem item,
double  gain,
double  peak 
)
void groove_set_logging ( int  level)

enable/disable logging of errors

Examples:
fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.
int groove_sink_attach ( struct GrooveSink sink,
struct GroovePlaylist playlist 
)

before calling this, set audio_format returns 0 on success, < 0 on error

int groove_sink_buffer_get ( struct GrooveSink sink,
struct GrooveBuffer **  buffer,
int  block 
)

returns < 0 on error, GROOVE_BUFFER_NO on aborted (block=1) or no buffer ready (block=0), GROOVE_BUFFER_YES on buffer returned, and GROOVE_BUFFER_END on end of playlist.

buffer is always set to either a valid GrooveBuffer or NULL

int groove_sink_buffer_peek ( struct GrooveSink sink,
int  block 
)

returns < 0 on error, 0 on no buffer ready, 1 on buffer ready if block is 1, block until buffer is ready

int groove_sink_contains_end_of_playlist ( struct GrooveSink sink)

Returns 1 if the sink contains the end of playlist sentinel, 0 otherwise.

struct GrooveSink* groove_sink_create ( void  )
void groove_sink_destroy ( struct GrooveSink sink)
int groove_sink_detach ( struct GrooveSink sink)

returns 0 on success, < 0 on error

int groove_sink_get_fill_level ( struct GrooveSink sink)

Returns the number of bytes contained in this sink.

int groove_sink_set_gain ( struct GrooveSink sink,
double  gain 
)

See the gain property of GrooveSink.

It is recommended that you leave this at 1.0 and instead adjust the gain of the playlist. returns 0 on success, < 0 on error

const char* groove_strerror ( int  error)
const char* groove_tag_key ( struct GrooveTag *  tag)
Examples:
metadata.c, and transcode.c.
const char* groove_tag_value ( struct GrooveTag *  tag)
Examples:
metadata.c, playlist.c, and transcode.c.
const char* groove_version ( void  )
Examples:
metadata.c.
int groove_version_major ( void  )
int groove_version_minor ( void  )
int groove_version_patch ( void  )