Tags handling
Using libmp3splt
Collaboration diagram for Tags handling:

## Macros

#define | SPLT_ID3V1_NUMBER_OF_GENRES 127
#define | SPLT_UNDEFINED_GENRE "Other"

## Typedefs

typedef struct _splt_tags | splt_tags
typedef struct _splt_tags_group | splt_tags_group

## Enumerations

enum | splt_tag_key { SPLT_TAGS_TITLE = 1, SPLT_TAGS_ARTIST = 2, SPLT_TAGS_ALBUM = 3, SPLT_TAGS_YEAR = 4, SPLT_TAGS_COMMENT = 5, SPLT_TAGS_TRACK = 6, SPLT_TAGS_GENRE = 7, SPLT_TAGS_PERFORMER = 8, SPLT_TAGS_ORIGINAL = 900 }

## Functions

splt_code | mp3splt_append_tags (splt_state *state, splt_tags *tags)
splt_code | mp3splt_erase_all_tags (splt_state *state)
void | mp3splt_free_one_tag (splt_tags *tags)
splt_tags_group * | mp3splt_get_tags_group (splt_state *state, splt_code *error)
splt_tags * | mp3splt_parse_filename_regex (splt_state *state, splt_code *error)
int | mp3splt_put_tags_from_string (splt_state *state, const char *tags, splt_code *error)
splt_code | mp3splt_read_original_tags (splt_state *state)
splt_code | mp3splt_remove_tags_of_skippoints (splt_state *state)
splt_code | mp3splt_set_default_comment_tag (splt_state *state, const char *default_comment_tag)
splt_code | mp3splt_set_default_genre_tag (splt_state *state, const char *default_genre_tag)
splt_code | mp3splt_set_input_filename_regex (splt_state *state, const char *regex)
char * | mp3splt_tags_get (splt_tags *tags, splt_tag_key key)
void | mp3splt_tags_group_init_iterator (splt_tags_group *tags_group)
splt_tags * | mp3splt_tags_group_next (splt_tags_group *tags_group)
splt_tags * | mp3splt_tags_new (splt_code *error)
splt_code | mp3splt_tags_set (splt_tags *tags,...)

## Variables

const char | splt_id3v1_genres [SPLT_ID3V1_NUMBER_OF_GENRES][25]

## Detailed Description

## Macro Definition Documentation

#define SPLT_ID3V1_NUMBER_OF_GENRES 127

Number of ID3v1 genres.

See Also
  splt_id3v1_genres

Definition at line 1417 of file mp3splt.h.

#define SPLT_UNDEFINED_GENRE "Other"

Undefined genre string.

Definition at line 1411 of file mp3splt.h.

Referenced by load_preferences().

## Typedef Documentation

typedef struct _splt_tags splt_tags

Structure containing the tags for one output file.

All members are private.

The structure contains the tags that we can set to one generated file. Tags may also define the output filenames.

See Also
  mp3splt_tags_set

Definition at line 1452 of file mp3splt.h.

typedef struct _splt_tags_group splt_tags_group

Structure containing a group of tags.

All members are private.

Definition at line 1504 of file mp3splt.h.

## Enumeration Type Documentation

enum splt_tag_key

Key tags useful with mp3splt_append_tags.

Enumerator
SPLT_TAGS_ORIGINAL | Use this to set original tags. You must call mp3splt_read_original_tags in order to use this.

Definition at line 1427 of file mp3splt.h.

## Function Documentation

splt_code mp3splt_append_tags | ( | splt_state * | state,
|  | splt_tags * | tags
| ) |  |

Append the `tags` in the `state`.

Tags must be appended in the same order as the splitpoints.

First appended tags are mapped to the segment between the first two splitpoints. Second appended tags are mapped to the second segment between the second and third splitpoints.

Parameters

  [in] | state | Main state.
  [in] | tags | Tags to be appended to the `state`.

Returns
  Possible error.

Referenced by put_splitpoints_and_tags_in_mp3splt_state().

Here is the caller graph for this function:

splt_code mp3splt_erase_all_tags | ( | splt_state * | state | ) |

Erase all the tags from the `state`.

Parameters

  [in] | state | Main state.

Returns
  Possible error.

void mp3splt_free_one_tag | ( | splt_tags * | tags | ) |

Free the memory of one splt_tags.

Parameters

  [in] | tags | Pointer to a splt_tags.

See Also
  mp3splt_parse_filename_regex

splt_tags_group* mp3splt_get_tags_group | ( | splt_state * | state,
|  | splt_code * | error
| ) |  |

Returns all the tags of the `state`.

Parameters

  [in] | state | Main state.
  [out] | error | Possible error; can be NULL.

Returns
  The tags group of the `state`.

See Also
  mp3splt_tags_group_init_iterator
  mp3splt_tags_group_next

splt_tags* mp3splt_parse_filename_regex | ( | splt_state * | state,
|  | splt_code * | error
| ) |  |

Parse the filename provided with mp3splt_set_filename_to_split using regex provided by mp3splt_set_input_filename_regex and returns the parsed tags.

Parameters

  [in] | state | Main state.
  [out] | error | Possible error; can be NULL.

Returns
  Parsed tags; must be freed with mp3splt_free_one_tag.

See Also
  mp3splt_set_filename_to_split
  mp3splt_set_input_filename_regex
  mp3splt_free_one_tag

int mp3splt_put_tags_from_string | ( | splt_state * | state,
|  | const char * | tags,
|  | splt_code * | error
| ) |  |

Fill the `state` with tags parsed from the `tags` string.

