Martchus / tageditor

A tag editor with Qt GUI and command-line interface supporting MP4/M4A/AAC (iTunes), ID3, Vorbis, Opus, FLAC and Matroska
GNU General Public License v2.0
692 stars 56 forks source link
aac flac hacktoberfest id3 matroska matroska-files mp4 opus qt-gui tagging vorbis

Tag Editor

A tag editor with Qt GUI and command-line interface. Supports MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska.

Supported formats

The tag editor can read and write the following tag formats:

Further remarks:

Additional features

The tag editor can also display technical information such as the ID, format, language, bitrate, duration, size, timestamps, sampling frequency, FPS and other information of the tracks.

It also allows to inspect and validate the element structure of MP4 and Matroska files.

Backup/temporary files

Sometimes the tag editor has to rewrite the entire file in order to apply changes. This leads to the creation of a temporary file. With the GUI's default settings this is even enforced to be conservative as the temporary files also serve as a backup in case something goes wrong, e.g. your computer crashes while saving or a bug within the tag editor breaks particularly structured files. When using the CLI it is therefore also recommend to use --force-rewrite.

The next section describes how to tweak settings to avoid rewriting at the cost of having no backup, having some padding within the files and/or storing tags at the end of the file.

Nevertheless, it will not always be possible to avoid rewriting a file in all cases anyways. You can configure a directory for temporary files within the GUI settings or the CLI option --temp-dir. Then you can easily clean up all temporary files at some point together. For efficiency the temporary directory should be on the same file system as the files you are editing. A feature to delete temporary files automatically has not been implemented yet.

File layout options

Tag position

The editor allows you to choose whether tags should be placed at the beginning or at the end of an MP4/Matroska file. Placing tags at the end of the file can avoid having to rewrite the entire file to apply changes.

In the CLI, this is controlled via --tag-pos option. To enforce a specific --tag-pos, even if this requires the file to be rewritten, combine with the --force option.

ID3v2 tags and Vorbis/Opus comments can only be placed at the beginning. ID3v1 tags can only be placed at the end of the file. Hence, this configuration has no effect when dealing with such tags.

Index position

It is also possible to control the position of the index/cues. However, this is currently only supported when dealing with Matroska files.

Note: This can not be implemented for MP4 since tags and index are tied to each other. When dealing with MP4 files the index position will always be the same as the tag position.

Faststart

Putting the index at the beginning of the file is sometimes called faststart.

For forcing faststart via CLI the following options are required:

tageditor set --index-pos front --force

Padding

Padding allows adding additional tag information without rewriting the entire file or appending the tag. Usage of padding can be configured:

It is also possible to force rewriting the entire file to enforce the preferred padding is used.

The relevant CLI options are --min-padding, --max-padding, --preferred-padding and --force-rewrite.

Taking advantage of padding is currently not supported when dealing with Ogg streams (it is supported when dealing with raw FLAC streams).

Avoid rewriting files

As explained in the "Backup/temporary files" section, this is not a good idea as the temporary file that is created when rewriting the entire file also serves as backup. However, if you nevertheless want to avoid rewriting the file as much as possible, set the following in the GUI's "File layout" settings:

When using the CLI, you just need to add --max-padding 429496729 to the CLI arguments (and avoid any of the other arguments mentioned in previous sections).

Improve performance

Editing big files (especially Matroska files) can take some time. To improve the performance, put the index at the end of the file (CLI option --index-pos back) because then the size of the index will never have to be recalculated. Also follow the advice from the "Backup/temporary files" section to force rewriting and to put the temporary directory on the same filesystem as the file you are editing. Forcing a rewrite can improve the performance because then the tag editor will not even try to see whether it could be avoided and can thus skip computations that can take a notable time for big Matroska files.

Of course being able to avoid a rewrite would still be more optimal. Checkout the previous section for how to achieve that. To improve performance further when avoiding a rewrite, put the tag at the end (CLI option --tag-pos back). Then the tag editor will not even try to put tags at the front and can thus skip a few computations. (Avoiding a rewrite is still not a good idea in general.)

Matroska-related remarks

The Matroska container format (and WebM which is based on Matroska) are breaking with common conventions. Therefore not all CLI examples mentioned below make sense to use on such files.

