Tag Parser  8.1.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
doc/adding-new-fields.md
Go to the documentation of this file.
1 # Adding a new field
2 
3 This document describes how to add support for a new field. From these instructions
4 one can also deduce what places need to be adjusted when amending support for a field.
5 
6 ## Support new field in tagparser library
7 1. Check whether https://wiki.hydrogenaud.io/index.php?title=Tag_Mapping contains
8  a recommendation for the specific field to be added.
9 2. Add the field to the enum `KnownField`.
10 3. Adjust `TagParser::lastKnownField` accordingly.
11 4. Adjust `TagParser::Tag::proposedDataType()` if it is not a text field.
12  Consider that this method might be overwritten in format-specific implementations
13  which might need adjustment as well.
14 5. Add the format-specific IDs to the corresponding header files, e.g. `vorbiscommentids.h`
15  for Vorbis Comments.
16 6. Add the field mapping to the `internallyGetFieldId()` and
17  `internallyGetKnownField()` methods of all formats which
18  should be supported, e.g. `TagParser::Id3v2Tag::internallyGetFieldId()`.
19 7. For ID3v2 tags add the mapping `convertToShortId()` and `convertToLongId()` if
20  possible.
21 
22 ## Support new field in the tag editor application
23 1. Add the field to the `KnownFieldModel` class.
24  1. Add the English denotation of the field to `KnownFieldModel::fieldName`.
25  2. Add the field to the constructor `KnownFieldModel::KnownFieldModel` which
26  composes the list of fields shown in the GUI and whether they are displayed
27  by default or not.
28 2. Add the field to the `FIELD_NAMES` macro. It is used for the CLI's auto-completion
29  and `print-field-names`. Only use small letters (a to z) here. No whitespaces!
30 3. Add the field to the `FieldMapping::fieldMapping` array used by the CLI. Be consistent
31  with 2.!