Main Module

Mutagen aims to be an all purpose multimedia tagging library.

import mutagen.[format]
metadata = mutagen.[format].Open(filename)

metadata acts like a dictionary of tags in the file. Tags are generally a list of string-like values, but may have additional methods available depending on tag or format. They may also be entirely different objects for certain keys, again depending on format.

mutagen.version = (1, 31)

Version tuple.

mutagen.File(filename, options=None, easy=False)

Guess the type of the file and try to open it.

The file type is decided by several things, such as the first 128 bytes (which usually contains a file type identifier), the filename extension, and the presence of existing tags.

If no appropriate type could be found, None is returned.

Parameters:
  • options – Sequence of FileType implementations, defaults to all included ones.
  • easy – If the easy wrappers should be returnd if available. For example EasyMP3 instead of MP3.
mutagen.version_string = '1.31'

Version string.

Base Classes

class mutagen.text

This type only exists for documentation purposes. It represents unicode under Python 2 and str under Python 3.

class mutagen.FileType(filename)

Bases: mutagen._util.DictMixin

An abstract object wrapping tags and audio stream information.

Attributes:

  • info – stream information (length, bitrate, sample rate)
  • tags – metadata tags, if any

Each file format has different potential tags and stream information.

FileTypes implement an interface very similar to Metadata; the dict interface, save, load, and delete calls on a FileType call the appropriate methods on its tag data.

delete()

Remove tags from a file.

In cases where the tagging format is independent of the file type (for example mutagen.ID3) all traces of the tagging format will be removed. In cases where the tag is part of the file type, all tags and padding will be removed.

The tags attribute will be cleared as well if there is one.

Does nothing if the file has no tags.

Raises mutagen.MutagenError:
 if deleting wasn’t possible
save()

Save metadata tags.

Raises mutagen.MutagenError:
 if saving wasn’t possible
add_tags()

Adds new tags to the file.

Raises mutagen.MutagenError:
 if tags already exist or adding is not possible.
mime

A list of mime types

pprint()

Print stream information and comment key=value pairs.

class mutagen.Metadata(*args, **kwargs)

An abstract dict-like object.

Metadata is the base class for many of the tag objects in Mutagen.

delete()

Remove tags from a file.

In most cases this means any traces of the tag will be removed from the file.

save()

Save changes to a file.

class mutagen.StreamInfo

Abstract stream information object.

Provides attributes for length, bitrate, sample rate etc.

See the implementations for details.

pprint()

Print stream information

class mutagen.PaddingInfo

Abstract padding information object.

This will be passed to the callback function that can be used for saving tags.

def my_callback(info: PaddingInfo):
    return info.get_default_padding()

The callback should return the amount of padding to use (>= 0) based on the content size and the padding of the file after saving. The actual used amount of padding might vary depending on the file format (due to alignment etc.)

The default implementation can be accessed using the get_default_padding() method in the callback.

padding = 0

The amount of padding left after saving in bytes (can be negative if more data needs to be added as padding is available)

size = 0

The amount of data following the padding

get_default_padding()

The default implementation which tries to select a reasonable amount of padding and which might change in future versions.

Returns:Amount of padding after saving
Return type:int
class mutagen.MutagenError

Base class for all custom exceptions in mutagen

New in version 1.25.

Internal Classes

Utility classes for Mutagen.

You should not rely on the interfaces here being stable. They are intended for internal use in Mutagen only.

class mutagen._util.DictMixin

Implement the dict API using keys() and __*item__ methods.

Similar to UserDict.DictMixin, this takes a class that defines __getitem__, __setitem__, __delitem__, and keys(), and turns it into a full dict-like object.

UserDict.DictMixin is not suitable for this purpose because it’s an old-style class.

This class is not optimized for very large dictionaries; many functions have linear memory requirements. I recommend you override some of these functions if speed is required.

class mutagen._util.DictProxy(*args, **kwargs)

Bases: mutagen._util.DictMixin