`tags` should contain one or more square brackets pairs []. The tags defined in the first pair of square brackets will be set on the first split file. Those defined in the second pair of square brackets will be set on the second split file, ... Inside a pair of square brackets, each tag is defined as @variable=value and they tags are separated by commas. If a percent sign % is found before the open square bracket character, then the pair of square brackets following the % character will define the default tags in the following files. Multiple '' can be defined. An optional 'r' character can be placed at the start, to replace tags in tags. The 'replace tags in tags' option is not recursive.

Variables can be: @a - artist, @b - album, @t - title, @y - year, @c - comment, @g - genre, @n - track number, @o - set original tags, @N - auto increment track number. Variables for the start splitpoint: @m - minutes, @s - seconds, @h - hundreths of seconds. Variables for the end splitpoint: @M - minutes, @S - seconds, @H - hundreths of seconds.

Using the 'replace tags in tags' option, you can also use the following variables, which are replaced by the data from the original tags: #a, #b, #t, #y, #c, #g. Note that this will only work if @o has been found before.

Parameters

  [in] | state | Main state.
  [in] | tags | String containing tags to be parsed and appended.
  [out] | error | Possible error; can be NULL.

Returns
  SPLT_TRUE if the input tags are ambiguous. Tags might be ambiguous if the input does not seem to be valid or if @t or @n is missing.

splt_code mp3splt_read_original_tags | ( | splt_state * | state | ) |

Parses the original tags from the input file and stores them for the future split.

This function must be called when using SPLT_TAGS_ORIGINAL called by mp3splt_tags_set.

Parameters

  [in] | state | Main state.

Returns
  Possible error.

splt_code mp3splt_remove_tags_of_skippoints | ( | splt_state * | state | ) |

Removes all the tags of the `state` for the skippoints.

Parameters

  [in] | state | Main state.

Returns
  Possible error.

splt_code mp3splt_set_default_comment_tag | ( | splt_state * | state,
|  | const char * | default_comment_tag
| ) |  |

Default comment tag when using SPLT_TAGS_FROM_FILENAME_REGEX and no comment found.

Parameters

  [in] | state | Main state.
  [in] | default_comment_tag | Default comment if no comment has been found.

Returns
  Possible error.

See Also
  mp3splt_set_input_filename_regex

splt_code mp3splt_set_default_genre_tag | ( | splt_state * | state,
|  | const char * | default_genre_tag
| ) |  |

Default genre tag when using SPLT_TAGS_FROM_FILENAME_REGEX and no genre found.

Parameters

  [in] | state | Main state.
  [in] | default_genre_tag | Default genre if no genre has been found.

Returns
  Possible error.

See Also
  mp3splt_set_input_filename_regex

splt_code mp3splt_set_input_filename_regex | ( | splt_state * | state,
|  | const char * | regex
| ) |  |

Defines the regex that will be used for SPLT_TAGS_FROM_FILENAME_REGEX.

Tags will be extracted using the following variables: (?<artist>), (?<album>), (?<title>), (?<tracknum>), (?<year>), (?<comment>), (?<genre>).

Example: (?<artist>.*?) _ (?<album>.*?) will extract 'one artist' and 'one album' from 'one artist _ one album'.

Parameters

  [in] | state | Main state.
  [in] | regex | Regular expression used to set the tags from the filename.

Returns
  Possible error.

char* mp3splt_tags_get | ( | splt_tags * | tags,
|  | splt_tag_key | key
| ) |  |

Returns the value of `key` from the `tags`.

Result must be freed.

void mp3splt_tags_group_init_iterator | ( | splt_tags_group * | tags_group | ) |

Initialisation of the iterator for use with mp3splt_tags_group_next.

Parameters

  [in] | tags_group | Group of tags returned with mp3splt_get_tags_group.

See Also
  mp3splt_tags_group_next

splt_tags* mp3splt_tags_group_next | ( | splt_tags_group * | tags_group | ) |

Returns the next tags from the `tags_group`.

Parameters

  [in] | tags_group | Tags group to be processed.

Returns
  Next tags of `tags_group` or NULL if none found or no tags remains.

See Also
  mp3splt_tags_get

splt_tags* mp3splt_tags_new | ( | splt_code * | error | ) |

Creates a new tags structure.

Parameters

  [in] | error | Possible error; can be NULL.

Returns
  Newly allocated tags.

See Also
  mp3splt_tags_set
  mp3splt_append_tags

Referenced by put_splitpoints_and_tags_in_mp3splt_state().

Here is the caller graph for this function:

splt_code mp3splt_tags_set | ( | splt_tags * | tags,
|  |  | ...
| ) |  |

Set tags values in the `tags`.

The ... parameters are pairs of (key, value); arguments must end with 0, where key is a splt_tag_key and value is const char *.

Example:

mp3splt_tags_set(tags, SPLT_TAGS_ARTIST, "my_artist", SPLT_TAGS_ALBUM, "my_album", 0);

When using SPLT_TAGS_ORIGINAL, the only possible values are "true" or "false". In order to use SPLT_TAGS_ORIGINAL, you have to call mp3splt_read_original_tags before.

Parameters

  [in] | tags | Tags to be changed.

Returns
  Possible error.

See Also
  mp3splt_append_tags

Referenced by put_splitpoints_and_tags_in_mp3splt_state().

Here is the caller graph for this function:

## Variable Documentation

const char splt_id3v1_genres[SPLT_ID3V1_NUMBER_OF_GENRES][25]

ID3v1 genres.