Vorbis, Speex and Theora 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 comment block contains one Vendor string, which can be retrieved with oggz_comment_get_vendor().
The rest of a comment block consists of name = value pairs, with the following restrictions:
#include <oggz/oggz.h>
Go to the source code of this file.
Data Structures | |
struct | OggzComment |
A comment. More... | |
Functions | |
const char * | oggz_comment_get_vendor (OGGZ *oggz, long serialno) |
Retrieve the vendor string. | |
int | oggz_comment_set_vendor (OGGZ *oggz, long serialno, const char *vendor_string) |
Set the vendor string. | |
const OggzComment * | oggz_comment_first (OGGZ *oggz, long serialno) |
Retrieve the first comment. | |
const OggzComment * | oggz_comment_next (OGGZ *oggz, long serialno, const OggzComment *comment) |
Retrieve the next comment. | |
const OggzComment * | oggz_comment_first_byname (OGGZ *oggz, long serialno, char *name) |
Retrieve the first comment with a given name. | |
const OggzComment * | oggz_comment_next_byname (OGGZ *oggz, long serialno, const OggzComment *comment) |
Retrieve the next comment following and with the same name as a given comment. | |
int | oggz_comment_add (OGGZ *oggz, long serialno, OggzComment *comment) |
Add a comment. | |
int | oggz_comment_add_byname (OGGZ *oggz, long serialno, const char *name, const char *value) |
Add a comment by name and value. | |
int | oggz_comment_remove (OGGZ *oggz, long serialno, OggzComment *comment) |
Remove a comment. | |
int | oggz_comment_remove_byname (OGGZ *oggz, long serialno, char *name) |
Remove all comments with a given name. | |
ogg_packet * | oggz_comment_generate (OGGZ *oggz, long serialno, OggzStreamContent packet_type, int FLAC_final_metadata_block) |
Output a comment packet for the specified stream. | |
void | oggz_packet_destroy (ogg_packet *packet) |
Free a packet and its payload. |
int oggz_comment_add | ( | OGGZ * | oggz, | |
long | serialno, | |||
OggzComment * | comment | |||
) |
Add a comment.
oggz | A OGGZ* handle (created with mode OGGZ_WRITE) | |
serialno | Identify a logical bitstream within oggz | |
comment | The comment to add |
0 | Success | |
OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle | |
OGGZ_ERR_INVALID | Operation not suitable for this OGGZ |
int oggz_comment_add_byname | ( | OGGZ * | oggz, | |
long | serialno, | |||
const char * | name, | |||
const char * | value | |||
) |
Add a comment by name and value.
oggz | A OGGZ* handle (created with mode OGGZ_WRITE) | |
serialno | Identify a logical bitstream within oggz | |
name | The name of the comment to add | |
value | The contents of the comment to add |
0 | Success | |
OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle | |
OGGZ_ERR_INVALID | Operation not suitable for this OGGZ |
const OggzComment* oggz_comment_first | ( | OGGZ * | oggz, | |
long | serialno | |||
) |
Retrieve the first comment.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz |
NULL | No comments exist for this OGGZ* object, or serialno does not identify an existing logical bitstream in oggz. |
const OggzComment* oggz_comment_first_byname | ( | OGGZ * | oggz, | |
long | serialno, | |||
char * | name | |||
) |
Retrieve the first comment with a given name.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz | |
name | the name of the comment to retrieve. |
NULL | No match was found, or serialno does not identify an existing logical bitstream in oggz. |
ogg_packet* oggz_comment_generate | ( | OGGZ * | oggz, | |
long | serialno, | |||
OggzStreamContent | packet_type, | |||
int | FLAC_final_metadata_block | |||
) |
Output a comment packet for the specified stream.
oggz | A OGGZ* handle (created with OGGZ_WRITE) | |
serialno | Identify a logical bitstream within oggz | |
packet_type | Type of comment packet to generate, FLAC, OggPCM, Speex, Theora and Vorbis are supported | |
FLAC_final_metadata_block | Set this to zero unless the packet_type is FLAC, and there are no further metadata blocks to follow. See note below for details. |
NULL | content type does not support comments, not enough memory or comment was too long for FLAC |
const char* oggz_comment_get_vendor | ( | OGGZ * | oggz, | |
long | serialno | |||
) |
Retrieve the vendor string.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz |
NULL | No vendor string is associated with oggz, or oggz is NULL, or serialno does not identify an existing logical bitstream in oggz. |
const OggzComment* oggz_comment_next | ( | OGGZ * | oggz, | |
long | serialno, | |||
const OggzComment * | comment | |||
) |
Retrieve the next comment.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz | |
comment | The previous comment. |
NULL | serialno does not identify an existing logical bitstream in oggz. |
const OggzComment* oggz_comment_next_byname | ( | OGGZ * | oggz, | |
long | serialno, | |||
const OggzComment * | comment | |||
) |
Retrieve the next comment following and with the same name as a given comment.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz | |
comment | A comment |
NULL | No further comments with the same name exist for this OGGZ* object, or serialno does not identify an existing logical bitstream in oggz. |
int oggz_comment_remove | ( | OGGZ * | oggz, | |
long | serialno, | |||
OggzComment * | comment | |||
) |
Remove a comment.
oggz | A OGGZ* handle (created with OGGZ_WRITE) | |
serialno | Identify a logical bitstream within oggz | |
comment | The comment to remove. |
1 | Success: comment removed | |
0 | No-op: comment not found, nothing to remove | |
OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle | |
OGGZ_ERR_INVALID | Operation not suitable for this OGGZ | |
OGGZ_ERR_BAD_SERIALNO | serialno does not identify an existing logical bitstream in oggz. |
int oggz_comment_remove_byname | ( | OGGZ * | oggz, | |
long | serialno, | |||
char * | name | |||
) |
Remove all comments with a given name.
oggz | A OGGZ* handle (created with OGGZ_WRITE) | |
serialno | Identify a logical bitstream within oggz | |
name | The name of the comments to remove |
>= 0 | The number of comments removed | |
OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle | |
OGGZ_ERR_INVALID | Operation not suitable for this OGGZ | |
OGGZ_ERR_BAD_SERIALNO | serialno does not identify an existing logical bitstream in oggz. |
int oggz_comment_set_vendor | ( | OGGZ * | oggz, | |
long | serialno, | |||
const char * | vendor_string | |||
) |
Set the vendor string.
oggz | A OGGZ* handle | |
serialno | Identify a logical bitstream within oggz | |
vendor_string | The contents of the vendor string to add |
0 | Success | |
OGGZ_ERR_BAD | oggz is not a valid OGGZ* handle | |
OGGZ_ERR_INVALID | Operation not suitable for this OGGZ |
void oggz_packet_destroy | ( | ogg_packet * | packet | ) |
Free a packet and its payload.
packet | A packet previously returned from a function such as oggz_comment_generate(). User generated packets should not be passed. |