Home

Awesome

tinytag

tinytag is a Python library for reading audio file metadata

Build Status Coverage Status PyPI Version PyPI Downloads

Install

python3 -m pip install tinytag

Features

tinytag only provides the minimum needed for reading meta-data. It can determine track number, total tracks, title, artist, album, year, duration and any more.

from tinytag import TinyTag
tag = TinyTag.get('/some/music.mp3')
print('This track is by %s.' % tag.artist)
print('It is %f seconds long.' % tag.duration)

Alternatively you can use tinytag directly on the command line:

$ python -m tinytag --format csv /some/music.mp3
> {"filename": "/some/music.mp3", "filesize": 30212227, "album": "Album", "albumartist": "Artist", "artist": "Artist", "audio_offset": null, "bitrate": 256, "channels": 2, "comment": null, "composer": null, "disc": "1", "disc_total": null, "duration": 10, "genre": null, "samplerate": 44100, "title": "Title", "track": "5", "track_total": null, "year": "2012"}

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

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

TinyTag.SUPPORTED_FILE_EXTENSIONS

Alternatively, check if a file is supported:

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

List of possible attributes you can get with TinyTag:

tag.album         # album as string
tag.albumartist   # album artist as string
tag.artist        # artist name as string
tag.audio_offset  # number of bytes before audio data begins
tag.bitdepth      # bit depth for lossless audio
tag.bitrate       # bitrate in kBits/s
tag.comment       # file comment as string
tag.composer      # composer as string 
tag.disc          # disc number
tag.disc_total    # the total number of discs
tag.duration      # duration of the song in seconds
tag.filesize      # file size in bytes
tag.genre         # genre as string
tag.samplerate    # samples per second
tag.title         # title of the song
tag.track         # track number as string
tag.track_total   # total number of tracks as string
tag.year          # year or date as string

For non-common fields and fields specific to single file formats, use extra:

tag.extra         # a dict of additional data

The extra dict currently may contain the following data: url, isrc, text, initial_key, lyrics, copyright

Additionally you can also get cover images from ID3 tags:

tag = TinyTag.get('/some/music.mp3', image=True)
image_data = tag.get_image()

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

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

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

TinyTag.get(file_obj=your_file_obj)

Changelog

2.0.0 (Unreleased)

1.10.1 (2023-10-26)

1.10.0 (2023-10-18)

1.9.0 (2023-04-23)

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

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

1.7.0. (2021-12-14)

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

1.5.0 (2020-11-05)

1.4.0 (2020-04-23)

1.3.0 (2020-03-09)

1.2.2 (2019-04-13)

1.2.1 (2019-04-13)

1.2.0 (2019-04-13)

1.1.0 (2019-04-13)

1.0.1 (2019-04-13)

1.0.0 (2018-12-12)

0.19.0 (2018-02-11)

0.18.0 (2017-04-29)

0.17.0 (2016-10-02)

0.16.0 (2016-08-06)

0.15.2 (2016-08-06)

0.15.0 (2016-08-06)

0.14.0 (2016-06-05):