puddletag

puddletag is an audio tag editor (primarily created) for GNU/Linux similar to the Windows program, Mp3tag. Unlike most taggers for GNU/Linux, it uses a spreadsheet-like layout so that all the tags you want to edit by hand are visible and easily editable.

The usual tag editor features are supported like extracting tag information from filenames, renaming files based on their tags by using patterns and basic tag editing.

Then there’re Functions, which can do things like replace text, trim it, do case conversions, etc. Actions can automate repetitive tasks. Doing web lookups using Amazon (including cover art), Discogs (does cover art too!), FreeDB and MusicBrainz is also supported. There’s quite a bit more, but I’ve reached my comma quota.

Supported formats: ID3v1, ID3v2 (mp3, wav, aac, aiff, dsf), MP4 (mp4, m4a, etc.), VorbisComments (ogg, flac), Musepack (mpc), Monkey’s Audio (.ape), WavPack (wv), OptimFROG (ofr, ofs), TAK (tak) and TrueAudio (tta).

Recent development

This repository has recently received renewed maintenance work, including:

• PyQt6 migration and Wayland/HiDPI startup improvements.
• Spanish translation packaging fixes and locale fallback from regional Spanish locales such as es_EC to the available es_ES catalog.
• Expanded audio format support for WAV, AAC, AIFF, DSF, OptimFROG, TAK, and TTA.
• Template-based export support for HTML, RTF, and CSV.
• Native playlist save/update support.
• Rhythmbox and MPD music library integration.
• Dark mode, a built-in log viewer, library statistics, and duplicate-finder improvements.
• CLI commands for export and tag editing.
• Generated documentation for supported audio formats, action functions, tag sources, and bundled plugins.
• A comprehensive plugin API reference for plugin developers, and a fix so user plugins in ~/.puddletag/plugins load again.
• AppImage packaging: create_appimage.sh build script and AppStream metainfo (puddletag.appdata.xml).

Dependencies

puddletag uses several third-party modules to performs its tasks:

• Python3
• PyQt6, for the GUI.
• configobj
• pyparsing , takes care of the parsing
• Mutagen, used as the tagging lib
• Chromaprint (recommended), for AcoustID support
• unidecode

How to install

PyPI

Puddletag is available on PyPI.

In addition to the full releases, every time we merge a PR or commit a change, we automatically release a new version on TestPyPI, so if you want to try a brand new feature or a recent bugfix, you can give these pre-releases a try.

There are several tools to install puddletag via PyPI, for example pip, pipx, pipenv, and several others. Choose the one that suits best your workflow, but we strongly recommend you create an isolated, local (f.e. by using pip install --local) environment when installing third-party software.

Distributions package

Here below is a list of the distributions and platforms where puddletag is available, and how to install it:

Debian

apt install puddletag

Contact: @sandrotosi

Gentoo

1. overlay: https://github.com/istitov/stuff/
2. add overlay: sudo layman -a stuff
3. install: sudo emerge -av puddletag

Contact: @DolphinStKom

Arch Linux

puddletag is currently part of the AUR:

git clone https://aur.archlinux.org/puddletag.git
cd puddletag
makepkg -si

Fedora

Available since Fedora 32.

dnf install puddletag

Nix

Available for channels 24.05 and unstable

On NixOS:

nix-env -iA nixos.puddletag

On Non NixOS:

# without flakes:
nix-env -iA nixpkgs.puddletag
# with flakes:
nix profile install nixpkgs#puddletag

NixOS configuration: Add the following Nix code to your NixOS Configuration, usually located in /etc/nixos/configuration.nix

  environment.systemPackages = [
    pkgs.puddletag
  ];

Brew/MacOS

support needed, open an issue if interested in working on it

Source Code

If you seek the bleeding edge of puddletag, or wanting to contribute (we welcome all contributions!) you can install and/or run via source code.

First, you need to install the dependencies; this step is different depending on the distribution; on Debian you can run:

apt install python3 python3-mutagen python3-configobj python3-pyparsing python3-pyqt6 python3-pyqt6.qtsvg python3-unidecode

For documentation and tests during development on Debian, also install:

apt install python3-sphinx python3-sphinx-bootstrap-theme python3-pytest

For translation testing and editing, see TRANSLATION_TESTING.md.

Then, clone the repo and run puddletag:

git clone 'https://github.com/puddletag/puddletag'
cd 'puddletag'
./puddletag

Alternatively you can use a virtual environment to install the dependencies, which only requires python and pip to be installed:

git clone 'https://github.com/puddletag/puddletag.git'
cd 'puddletag'
python3 -m 'venv' '.'
bin/pip3 install -r 'requirements.txt'
bin/python3 'puddletag'

License

puddletag is licensed under the GPLv3, which you can find in its entirety at http://www.gnu.org/licenses/gpl-3.0.html