Metadata-Version: 2.4
Name: tinytag
Version: 1.10.1
Summary: Read music meta data and length of MP3, OGG, OPUS, MP4, M4A, FLAC, WMA and Wave files
Home-page: https://github.com/devsnd/tinytag
Author: Tom Wallroth
Author-email: tomwallroth@gmail.com
License: MIT
Keywords: metadata,music
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=2.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: flake8; extra == "tests"
Dynamic: license-file

# tinytag 

tinytag is a library for reading music meta data of most common audio files in pure Python

[![Build Status](https://github.com/devsnd/tinytag/actions/workflows/tests.yml/badge.svg)](https://github.com/devsnd/tinytag/actions?query=workflow:%22Tests%22)
[![Build status](https://ci.appveyor.com/api/projects/status/w9y2kg97869g1edj?svg=true)](https://ci.appveyor.com/project/devsnd/tinytag)
[![Coverage Status](https://coveralls.io/repos/devsnd/tinytag/badge.svg)](https://coveralls.io/r/devsnd/tinytag)
[![PyPI version](https://badge.fury.io/py/tinytag.svg)](https://pypi.org/project/tinytag/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/tinytag.svg)](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
