Tags manipulation

API for retrieving and setting string data within sound files. More...

Enumerations
enum	SF_STR_FIELD {   SF_STR_TITLE = 0x01, SF_STR_COPYRIGHT = 0x02, SF_STR_SOFTWARE = 0x03, SF_STR_ARTIST = 0x04,   SF_STR_COMMENT = 0x05, SF_STR_DATE = 0x06, SF_STR_ALBUM = 0x07, SF_STR_LICENSE = 0x08,   SF_STR_TRACKNUMBER = 0x09, SF_STR_GENRE = 0x10 }
	Defines field type constants. More...

Functions
SNDFILE2K_EXPORT int	sf_set_string (SNDFILE *sndfile, int str_type, const char *str)
	Sets string field for given sound file. More...
SNDFILE2K_EXPORT const char *	sf_get_string (SNDFILE *sndfile, int str_type)
	Gets string field from given sound file. More...

Detailed Description

API for retrieving and setting string data within sound files.

Note

Not all file types support this features.

Enumeration Type Documentation

SF_STR_FIELD

enum SF_STR_FIELD

Defines field type constants.

Enumerator
SF_STR_TITLE	Title.
SF_STR_COPYRIGHT	Copyright.
SF_STR_SOFTWARE	Software.
SF_STR_ARTIST	Artist.
SF_STR_COMMENT	Comment.
SF_STR_DATE	Date.
SF_STR_ALBUM	Album.
SF_STR_LICENSE	License.
SF_STR_TRACKNUMBER	Track number.
SF_STR_GENRE	Genre.

Function Documentation

sf_get_string()

SNDFILE2K_EXPORT const char* sf_get_string	(	SNDFILE *	sndfile,
		int	str_type
	)

Gets string field from given sound file.

Parameters

[in]	sndfile	Pointer to a sound file state
[in]	str_type	Type of field to retrieve, one of SF_STR_FIELD values

Returns

Zero-terminated string in utf-8 encoding on success or NULL otherwise.

sf_set_string()

SNDFILE2K_EXPORT int sf_set_string	(	SNDFILE *	sndfile,
		int	str_type,
		const char *	str
	)

Sets string field for given sound file.

Parameters

[in]	sndfile	Pointer to a sound file state
[in]	str_type	Type of field to set, one of SF_STR_FIELD values
[in]	str	Pointer to a null-terminated string with data to set

Note

Strings passed to this function is assumed to be utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8, others like WAV and AIFF officially only support ASCII. Current policy is to write such string as it is without conversion. Such tags can be read back with SndFile2K without problems, but other programs may fail to decode and display data correctly. If you want to write strings in ASCII, perform reencoding before passing data to sf_set_string().

Returns

Zero on success and non-zero value otherwise.