Generally, one Matroska file can have multiple tags and each tag has a "target" which decides to what the fields of the tag apply to, e.g. the song or the whole album. So when using the CLI or the GUI you need to be aware to what tag/target to add fields to.

Matroska also does not use one combined field for the track/disk number and total like other formats do. It instead uses the separate fields part and totalparts which again need to be added to a tag of the desired target (e.g. 50/"ALBUM" for the track number and total).

Checkout the official Matroska documentation on tagging for details. It also contains examples for audio content and video content.

Note that Tag Editor does not support the XML format mentioned on the Matroska documentation. In the GUI you can simply add/remove/edit tags and their targets via the controls at the top of the editor. In the settings you can also specify that tags of certain targets should be added automatically when loading a file. When using the CLI you can specify that a field should be added to a tag of a certain target by specifying the target before that field. You can also explicitly remove tags of certain targets. Examples of the concrete CLI usage can be found below.

Download

Source

See the release section on GitHub.

Packages and binaries

Usage

The Tag Editor has a Qt-based GUI and a command line interface. For a C++ library interface checkout the underlying tagparser library.

GUI

The GUI should be self-explaining - a lot of the UI elements have tooltips with further explanations. The basic workflow is quite simple:

  1. Open a file
  2. Edit the tags
  3. Save changes

You can set the behaviour of the editor to keep previous values, so you don't have to enter information like album name or artist for all files in an album again and again.

Limitations

The GUI does not support setting multiple values of the same field (besides covers of different types). If a file already contains fields with multiple values, the additional values are discarded. Use the CLI if support for multiple values per field is required. Not all tag formats support this anyways, though.

The GUI does not support batch processing. I recommend using the CLI for this.

Screenshots

Main window under Openbox/qt5ct with Breeze theme/icons

main window/Openbox/qt5ct/Breeze theme

Main window under Plasma 5 with dark Breeze theme/icons

This screenshot shows the experimental MusicBrainz/LyricWiki search.

main window/Plasma 5/dark Breeze theme

Settings

Checkout the settings dialog. You can

Settings of the GUI do not affect the CLI.

File renaming

There is also a tool to rename files using the tag information stored in the files. The new name for each file is generated by a small JavaScript which can be customized. An example script is provided. Before any actual changes are made, you will see a preview with the generated file names. As shown in the example script it is also possible to move files into another directory.

MusicBrainz, Cover Art Archive and LyricWiki search

The tag editor also features a MusicBrainz, Cover Art Archive and LyricWiki search.

  1. Open the search by pressing F10.
  2. Open the first file in the album.
  3. If album and artist are already present those are automatically inserted as search terms. Otherwise you need to enter the album and artist to search for manually. It makes most sense to search for an entire album and therefore leave the fields for track number and title blank.
  4. Click on "Search" and select on of the query options.
  5. Select the row and fields to be used and click on "Use row". You can also double click the row you want to use.
  6. Use the "Insert automatically" option to insert search results for the next files automatically when you open them. To find the matching row for the song in the search results the title or track number needs to be present. If artist and album are present as well these are also tried to match for further disambiguation.
Notes

CLI

Usage

tageditor <operation> [options]

Checkout the available operations and options with --help. For a list of all available field names, track attribute names and modifier, use the CLI option --print-field-names. Not all fields are supported by all tag/container formats. Most notably, the Matroska container format does not use track/disk to store the track/disk number and total in one field. Instead, the fields part and totalparts need to be used on the desired target.

Note that Windows users must use tageditor-cli.exe instead of tageditor.exe or use Mintty as terminal. Checkout the "Windows-specific issues" section for details.

Examples

Here are some Bash examples which illustrate getting and setting tag information:

Reading tags
Modifying tags and track attributes
Further useful commands

Text encoding / unicode support

  1. It is possible to set the preferred encoding used within the tags via CLI option --encoding and in the GUI settings.
    • However, in the GUI this only affects visible fields. In the CLI only specified fields are affected. So reencoding all text fields is currently not supported.
    • The option is ignored (with a warning) when the specified encoding is not supported by the tag format.
  2. The CLI assumes all arguments to be UTF-8 encoded (no matter which preferred encoding is specified) and file names are just passed as specified.
  3. The CLI prints all values in UTF-8 encoding (no matter which encoding is actually used in the tag).

