TinyTag Audio Metadata Reader

2.2.1 · active · verified Sat Apr 11

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.

Warnings

breaking In 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`.
breaking Version 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.
deprecated The `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}')`.
gotcha Prior 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.
gotcha Before 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.

Install

pip install tinytag Install latest version

Imports

TinyTag
```
from tinytag import TinyTag
```

Quickstart

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)

view raw JSON →