# tinytag
tinytag is a library for reading music meta data of most common audio files in pure Python
[](https://github.com/devsnd/tinytag/actions?query=workflow:%22Tests%22)
[](https://ci.appveyor.com/project/devsnd/tinytag)
[](https://coveralls.io/r/devsnd/tinytag)
[](https://pypi.org/project/tinytag/)
[](https://pypistats.org/packages/tinytag)
## Install
```pip install tinytag```
## Features
* Read tags, length and cover images of audio files
* Supported formats:
* MP3 / MP2 / MP1 (ID3 v1, v1.1, v2.2, v2.3+)
* M4A (AAC / ALAC)
* Wave / RIFF
* OGG (FLAC / Opus / Speex / Vorbis)
* FLAC
* WMA
* AIFF / AIFF-C
* Pure Python, no dependencies
* Supports Python 2.7 and 3.6 or higher
* High test coverage
* Just a few hundred lines of code (just include it in your project!)
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
### 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
Raw data
{
"_id": null,
"home_page": "https://github.com/devsnd/tinytag",
"name": "tinytag",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": "",
"keywords": "metadata,music",
"author": "Tom Wallroth",
"author_email": "tomwallroth@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/59/b5/ff5e5f9ca9677be7272260f67c87f7e8e885babc7ce94604e837dcfd8d76/tinytag-1.10.1.tar.gz",
"platform": null,
"description": "# tinytag \n\ntinytag is a library for reading music meta data of most common audio files in pure Python\n\n[](https://github.com/devsnd/tinytag/actions?query=workflow:%22Tests%22)\n[](https://ci.appveyor.com/project/devsnd/tinytag)\n[](https://coveralls.io/r/devsnd/tinytag)\n[](https://pypi.org/project/tinytag/)\n[](https://pypistats.org/packages/tinytag)\n\n\n## Install\n\n```pip install tinytag```\n\n\n## Features\n\n * Read tags, length and cover images of audio files\n * Supported formats:\n * MP3 / MP2 / MP1 (ID3 v1, v1.1, v2.2, v2.3+)\n * M4A (AAC / ALAC)\n * Wave / RIFF\n * OGG (FLAC / Opus / Speex / Vorbis)\n * FLAC\n * WMA\n * AIFF / AIFF-C\n * Pure Python, no dependencies\n * Supports Python 2.7 and 3.6 or higher\n * High test coverage\n * Just a few hundred lines of code (just include it in your project!) \n\ntinytag only provides the minimum needed for _reading_ meta-data.\nIt can determine track number, total tracks, title, artist, album, year, duration and any more.\n\n from tinytag import TinyTag\n tag = TinyTag.get('/some/music.mp3')\n print('This track is by %s.' % tag.artist)\n print('It is %f seconds long.' % tag.duration)\n \nAlternatively you can use tinytag directly on the command line:\n\n $ python -m tinytag --format csv /some/music.mp3\n > {\"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\"}\n\nCheck `python -m tinytag --help` for all CLI options, for example other output formats.\n\nTo receive a list of file extensions tinytag supports, use the `SUPPORTED_FILE_EXTENSIONS` constant:\n\n TinyTag.SUPPORTED_FILE_EXTENSIONS\n\nAlternatively, check if a file is supported:\n\n is_supported = TinyTag.is_supported('/some/music.mp3')\n\nList of possible attributes you can get with TinyTag:\n\n tag.album # album as string\n tag.albumartist # album artist as string\n tag.artist # artist name as string\n tag.audio_offset # number of bytes before audio data begins\n tag.bitdepth # bit depth for lossless audio\n tag.bitrate # bitrate in kBits/s\n tag.comment # file comment as string\n tag.composer # composer as string \n tag.disc # disc number\n tag.disc_total # the total number of discs\n tag.duration # duration of the song in seconds\n tag.filesize # file size in bytes\n tag.genre # genre as string\n tag.samplerate # samples per second\n tag.title # title of the song\n tag.track # track number as string\n tag.track_total # total number of tracks as string\n tag.year # year or date as string\n\nFor non-common fields and fields specific to single file formats, use `extra`:\n\n tag.extra # a dict of additional data\n\nThe `extra` dict currently *may* contain the following data:\n `url`, `isrc`, `text`, `initial_key`, `lyrics`, `copyright`\n\nAdditionally you can also get cover images from ID3 tags:\n\n tag = TinyTag.get('/some/music.mp3', image=True)\n image_data = tag.get_image()\n\nTo open files using a specific encoding, you can use the `encoding` parameter.\nThis parameter is however only used for formats where the encoding isn't explicitly\nspecified.\n\n TinyTag.get('a_file_with_gbk_encoding.mp3', encoding='gbk')\n\nTo use a file-like object (e.g. BytesIO) instead of a file path, pass a\n`file_obj` keyword argument:\n\n TinyTag.get(file_obj=your_file_obj)\n\n\n## Changelog\n\n### 1.10.1 (2023-10-26)\n\n- Update 'extra' fields with data from other tags #188\n- ID3: Add missing 'extra.copyright' field\n\n### 1.10.0 (2023-10-18)\n\n- Add support for OGG FLAC format #182\n- Add support for OGG Speex format #181\n- Wave: support image loading\n- Add support for file-like objects (BytesIO) #178\n- Add list of supported file extensions #177\n- Fix deprecations related to setuptools #176\n- Fix pathlib support in TinyTag.is_supported()\n- Only remove zero bytes at the end of strings\n- Stricter conditions in while loops\n- OGG: Add stricter magic byte matching for OGG files\n- Compatibility with Python 3.4 and 3.5 is no longer tested\n\n### 1.9.0 (2023-04-23)\n\n- Add bitdepth attribute for lossless audio #157\n- Add recognition of Audible formats #163 (thanks to snowskeleton)\n- Add .m4v to list of supported file extensions #142\n- Aiff: Implement replacement for Python's aifc module #164\n- ID3: Only check for language in COMM and USLT frames #147\n- ID3: Read the correct number of bytes from Xing header #154\n- ID3: Add support for ID3v2.4 TDRC frame #156 (thanks to Uninen)\n- M4A: Add description fields #168 (thanks to snowskeleton)\n- RIFF: Handle tags containing extra zero-byte #141\n- Vorbis: Parse OGG cover art #144 (thanks to Pseurae)\n- Vorbis: Support standard disctotal/tracktotal comments #171\n- Wave: Add proper support for padded IFF chunks\n\n### 1.8.1 (2022-03-12) [still mathiascode-edition]\n\n- MP3 ID3: Set correct file position if tag reading is disabled #119 (thanks to mathiascode)\n- MP3: Fix incorrect calculation of duration for VBR encoded MP3s #128 (thanks to mathiascode)\n\n### 1.8.0 (2022-03-05) [mathiascode-edition]\n\n- Add support for ALAC audio files #130 (thanks to mathiascode)\n- AIFF: Fixed bitrate calculation for certain files #129 (thanks to mathiascode)\n- MP3: Do not round MP3 bitrates #131 (thanks to mathiascode)\n- MP3 ID3: Support any language in COMM and USLT frames #135 (thanks to mathiascode)\n- Performance: Don't use regex when parsing genre #136 (thanks to mathiascode)\n- Disable tag parsing for all formats when requested #137 (thanks to mathiascode)\n- M4A: Fix invalid bitrates in certain files #132 (thanks to mathiascode)\n- WAV: Fix metadata parsing for certain files #133 (thanks to mathiascode)\n\n### 1.7.0. (2021-12-14)\n\n- fixed rare occasion of ID3v2 tags missing their first character, #106\n- allow overriding the default encoding of ID3 tags (e.g. `TinyTag.get(..., encoding='gbk'))`)\n- fixed calculation of bitrate for very short mp3 files, #99\n- utf-8 support for AIFF files, #123\n- fixed image parsing for id3v2 with images containing utf-16LE descriptions, #117\n- fixed ID3v1 tags overwriting ID3v2 tags, #121\n- Set correct file position if tag reading is disabled for ID3 (thanks to mathiascode)\n\n### 1.6.0 (2021-08-28) [aw-edition]\n\n- fixed handling of non-latin encoding types for images (thanks to aw-was-here)\n- added support for ISRC data, available in `extra['isrc']` field (thanks to aw-was-here)\n- added support for AIFF/AIFF-C (thanks to aw-was-here)\n- fixed import deprecation warnings (thanks to idotobi)\n- fixed exception for TinyTag misuse being different in different python versions (thanks to idotobi)\n- added support for ID3 initial key tonality hint, available in `extra['initial_key']`\n- added support for ID3 unsynchronized lyrics, available in `extra['lyrics']`\n- added `extra` field, which may contain additional metadata not available in all file formats\n\n### 1.5.0 (2020-11-05)\n\n- fixed data type to always return str for disc, disc_total, track, track_total #97 (thanks to kostalski)\n- fixed package install being reported as UNKNOWN for some python/pip variations #90 (thanks to russpoutine)\n- Added automatic detection for certain MP4 file headers\n\n### 1.4.0 (2020-04-23)\n\n- detecting file types based on their magic header bytes, #85\n- fixed opus duration being wrong for files with lower sample rate #81\n- implemented support for binary paths #72\n- always cast mp3 bitrates to int, so that CBR and VBR output behaves the sam\n- made __str__ deterministic and use json as output format\n\n### 1.3.0 (2020-03-09)\n\n- added option to ignore encoding errors `ignore_errors` #73\n- Improved text decoding for many malformed files\n\n### 1.2.2 (2019-04-13)\n\n- Improved stability when reading corrupted mp3 files\n\n### 1.2.1 (2019-04-13)\n\n- fixed wav files not correctly reporting the number of channels #61\n\n### 1.2.0 (2019-04-13)\n\n- using setup.cfg instead of setup.py (thanks to scivision)\n- added support for calling TinyTag.get with pathlib.Path (thanks to scivision)\n- added appveyor windows test CI (thanks to scivision)\n- using pytest instead of nosetest (thanks to scivision)\n\n### 1.1.0 (2019-04-13)\n\n- added new field \"composer\" (Thanks to Phil Borman)\n\n### 1.0.1 (2019-04-13)\n\n- fixed ID3 loading for files with corrupt header (thanks to Ian Homer)\n- fixed parsing of duration in wav file (thanks to Ian Homer)\n\n### 1.0.0 (2018-12-12)\n\n- added comment field\n- added wav-riff format support\n- use MP4 parser for m4b files\n- added simple cli tool\n- fix parsing of FLAC files with ID3 header (thanks to minus7)\n- added method `TinyTag.is_supported(filename)`\n\n### 0.19.0 (2018-02-11)\n\n- fixed corrupted images for some mp3s (#45)\n\n### 0.18.0 (2017-04-29)\n\n- fixed wrong bitrate and crash when parsing xing header\n\n### 0.17.0 (2016-10-02)\n\n- supporting ID3v2.2 images\n\n### 0.16.0 (2016-08-06)\n\n- MP4 cover image support\n\n### 0.15.2 (2016-08-06)\n\n- fixed crash for malformed MP4 files (#34)\n\n### 0.15.0 (2016-08-06)\n\n- fixed decoding of UTF-16LE ID3v2 Tags, improved overall stability\n\n### 0.14.0 (2016-06-05):\n\n- MP4/M4A and Opus support\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Read music meta data and length of MP3, OGG, OPUS, MP4, M4A, FLAC, WMA and Wave files",
"version": "1.10.1",
"project_urls": {
"Homepage": "https://github.com/devsnd/tinytag"
},
"split_keywords": [
"metadata",
"music"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f04ef783cbc4aa3a5ed75969e300b3e3929daf3d1b52fe80e950c63e0d66d95",
"md5": "14505e307689f717b3b4197be4b465ee",
"sha256": "e437654d04c966fbbbdbf807af61eb9759f1d80e4173a7d26202506b37cfdaf0"
},
"downloads": -1,
"filename": "tinytag-1.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14505e307689f717b3b4197be4b465ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=2.7",
"size": 37900,
"upload_time": "2023-10-26T19:30:36",
"upload_time_iso_8601": "2023-10-26T19:30:36.724564Z",
"url": "https://files.pythonhosted.org/packages/2f/04/ef783cbc4aa3a5ed75969e300b3e3929daf3d1b52fe80e950c63e0d66d95/tinytag-1.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59b5ff5e5f9ca9677be7272260f67c87f7e8e885babc7ce94604e837dcfd8d76",
"md5": "bb2617566457cfb229f8e5d303a78c29",
"sha256": "122a63b836f85094aacca43fc807aaee3290be3de17d134f5f4a08b509ae268f"
},
"downloads": -1,
"filename": "tinytag-1.10.1.tar.gz",
"has_sig": false,
"md5_digest": "bb2617566457cfb229f8e5d303a78c29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 40906,
"upload_time": "2023-10-26T19:30:38",
"upload_time_iso_8601": "2023-10-26T19:30:38.791475Z",
"url": "https://files.pythonhosted.org/packages/59/b5/ff5e5f9ca9677be7272260f67c87f7e8e885babc7ce94604e837dcfd8d76/tinytag-1.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-26 19:30:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "devsnd",
"github_project": "tinytag",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"appveyor": true,
"lcname": "tinytag"
}
JSON