Build instructions

The application depends on c++utilities and tagparser and is built the same way as these libraries. For basic instructions checkout the README file of c++utilities. When the Qt GUI is enabled, Qt and qtutilities are required, too.

To avoid building c++utilities/tagparser/qtutilities separately, follow the instructions under "Building this straight". There's also documentation about various build variables which can be passed to CMake to influence the build.

Building with Qt GUI

The Qt GUI is enabled by default. The following Qt modules are required (only the latest Qt 5 and Qt 6 version tested): core concurrent gui network widgets declarative/script webenginewidgets/webkitwidgets

Note that old Qt versions lack support for modern JavaScript features. To use the JavaScript-based renaming tool it is recommend to use at least Qt 5.12.

To specify the major Qt version to use, set QT_PACKAGE_PREFIX (e.g. add -DQT_PACKAGE_PREFIX:STRING=Qt6 to the CMake arguments).

Select Qt module for web view and JavaScript

Building without Qt GUI

It is possible to build without the GUI if only the CLI is needed. In this case no Qt dependencies (including qtutilities) are required.

To build without GUI, add the following parameters to the CMake call:

-DWIDGETS_GUI=OFF -DQUICK_GUI=OFF

JSON export

As a small demo for Reflective RapidJSON, the tag editor features an optional JSON export. To enable it, add -DENABLE_JSON_EXPORT=ON to the CMake arguments.

When enabled, the following additional dependencies are required (only at build-time): rapidjson, reflective-rapidjson and llvm/clang

Building this straight

  1. Install (preferably the latest version of) the GCC toolchain or Clang, the required Qt modules, iso-codes, iconv, zlib, CMake and Ninja.
  2. Get the sources of additional dependencies and the tag editor itself. For the latest version from Git clone the following repositories:
    cd "$SOURCES"
    git config core.symlinks true                                          # only required on Windows
    git clone https://github.com/Martchus/cpp-utilities.git c++utilities
    git clone https://github.com/Martchus/tagparser.git
    git clone https://github.com/Martchus/qtutilities.git                  # only required for Qt GUI
    git clone https://github.com/Martchus/reflective-rapidjson.git         # only required for JSON export
    git clone https://github.com/Martchus/tageditor.git
    git clone https://github.com/Martchus/subdirs.git

    Note that git config core.symlinks=true is only required under Windows to handle symlinks correctly. This requires a recent Git version and a filesystem which supports symlinks (NTFS works). Additionally, you need to enable Windows Developer Mode. If you run into "not found" errors on symlink creation use git reset --hard within the repository to fix this.

  3. Configure the build
    cd "$BUILD_DIR"
    cmake \
    -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DLANGUAGE_FILE_ISO_639_2="/usr/share/iso-codes/json/iso_639-2.json" \
    -DCMAKE_INSTALL_PREFIX="/install/prefix" \
    "$SOURCES/subdirs/tageditor"
    • Replace /install/prefix with the directory where you want to install.
    • Replace /usr/…/iso_639-2.json with the path for your iso-codes installation.
  4. Build and install everything in one step:
    cd "$BUILD_DIR"
    ninja install
    • If the install directory is not writable, do not conduct the build as root. Instead, set DESTDIR to a writable location (e.g. DESTDIR="temporary/install/dir" ninja install) and move the files from there to the desired location afterwards.

TODOs and known problems

Known problems and caveats

Windows-specific issues

The following caveats can be worked around by using the CLI-wrapper instead of the main executable. This is the file that ends with -cli.exe. Alternatively you may use Mintty (e.g. via MSYS2) which is also not affected by those issues:


Dark mode should work out of the box under Windows 11 and can otherwise be enabled by selecting the Fusion style.


Tag Editor supports PMv2 out of the box as of Qt 6. You may tweak settings according to the Qt documentation.

Copyright notice and license

Copyright © 2015-2024 Marius Kittler

All code is licensed under GPL-2-or-later.

Attribution for 3rd party content