tinytag

tinytag is a Python library for reading audio file metadata

Install

python3 -m pip install tinytag

Features

Read tags, images and properties of audio files
Supported formats:
- ID3 v1, v1.1, v2.2, v2.3, v2.4
- MP3 / MP2 / MP1
- MP4 (MPEG-4 Audio / AAC / ALAC)
- WAVE / WAV
- OGG (FLAC / Opus / Speex / Vorbis)
- FLAC
- ASF (WMA)
- AIFF / AIFF-C
Same API for all formats
Small, portable library
High code coverage
Pure Python, no dependencies
Supports Python 3.7 or higher

Important

Support for changing/writing metadata will not be added. Use another library such as Mutagen or pytaglib for this.

Usage

tinytag only provides the minimum needed for reading metadata, and presents it in a simple format. It can determine track number, total tracks, title, artist, album, year, duration and more.

from tinytag import TinyTag
tag: TinyTag = TinyTag.get('/some/music.mp3')

print(f'This track is by {tag.artist}.')
print(f'It is {tag.duration:.2f} seconds long.')

Warning

The ignore_errors parameter of TinyTag.get() is obsolete as of tinytag 2.0.0, and will be removed in the future.

Alternatively you can use tinytag directly on the command line:

$ python3 -m tinytag /some/music.mp3
{
  "filename": "/some/music.mp3",
  "filesize": 3243226,
  "mime_type": "audio/mpeg",
  "is_lossless": false,
  "duration": 173.52,
  "channels": 2,
  "bitrate": 128,
  "samplerate": 44100,
  "artist": [
    "artist name"
  ],
  "album": [
    "album name"
  ],
  "title": [
    "track name"
  ],
  "track": [
    "4"
  ],
  "genre": [
    "Jazz"
  ],
  "year": [
    "2010"
  ],
  "comment": [
    "Some comment here"
  ]
}

Check python3 -m tinytag --help for all CLI options, for example other output formats.

Supported Files

To receive a tuple of file extensions tinytag supports, use the SUPPORTED_FILE_EXTENSIONS constant:

TinyTag.SUPPORTED_FILE_EXTENSIONS

Alternatively, check if a file is supported by providing its path:

is_supported = TinyTag.is_supported('/some/music.mp3')

Common Metadata

tinytag provides some common attributes, which always contain a single value. These are helpful when you need quick access to common metadata.

File/Audio Properties

tag.filename: str | None         # file name
tag.filesize: int                # file size in bytes
tag.bitdepth: int | None         # audio bit depth
tag.bitrate: float | None        # audio bitrate in kbps
tag.channels: int | None         # number of audio channels
tag.duration: float | None       # audio duration in seconds
tag.is_lossless: bool | None     # is audio lossless? (added in tinytag 2.3.0)
tag.mime_type: str | None        # audio MIME type (added in tinytag 2.3.0) 
tag.samplerate: int | None       # audio samples per second

Warning

The tag.audio_offset attribute is obsolete as of tinytag 2.0.0, and will be removed in the future.

Metadata Fields

tag.album: str | None            # album name
tag.albumartist: str | None      # album artist name
tag.artist: str | None           # artist name
tag.comment: str | None          # file comment
tag.composer: str | None         # composer name
tag.disc: int | None             # disc number
tag.disc_total: int | None       # total number of discs
tag.genre: str | None            # genre
tag.title: str | None            # title
tag.track: int | None            # track number
tag.track_total: int | None      # total number of tracks
tag.year: str | None             # year/date

Audio MIME Types

At present, tinytag may return the audio MIME types documented in this section. When available, a codecs parameter as described in the RFC 6381 standard is included.

For standard codec values, see:

No official standards exists for codecs values for the application/vnd.ms-asf and audio/aiff MIME types. The most appropriate value provided by the format is used.

# ASF
application/vnd.ms-asf
application/vnd.ms-asf; codecs="<1..>"  # WAVE format tag, e.g. "161" (WMA)

# AIFF
audio/aiff
audio/aiff; codecs="<FourCC>"  # AIFF-C compression type, e.g. "alaw"

# FLAC
audio/flac

# MP4
audio/mp4
audio/mp4; codecs="alac"
audio/mp4; codecs="mp4a.oo[.A]"  # E.g. "mp4a.40.2" for AAC-LC

