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, 38)¶ Version tuple.
-
mutagen.
File
(filething, 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: Returns: - A FileType instance for the detected type or
None
in case the type couln’t be determined.
Return type: Raises: MutagenError
– in case the detected type fails to load the file.- A FileType instance for the detected type or
-
mutagen.
version_string
= '1.38'¶ Version string.
Base Classes¶
-
class
mutagen.
FileType
(filething, **kwargs)¶ Bases:
mutagen._util.DictMixin
Parameters: filething (filething) – A filename or a file-like object Subclasses might take further options via keyword arguments.
An abstract object wrapping tags and audio stream information.
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.
-
info
¶ StreamInfo
– contains length, bitrate, sample rate
Adds new tags to the file.
Raises: MutagenError
– if tags already exist or adding is not possible.
-
delete
(filething=None)¶ Remove tags from a file.
In cases where the tagging format is independent of the file type (for example
mutagen.id3.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: MutagenError
– if deleting wasn’t possible
-
save
(filething=None, **kwargs)¶ Save metadata tags.
Raises: MutagenError
– if saving wasn’t possible
-
-
class
mutagen.
Tags
¶ Tags
is the base class for many of the tag objects in Mutagen.In many cases it has a dict like interface.
-
class
mutagen.
Metadata
(filething=None, **kwargs)¶ Bases:
mutagen.Tags
Parameters: filething (filething) – a filename or a file-like object or None
to create an empty instance (likeID3()
)Like
Tags
but for standalone tagging formats that are not solely managed by a container format.Provides methods to load, save and delete tags.
-
delete
(filething=None)¶ Remove tags from a file.
In most cases this means any traces of the tag will be removed from the file.
Parameters: filething (filething) – or None
Raises: MutagenError
– if deleting wasn’t possible
-
save
(filething=None, **kwargs)¶ Save changes to a file.
Parameters: filething (filething) – or None
Raises: MutagenError
– if saving wasn’t possible
-
-
class
mutagen.
StreamInfo
¶ Abstract stream information object.
Provides attributes for length, bitrate, sample rate etc.
See the implementations for details.
-
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.
-
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
Other Classes and Functions¶
-
class
mutagen.
text
¶ This type only exists for documentation purposes. It represents
unicode
under Python 2 andstr
under Python 3.
-
class
mutagen.
bytes
¶ This type only exists for documentation purposes. It represents
str
under Python 2 andbytes
under Python 3.
-
class
mutagen.
fspath
¶ This type only exists for documentation purposes. It represents a file name which can be
str
orunicode
under Python 2 andbytes
orstr
under Python 3.
-
class
mutagen.
fileobj
¶ - This type only exists for documentation purposes. A file-like object.
- See Working with File-like Objects for more information.
-
class
mutagen.
filething
¶ This type only exists for documentation purposes. Either a
fspath
or afileobj
.
-
mutagen.
PaddingFunction
(info)¶ A function you can implement and pass to various
save()
methods for controlling the amount of padding to use. See Tag Padding for more information.Parameters: info (PaddingInfo) – Returns: The amount of padding to use Return type: int