tinytag

library2.3.0pypypi✓ verified 24d ago

tinytag is a small, fast, and feature-rich Python library for reading audio file metadata from various formats including MP3, OGG, FLAC, M4A, WAV, and WMA. It supports ID3v1, ID3v2, OGG Vorbis, OGG Opus, M4A/MP4, and more. The current version is 2.2.1, and it maintains an active release cadence with regular updates.

serialization data

pip install tinytag

github ↗package ↗

INSTALL

IMPORT

SIG · TINYTAG

tinytag

serializationpythonv2.3.0

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.002s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TinyTag

✓ from tinytag import TinyTag

This quickstart demonstrates how to read metadata from an audio file using TinyTag. It creates a minimal dummy file to ensure the example is runnable, then attempts to extract common tags like artist, title, duration, and bitrate. In a real application, you would replace `dummy_audio_file` with the path to your actual audio file.

import os from tinytag import TinyTag # Create a dummy audio file for demonstration dummy_audio_file = 'example.mp3' with open(dummy_audio_file, 'wb') as f: f.write(b'RIFF\x00\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00\x44\xAC\x00\x00\x88\x58\x01\x00\x02\x00\x10\x00data\x00\x00\x00\x00') try: # In a real scenario, replace 'example.mp3' with your actual audio file path tag = TinyTag.get(dummy_audio_file) print(f"File: {dummy_audio_file}") print(f"Artist: {tag.artist}") print(f"Title: {tag.title}") print(f"Duration: {tag.duration} seconds") print(f"Audio offset: {tag.audio_offset}") print(f"Filesize: {tag.filesize} bytes") print(f"Bitrate: {tag.bitrate} kBit/s") print(f"Genre: {tag.genre}") print(f"Year: {tag.year}") except Exception as e: print(f"Error reading tag: {e}") finally: # Clean up the dummy file if os.path.exists(dummy_audio_file): os.remove(dummy_audio_file)

Debug

Known issues

breakingIn version 2.0.0, the `disc`, `disc_total`, `track`, and `track_total` fields changed from `str` to `int`. Code expecting string values for these fields will fail.

fix

Update your code to expect and handle integer values for `tag.disc`, `tag.disc_total`, `tag.track`, and `tag.track_total`.

affects: >=2.0.0

breakingVersion 2.0.0 changed the behavior of the `as_dict()` method. Values for fields are now returned as lists, even if they contain only a single item.

fix

Adjust your parsing logic for `as_dict()` results to expect list values, e.g., `tag.as_dict()['artist'][0]` instead of `tag.as_dict()['artist']` for single values.

affects: >=2.0.0

deprecatedThe `ignore_errors` parameter for `TinyTag.get()` was deprecated in version 2.0.0. Using this parameter is no longer recommended.

fix

Instead of `TinyTag.get(filepath, ignore_errors=True)`, use a `try...except TinyTagException` block to explicitly handle parsing errors, for example: `from tinytag import TinyTag, TinyTagException; try: tag = TinyTag.get(filepath) except TinyTagException as e: print(f'Error: {e}')`.

affects: >=2.0.0

gotchaPrior to version 2.2.1, malformed ID3v2 Synchronized Lyrics (SYLT) strings could cause an infinite loop during tag parsing, leading to application hangs or crashes.

fix

Upgrade to TinyTag version 2.2.1 or newer to ensure robustness against malformed SYLT data.

affects: <2.2.1

gotchaBefore version 2.1.1, the library incorrectly removed the 'b' character from ID3 string data, leading to corrupted metadata values for certain fields.

fix

Update to TinyTag version 2.1.1 or later to correctly decode ID3 string fields and prevent data corruption.

affects: <2.1.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tinytag'

The 'tinytag' library is not installed in the current Python environment.

fix

pip install tinytag

tinytag.TinyTagException: Can't parse tag.

The provided audio file is either corrupt, not a recognized format, or its metadata is malformed, preventing tinytag from extracting information.

fix

Ensure the audio file is valid and of a supported format (MP3, OGG, FLAC, M4A, WAV, WMA). Wrap TinyTag.get() in a try-except tinytag.TinyTagException block for robust error handling.

AttributeError: 'NoneType' object has no attribute 'lower'

An attempt was made to call a method on an audio tag attribute (e.g., tag.artist) that returned None because the metadata was not present in the file.

fix

Check if the attribute is None before attempting to use it, or provide a default value. Example: artist = tag.artist if tag.artist else 'Unknown Artist'

FileNotFoundError: [Errno 2] No such file or directory: '/path/to/your/audio.mp3'

The specified path to the audio file passed to TinyTag.get() is incorrect or the file does not exist at that location.

fix

Verify the file path is correct and that the audio file exists. Use absolute paths or ensure the file is relative to your script's execution directory.

Upgrade

Version history

2.3.0latest on PyPI · released Jul 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/tinytag/tinytag ↗

packagehttps://pypi.org/project/tinytag/ ↗