# MP3 / MP2 / MP1
audio/mpeg

# OGG
audio/ogg
audio/ogg; codecs="flac"
audio/ogg; codecs="opus"
audio/ogg; codecs="speex"
audio/ogg; codecs="vorbis"

# WAV
audio/wav
audio/wav; codecs="<1..>"  # WAVE format tag, e.g. "1" for PCM

Additional Metadata

For additional values of the same field type, uncommon metadata fields, or metadata specific to certain file formats, use other:

tag.other: OtherFields           # a dictionary of additional fields

Warning

The other dictionary has replaced the extra dictionary in tinytag 2.0.0. The latter will be removed in a future release.

The following other field names are standardized in tinytag, and optionally present when files provide such metadata:

barcode
bpm
catalog_number
conductor
copyright
director
encoded_by
encoder_settings
grouping
initial_key
isrc
language
license
lyricist
lyrics
media
movement
movement_name
movement_total
publisher
set_subtitle
show_movement
url
work
xmp

Additional other field names not documented above may be present, but are format-specific and may change or disappear in future tinytag releases. If tinytag does not expose metadata you need, or you wish to standardize more field names, open a feature request on GitHub for discussion.

other values are always provided as strings, and are not guaranteed to be valid. Should e.g. the bpm value in the file contain non-numeric characters, tinytag will provide the string as-is. It is your responsibility to handle possible exceptions, e.g. when converting the value to an integer.

Multiple values of the same field type are provided if a file contains them. Values are always provided as a list, even when only a single value exists.

Example:

from tinytag import OtherFields, TinyTag

tag: TinyTag = TinyTag.get('/some/music.mp3')
other_fields: OtherFields = tag.other
catalog_numbers: list[str] | None = other_fields.get('catalog_number')

if catalog_numbers:
    catalog_number: str = catalog_numbers[0]
    print(catalog_number)

print(catalog_numbers)

Output:

> 10
> ['10']

When a file contains multiple values for a common metadata field (e.g. artist), the primary value is accessed through the common attribute (tag.artist), and any additional values through the other dictionary (tag.other['artist']).

Example:

from tinytag import TinyTag

tag: TinyTag = TinyTag.get('/some/music.mp3')
artist: str | None = tag.artist
additional_artists: list[str] | None = tag.other.get('artist')

print(artist)
print(additional_artists)

Output:

> main artist
> ['another artist', 'yet another artist']

All Metadata

If you need to receive all available metadata as key-value pairs in a flat dictionary, use the as_dict() method. This combines the common attributes and other dictionary, which can be more convenient in some cases.

from tinytag import TinyTag

tag: TinyTag = TinyTag.get('/some/music.mp3')
metadata: dict = tag.as_dict()

Images

Additionally, you can also read embedded images by passing a image=True keyword argument to TinyTag.get().

If you need to receive an image of a specific kind, including its description, use images:

tag.images: Images             # available embedded images

The following common image attributes are available, providing the first located Image object of each kind:

tag.images.front_cover: Image  # front cover
tag.images.back_cover: Image   # back cover
tag.images.media: Image        # media (e.g. CD label)

When present, any additional images are available in an images.other dictionary, using the following standardized key names:

generic
icon
alt_icon
front_cover
back_cover
media
leaflet
lead_artist
artist
conductor
band
composer
lyricist
recording_location
during_recording
during_performance
screen_capture
bright_colored_fish
illustration
band_logo
publisher_logo
unknown

Provided values are always lists containing at least one Image object.

The Image object provides the following attributes:

image.data: bytes               # image data
image.size: int                 # image size in bytes (added in tinytag 2.3.0) 
image.name: str                 # image name/kind
image.mime_type: str | None     # image MIME type
image.description: str | None   # image description

To receive any available image, prioritizing the front cover, use images.any:

from tinytag import Image, TinyTag

tag: TinyTag = TinyTag.get('/some/music.ogg', image=True)
image: Image | None = tag.images.any

if image is not None:
    data: bytes = image.data
    size: int = image.size
    name: str = image.name
    mime_type: str | None = image.mime_type
    description: str | None = image.description

    print(len(data))
    print(size)
    print(name)
    print(mime_type)
    print(description)

