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 GrooveFile *	groove_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 GroovePlaylist *	groove_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 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. 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 GrooveSink *	groove_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

Examples:: fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.

#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

enum GrooveError

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 )

Examples:: fingerprint.c, metadata.c, playlist.c, replaygain.c, and transcode.c.

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 )

Enumerator
GrooveErrorNone
GrooveErrorNoMem
GrooveErrorInvalidSampleFormat

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation