comments.h File Reference

Encoding and decoding of comments. More...

#include <fishsound/fishsound.h>

Data Structures
struct	FishSoundComment
	A comment. More...
Functions
const char *	fish_sound_comment_get_vendor (FishSound *fsound)
	Retrieve the vendor string.
const FishSoundComment *	fish_sound_comment_first (FishSound *fsound)
	Retrieve the first comment.
const FishSoundComment *	fish_sound_comment_next (FishSound fsound, const FishSoundComment comment)
	Retrieve the next comment.
const FishSoundComment *	fish_sound_comment_first_byname (FishSound fsound, char name)
	Retrieve the first comment with a given name.
const FishSoundComment *	fish_sound_comment_next_byname (FishSound fsound, const FishSoundComment comment)
	Retrieve the next comment following and with the same name as a given comment.
int	fish_sound_comment_add (FishSound fsound, FishSoundComment comment)
	Add a comment.
int	fish_sound_comment_add_byname (FishSound fsound, const char name, const char *value)
	Add a comment by name and value.
int	fish_sound_comment_remove (FishSound fsound, FishSoundComment comment)
	Remove a comment.
int	fish_sound_comment_remove_byname (FishSound fsound, char name)
	Remove all comments with a given name.

Detailed Description

Encoding and decoding of comments.

Vorbis and Speex bitstreams use a comment format called "Vorbiscomment", defined here. Many standard comment names (such as TITLE, COPYRIGHT and GENRE) are defined in that document.

The following general features of Vorbiscomment are relevant to this API:

Each stream has one comment packet, which occurs before any encoded audio data in the stream.
When encoding, FishSound will generate the comment block and pass it to the encoded() callback in sequence, just like any other packet. Hence, all comments must be set before any call to fish_sound_encode_*().
When decoding, FishSound will decode the comment block before calling the first decoded() callback. Hence, retrieving comment data is possible from as soon as the decoded() callback is first called.

Each comment block contains one Vendor string, which can be retrieved with fish_sound_comment_get_vendor(). When encoding, this string is effectively fixed by the codec libraries; it cannot be set by the application.

The rest of a comment block consists of name = value pairs, with the following restrictions:

Both the name and value must be non-empty
The name is case-insensitive and must consist of ASCII within the range 0x20 to 0x7D inclusive, 0x3D ('=') excluded.
The name is not unique; multiple entries may exist with equivalent name within a Vorbiscomment block.
The value may be any UTF-8 string.

Retrieving comments

FishSound contains API methods to iterate through all comments associated with a FishSound* handle (fish_sound_comment_first() and fish_sound_comment_next(), and to iterate through comments matching a particular name (fish_sound_comment_first_byname() and fish_sound_comment_next_byname()). Given that multiple comments may exist with the same name, you should not use fish_sound_comment_first_byname() as a simple "get" function.

Encoding comments

For encoding, FishSound contains API methods for adding comments (fish_sound_comment_add() and fish_sound_comment_add_byname() and for removing comments (fish_sound_comment_remove() and fish_sound_comment_remove_byname()).

Function Documentation

int fish_sound_comment_add	(	FishSound *	fsound,
		FishSoundComment *	comment
	)

Add a comment.

Parameters:

	fsound	A FishSound* handle (created with mode FISH_SOUND_ENCODE)
	comment	The comment to add

Return values:

	0	Success
	FISH_SOUND_ERR_BAD	fsound is not a valid FishSound* handle
	FISH_SOUND_ERR_INVALID	Operation not suitable for this FishSound

int fish_sound_comment_add_byname	(	FishSound *	fsound,
		const char *	name,
		const char *	value
	)

Add a comment by name and value.

Parameters:

	fsound	A FishSound* handle (created with mode FISH_SOUND_ENCODE)
	name	The name of the comment to add
	value	The contents of the comment to add

Return values:

	0	Success
	FISH_SOUND_ERR_BAD	fsound is not a valid FishSound* handle
	FISH_SOUND_ERR_INVALID	Operation not suitable for this FishSound

const FishSoundComment* fish_sound_comment_first ( FishSound * fsound )

Retrieve the first comment.

Parameters:

fsound

A FishSound* handle

Returns:: A read-only copy of the first comment, or NULL if no comments exist for this FishSound* object.

const FishSoundComment* fish_sound_comment_first_byname	(	FishSound *	fsound,
		char *	name
	)

Retrieve the first comment with a given name.

Parameters:

	fsound	A FishSound* handle
	name	the name of the comment to retrieve.

Returns:: A read-only copy of the first comment matching the given name.

Return values:

NULL

no match was found.

Note:: If name is NULL, the behaviour is the same as for fish_sound_comment_first()

const char* fish_sound_comment_get_vendor ( FishSound * fsound )

Retrieve the vendor string.

Parameters:

fsound

A FishSound* handle

Returns:: A read-only copy of the vendor string

Return values:

NULL

No vendor string is associated with fsound, or fsound is NULL.

const FishSoundComment* fish_sound_comment_next	(	FishSound *	fsound,
		const FishSoundComment *	comment
	)

Retrieve the next comment.

Parameters:

	fsound	A FishSound* handle
	comment	The previous comment.

Returns:: A read-only copy of the comment immediately following the given comment.

const FishSoundComment* fish_sound_comment_next_byname	(	FishSound *	fsound,
		const FishSoundComment *	comment
	)

Retrieve the next comment following and with the same name as a given comment.

Parameters:

	fsound	A FishSound* handle
	comment	A comment

Returns:: A read-only copy of the next comment with the same name as comment.

Return values:

NULL

no further comments with the same name exist for this FishSound* object.

int fish_sound_comment_remove	(	FishSound *	fsound,
		FishSoundComment *	comment
	)

Remove a comment.

Parameters:

	fsound	A FishSound* handle (created with FISH_SOUND_ENCODE)
	comment	The comment to remove.

Return values:

	1	Success: comment removed
	0	No-op: comment not found, nothing to remove
	FISH_SOUND_ERR_BAD	fsound is not a valid FishSound* handle
	FISH_SOUND_ERR_INVALID	Operation not suitable for this FishSound

int fish_sound_comment_remove_byname	(	FishSound *	fsound,
		char *	name
	)

Remove all comments with a given name.

Parameters:

	fsound	A FishSound* handle (created with FISH_SOUND_ENCODE)
	name	The name of the comments to remove

Return values:

	>= 0	The number of comments removed
	FISH_SOUND_ERR_BAD	fsound is not a valid FishSound* handle
	FISH_SOUND_ERR_INVALID	Operation not suitable for this FishSound

comments.h File Reference

Data Structures

Functions

Detailed Description

Retrieving comments

Encoding comments

Function Documentation