Output:

> 74452
> 74452
> front_cover
> image/jpeg
> some image description

Warning

tag.images.any has replaced tag.get_image() in tinytag 2.0.0. tag.get_image() will be removed in the future.

To receive a common image, e.g. front_cover:

from tinytag import Image, Images, TinyTag

tag: TinyTag = TinyTag.get('/some/music.ogg', image=True)
images: Images = tag.images
cover_image: Image = images.front_cover

if cover_image is not None:
    data: bytes = cover_image.data
    description: str | None = cover_image.description

To receive an additional image, e.g. bright_colored_fish:

from tinytag import Image, OtherImages, TinyTag

tag: TinyTag = TinyTag.get('/some/music.ogg', image=True)
other_images: OtherImages = tag.images.other
fish_images: list[Image] | None = other_images.get('bright_colored_fish')

if fish_images:
    image = fish_images[0]  # Use first image
    data = image.data
    description = image.description

Magic Byte Detection

By default, tinytag will determine the file type by 1. checking the file name extension, and 2. reading and inspecting magic bytes in the file header.

In case you want to disable magic byte detection, e.g. to minimize read operations when many non-audio files exist in a folder, pass a check_magic_bytes argument with a value of False (added in tinytag 2.3.0).

tag: TinyTag = TinyTag.get('invalid_file.jpg', check_magic_bytes=False)

Encoding

To open files using a specific encoding, you can use the encoding parameter. This parameter is however only used for formats where the encoding is not explicitly specified.

tag: TinyTag = TinyTag.get('a_file_with_gbk_encoding.mp3', encoding='gbk')

File-like Objects

To use a file-like object (e.g. BytesIO) instead of a file path, pass a file_obj keyword argument:

tag: TinyTag = TinyTag.get(file_obj=your_file_obj)

Exceptions

TinyTagException        # Base class for exceptions
ParseError              # Parsing an audio file failed
UnsupportedFormatError  # File format is not supported

Changelog

2.3.2 (2026-09-07)

ID3: Optimize parsing of UTF-16 strings
MP4: Only parse decoder specific info if it exists
ASF: Decode strings as UTF-16LE instead of system byte order

2.3.1 (2026-08-30)

Don't open unrecognized files when disabling magic byte detection
MPEG: Fix parsing of some files with incorrect headers
OGG/WAV: Read sizes as little endian instead of native byte order

2.3.0 (2026-07-31)

Add 'mime_type' attribute for audio MIME type/codec
Add 'is_lossless' attribute to indicate lossless audio
Add 'size' attribute to images for size in bytes
Add option to disable magic byte detection
Make XMP metadata available under 'other.xmp' field
Make bit depth available for lossy files providing it
Add .asf, .ogv and .wmv to list of supported file extensions
Mark deprecated 'extra' dictionary as obsolete
Fix incorrect key when adding common images to 'other' dictionary
Fix disc/track numbers not being returned as lists in 'as_dict()'
Only set audio properties with a positive value
Always read tags and audio properties in a single pass
ID3: Parse multi-value text frames correctly
ID3: Parse COMM and USLT frames correctly
ID3: Fix some errors in parsed size calculations
ID3: Exclude a few frames with custom structures
MPEG: Read VBRI and Xing Info headers for duration/bitrate
MPEG: Fix parsing of layer I and MPEG-2 layer III audio properties
MPEG: Fix slightly incorrect duration estimation
MPEG/MP4: Raise ParseError if header is invalid
MP4: Add 'image/bmp' and 'image/gif' MIME types
MP4: Fix infinite loop if size of certain sub-atoms is zero
MP4: Fix incorrect parsing of descriptor size
MP4: Don't read image data when image reading is disabled
OGG: Parse multi-stream files correctly
Speex: Don't read vendor string as comment
FLAC: Provide actual audio bitrate instead of overall bitrate
FLAC: Parse VORBIS_COMMENT and PICTURE blocks with invalid size
FLAC: Ignore subsequent STREAMINFO blocks
WAV: Include unknown fields in 'other' dictionary
WAV: Calculate bitrate/duration correctly
AIFF/WAV: Read whole ID3 chunk before parsing
ASF: Support parsing additional metadata objects
ASF: Stop parsing if object size is smaller than header
ASF: Make magic header detection more strict
Various performance improvements
Various code refactors

2.2.1 (2026-03-15)

ID3: Prevent infinite loop due to malformed SYLT strings

2.2.0 (2025-12-15)

Add support for movement, work and grouping fields
ID3: Make synced lyrics available in 'other.lyrics' (LRC format)
ID3: Continue reading after encountering empty frame
ID3: Fix frame reading when image parsing is disabled
ID3: Exclude more frames containing binary data
ID3: Avoid unnecessary string decoding
M4A: Support extended atom sizes
M4A: Ensure all field names are lowercase
OGG: Stop reading after reaching EOS page
Vorbis: Map UNSYNCEDLYRICS field to other.lyrics

2.1.2 (2025-08-14)

M4A: Add a few missing additional metadata fields
M4A: Support '©com' composer atom
M4A: Fix reading of multi-value custom fields
M4A: Use correct encoding when reading data names
ID3: Don't read entire file to determine duration
ID3: Skip stray null byte before image data
Add missing __version__ attribute
Avoid some unnecessary work in hot code paths
Improve a few incomplete type hints

2.1.1 (2025-04-23)

ID3: Stop removing 'b' character from strings
Port unit tests from pytest to built-in unittest module

2.1.0 (2025-02-23)

Opus: Calculate audio bitrate
Opus: Take pre-skip into account when calculating the duration

2.0.0 (2024-11-03)

BREAKING: Store 'disc', 'disc_total', 'track' and 'track_total' values as int instead of str
BREAKING: 'as_dict()' method (previously undocumented) returns tag field values in list form
BREAKING: TinyTagException no longer inherits LookupError
BREAKING: TinyTag subclasses are now private
BREAKING: Remove function to use custom audio file samples in tests
BREAKING: Remove support for Python 2
DEPRECATION: Mark 'ignore_errors' parameter for TinyTag.get() as obsolete
DEPRECATION: Mark 'audio_offset' attribute as obsolete
DEPRECATION: Deprecate 'extra' dict in favor of 'other' dict with values in list form
DEPRECATION: Deprecate 'get_image()' method in favor of 'images.any' property
Add type hints to codebase
Provide access to custom metadata fields through the 'other' dict
Provide access to all available images
Add more standard 'other' fields
Use Flit as Python build backend instead of Setuptools
ID3: Fix invalid sample rate/duration in some cases
ID3: Fix reading of UTF-16 strings without BOM
FLAC: Apply ID3 tags after Vorbis
OGG/WMA: Set missing 'channels' field
WMA: Set missing 'other.copyright' field
WMA: Raise exception if file is invalid
Various optimizations

1.10.1 (2023-10-26)

Update 'extra' fields with data from other tags #188
ID3: Add missing 'extra.copyright' field

1.10.0 (2023-10-18)

Add support for OGG FLAC format #182
Add support for OGG Speex format #181
Wave: support image loading
Add support for file-like objects (BytesIO) #178
Add list of supported file extensions #177
Fix deprecations related to setuptools #176
Fix pathlib support in TinyTag.is_supported()
Only remove zero bytes at the end of strings
Stricter conditions in while loops
OGG: Add stricter magic byte matching for OGG files
Compatibility with Python 3.4 and 3.5 is no longer tested

1.9.0 (2023-04-23)

Add bitdepth attribute for lossless audio #157
Add recognition of Audible formats #163 (thanks to snowskeleton)
Add .m4v to list of supported file extensions #142
Aiff: Implement replacement for Python's aifc module #164
ID3: Only check for language in COMM and USLT frames #147
ID3: Read the correct number of bytes from Xing header #154
ID3: Add support for ID3v2.4 TDRC frame #156 (thanks to Uninen)
M4A: Add description fields #168 (thanks to snowskeleton)
RIFF: Handle tags containing extra zero-byte #141
Vorbis: Parse OGG cover art #144 (thanks to Pseurae)
Vorbis: Support standard disctotal/tracktotal comments #171
Wave: Add proper support for padded IFF chunks

1.8.1 (2022-03-12) [still mathiascode-edition]

