Tagging music files is a way of keeping a music library well organized and let us search for songs on the base of Artists, albums, genre and other parameters. Many graphical and command line applications exist on Linux to manage tags for audio files, like Picard or Quodlibet. Most of those applications are written in Python and use the “mutagen” module at their core. In this tutorial we learn how to use it directly.
In this tutorial you will learn:
- How to install the mutagen python3 module
- How to open an audio file
- How to read, add and remove tags
- How to access audio stream information
Software requirements and conventions used
| Category | Requirements, Conventions or Software Version Used |
|---|---|
| System | Distribution-independent |
| Software | Python3 and the mutagen module |
| Other | Basic knowledge of Python and object oriented programming |
| Conventions | # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command$ – requires given linux-commands to be executed as a regular non-privileged user |
Installing mutagen
Installing the mutagen Python module is quite simple. The software is free and open source, and it is included in the official repositories of the most commonly used Linux distributions, such as Fedora, Debian and ArchLinux, therefore we can install it using the package managers of those systems. On Fedora, for example, the package manager is called dnf, and the command we should run to install mutagen is the following:
$ sudo dnf install python3-mutagen
On Debian and its many derivatives, instead, we use apt:
$ sudo apt install python3-mutagen
If we are running on Archlinux, instead, we can use pacman to install software packages. In this case the command we need to run is:
$ sudo pacman -Sy python-mutagen
The alternative, universal, method we can use to install mutagen is by using
pip: the python package manager. One advantage of this method is that we will always obtain the latest stable version of the software, which we can install without the need of privilege escalation. To install mutagen using pip only for our user, we should run:
$ pip install --user mutagen
Opening an audio file
Once mutagen is installed, we can start working with it. Let’s start from the basics. The first thing we want to do, of course, is to import the module, and “open” a file, which for the sake of this example, is in the FLAC format (FLAC stands for Free Lossless Audio Codec). The song is we_disintegrate.flac by Nevermore:
>>> import mutagen
>>> a = mutagen.File('we_disintegrate.flac')
In the example above, to open the file we used the File function included in the mutagen module. What this function does? It tries to guess the type of the file which is passed as argument by examining its first 128 bytes, its extension, and the presence of already existing tags, and tries to open it, returning an instance of the appropriate class which extends the generic FileType. In this case, for example, it returns an instance of the Flac class. This is the object we will interact with the most:
>>> type(a) <class 'mutagen.flac.FLAC'>
If we know the filetype of the audio file beforehand, we can instantiate the appropriate class directly. In this case, for example, we could have run:
>>> from mutagen.flac import FLAC
>>> a = FLAC('we_disintegrate.flac')
What if we try to instantiate the wrong FileType class for a file? Imagine we try to create an instance of the FLAC class passing an mp3 audio file as argument. As you can see, an exception would be raised:
>>> a = FLAC('01_an_ancient_sign_of_the_coming_storm.mp3')
[...]
mutagen.flac.FLACNoHeaderError: '01_an_ancient_sign_of_coming_storm.mp3' is not a valid FLAC file
The FLACNoHeaderError exception its an extension of the Error class, which in its turn extends MutagenError, therefore we can catch the latter if we need to handle errors in a more generic way.
Managing tags
Once we created an instance of the appropriate FileType class, either directly or via the File function, we can access the tags of an audio file via the tags attribute, which is the appropriate instance of a mutagen.Tag child class (this is done because tags are managed differently in the different audio containers: in FLAC files, for example, tags are stored as vorbis comments):
>>> from mutagen.flac import FLAC
>>> a = FLAC('we_disintegrate')
>>> type(a.tags)
<class 'mutagen.flac.VCFLACDict'>
The tags can be accessed and modified via a dictionary-like interface. The available tags depend on the file type. I previously tagged the file, so, for example, to check what is the value associated with the ‘ARTIST’ tag, I would run:
>>> a.tags['ARTIST'] ['Nevermore']
As a shortcut, tags can also be accessed, using the same type of interface, directly on the FileType based class we are using. We could retrieve the value corresponding to the ARTIST tag by using the following code:
>>> a['ARTIST']
To change the value of a tag or add a new tag, we would simply assign its value:
>>> a.tags['ARTIST'] = 'Someotherartist'
To visualize all the tags and their values, we simply access the a.tags attribute: they would be returned as a list of two-items tuples, where the first element is the key and the second is its value. To obtain a “pretty printed” list of tags and values, instead, we can use the pprint method: it returns a string where each tag with its value is separated from the others with a newline character \n. Printing that string would therefore return a result similar to the following:
>>> print(a.tags.pprint()) MUSICBRAINZ_RELEASEGROUPID=e34d3efe-e062-3ffe-86b0-0e124fa429fd ORIGINALDATE=2000-09-17 ORIGINALYEAR=2000 RELEASETYPE=album MUSICBRAINZ_ALBUMID=ca554c0f-7e0c-4fd6-b56e-0081a1b1b143 MUSICBRAINZ_ALBUMARTISTID=7d093650-89be-4108-842b-ba7f5367504b ALBUMARTIST=Nevermore ALBUMARTISTSORT=Nevermore ALBUM=Dead Heart in a Dead World RELEASECOUNTRY=XE LABEL=Century Media CATALOGNUMBER=77310-2 ASIN=B000A69REE RELEASESTATUS=official SCRIPT=Latn BARCODE=5051099731028 DATE=2011-03-01 TOTALDISCS=1 TOTALTRACKS=11 DISCNUMBER=1 MEDIA=CD MUSICBRAINZ_TRACKID=5eb91e83-aa7c-491c-95fc-67f16dac2afe ISRC=US4E40401002 MUSICBRAINZ_ARTISTID=7d093650-89be-4108-842b-ba7f5367504b ARTISTSORT=Nevermore ARTISTS=Nevermore TITLE=We Disintegrate MUSICBRAINZ_RELEASETRACKID=085cd92f-825f-3765-a951-b6b4f357b779 TRACKNUMBER=2 TRACKTOTAL=11 DISCTOTAL=1 ARTIST=Nevermore
Removing a tag
Sometimes we just don’t want to change the value associated with a tag, but remove the tag completely. To achieve this task we can use the pop method of the FileType object and pass the name of the tag as argument. Say for example we want to remove the BARCODE tag. Here is the code we would write:
>>> a.pop('BARCODE')
Deleting all tags from a file
In some situations we may want to just remove all the existing tags from a file. In those cases, we want to use the delete method of the FileType object:
>>> a.delete() >>> a.tags []
When dealing with FLAC files, we may also want to remove any embed images: we can do it by using the
clear_pictures method.
Changes like the ones we saw in the previous examples, performed on the metadata of an audio file with mutagen, are not immediately effective. To make them persistent we need to call another method: save. The arguments accepted by this method may vary depending on the FileType based class we are using.
Accessing audio stream information
We can access an audio file stream information, like for example its length and bitrate, via the info property of the FileType object. Since in this case the file is a FLAC, it will be an instance of the mutagen.flac.StreamInfo class. We can access the single information using this class property. For example, let’s say we want to check the audio bitrate value; we would run:
>>> from mutagen.flac import FLAC
>>> a = FLAC('we_disintegrate.flac')
>>> a.info.bitrate
1016635
As we did for tags, to obtain a nice-formatted list of the stream attributes, we would use the pprint method:
>>> print(a.info.pprint()) FLAC, 311.99 seconds, 44100 Hz
Not all the available information, however, are reported in the output returned by this method, as you can see.
Conclusions
In this tutorial we learned the basic usage of the mutagen Python module. This module is used in many tagging applications, as Musicbrainz Picard. We saw how to install it using some of the most used Linux distribution’s package managers and via pip, how to use it to open audio files, how to read, add and remove tags, and, finally, how use it to read stream information. Here we described only the basic usage of the module: for a complete overview of the available methods and to find how the different audio containers are handled, please take a look at the official documentation.