MP3 ID3: Set correct file position if tag reading is disabled #119 (thanks to mathiascode)
MP3: Fix incorrect calculation of duration for VBR encoded MP3s #128 (thanks to mathiascode)

1.8.0 (2022-03-05) [mathiascode-edition]

Add support for ALAC audio files #130 (thanks to mathiascode)
AIFF: Fixed bitrate calculation for certain files #129 (thanks to mathiascode)
MP3: Do not round MP3 bitrates #131 (thanks to mathiascode)
MP3 ID3: Support any language in COMM and USLT frames #135 (thanks to mathiascode)
Performance: Don't use regex when parsing genre #136 (thanks to mathiascode)
Disable tag parsing for all formats when requested #137 (thanks to mathiascode)
M4A: Fix invalid bitrates in certain files #132 (thanks to mathiascode)
WAV: Fix metadata parsing for certain files #133 (thanks to mathiascode)

1.7.0. (2021-12-14)

fixed rare occasion of ID3v2 tags missing their first character, #106
allow overriding the default encoding of ID3 tags (e.g. TinyTag.get(..., encoding='gbk')))
fixed calculation of bitrate for very short mp3 files, #99
utf-8 support for AIFF files, #123
fixed image parsing for id3v2 with images containing utf-16LE descriptions, #117
fixed ID3v1 tags overwriting ID3v2 tags, #121
Set correct file position if tag reading is disabled for ID3 (thanks to mathiascode)

1.6.0 (2021-08-28) [aw-edition]

fixed handling of non-latin encoding types for images (thanks to aw-was-here)
added support for ISRC data, available in extra['isrc'] field (thanks to aw-was-here)
added support for AIFF/AIFF-C (thanks to aw-was-here)
fixed import deprecation warnings (thanks to idotobi)
fixed exception for TinyTag misuse being different in different python versions (thanks to idotobi)
added support for ID3 initial key tonality hint, available in extra['initial_key']
added support for ID3 unsynchronized lyrics, available in extra['lyrics']
added extra field, which may contain additional metadata not available in all file formats

1.5.0 (2020-11-05)

fixed data type to always return str for disc, disc_total, track, track_total #97 (thanks to kostalski)
fixed package install being reported as UNKNOWN for some python/pip variations #90 (thanks to russpoutine)
Added automatic detection for certain MP4 file headers

1.4.0 (2020-04-23)

detecting file types based on their magic header bytes, #85
fixed opus duration being wrong for files with lower sample rate #81
implemented support for binary paths #72
always cast mp3 bitrates to int, so that CBR and VBR output behaves the sam
made str deterministic and use json as output format

1.3.0 (2020-03-09)

added option to ignore encoding errors ignore_errors #73
Improved text decoding for many malformed files

1.2.2 (2019-04-13)

Improved stability when reading corrupted mp3 files

1.2.1 (2019-04-13)

fixed wav files not correctly reporting the number of channels #61

1.2.0 (2019-04-13)

using setup.cfg instead of setup.py (thanks to scivision)
added support for calling TinyTag.get with pathlib.Path (thanks to scivision)
added appveyor windows test CI (thanks to scivision)
using pytest instead of nosetest (thanks to scivision)

1.1.0 (2019-04-13)

added new field "composer" (Thanks to Phil Borman)

1.0.1 (2019-04-13)

fixed ID3 loading for files with corrupt header (thanks to Ian Homer)
fixed parsing of duration in wav file (thanks to Ian Homer)

1.0.0 (2018-12-12)

added comment field
added wav-riff format support
use MP4 parser for m4b files
added simple cli tool
fix parsing of FLAC files with ID3 header (thanks to minus7)
added method TinyTag.is_supported(filename)

0.19.0 (2018-02-11)

fixed corrupted images for some mp3s (#45)

0.18.0 (2017-04-29)

fixed wrong bitrate and crash when parsing xing header

0.17.0 (2016-10-02)

supporting ID3v2.2 images

0.16.0 (2016-08-06)

MP4 cover image support

0.15.2 (2016-08-06)

fixed crash for malformed MP4 files (#34)

0.15.0 (2016-08-06)

fixed decoding of UTF-16LE ID3v2 Tags, improved overall stability

0.14.0 (2016-06-05)

MP4/M4A and Opus support

Latest commit

History