tinytag 2.2.0__tar.gz → 2.3.0__tar.gz

{tinytag-2.2.0 → tinytag-2.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2025 Tom Wallroth, Mat (mathiascode), et al.
+Copyright (c) 2014-2026 Tom Wallroth, Mat (mathiascode), et al.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{tinytag-2.2.0 → tinytag-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinytag
-Version: 2.2.0
+Version: 2.3.0
 Summary: Read audio file metadata
 Keywords: metadata,audio,music,mp3,m4a,wav,ogg,opus,flac,wma,aiff
 Author: Tom Wallroth, Mat (mathiascode)
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 4 - Resilient
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
@@ -37,7 +38,7 @@ Project-URL: Homepage, https://github.com/tinytag/tinytag
 Provides-Extra: tests
 
 <!--
-  SPDX-FileCopyrightText: 2014-2024 tinytag Contributors
+  SPDX-FileCopyrightText: 2014-2026 tinytag Contributors
   SPDX-License-Identifier: MIT
 -->
 
@@ -64,12 +65,13 @@ python3 -m pip install tinytag
 
   * Read tags, images and properties of audio files
   * Supported formats:
-    * MP3 / MP2 / MP1 (ID3 v1, v1.1, v2.2, v2.3+)
-    * M4A (AAC / ALAC)
+    * ID3 v1, v1.1, v2.2, v2.3, v2.4
+    * MP3 / MP2 / MP1
+    * MP4 (MPEG-4 Audio / AAC / ALAC)
     * WAVE / WAV
     * OGG (FLAC / Opus / Speex / Vorbis)
     * FLAC
-    * WMA
+    * ASF (WMA)
     * AIFF / AIFF-C
   * Same API for all formats
   * Small, portable library
@@ -79,7 +81,8 @@ python3 -m pip install tinytag
 
 > [!IMPORTANT]  
 > Support for changing/writing metadata will not be added. Use another library
-> such as [Mutagen](https://mutagen.readthedocs.io/) for this.
+> such as [Mutagen](https://mutagen.readthedocs.io/) or [pytaglib](https://github.com/supermihi/pytaglib)
+> for this.
 
 
 ## Usage
@@ -102,34 +105,40 @@ print(f'It is {tag.duration:.2f} seconds long.')
 
 Alternatively you can use tinytag directly on the command line:
 
-    $ python3 -m tinytag /some/music.mp3
-    {
-      "filename": "/some/music.mp3",
-      "filesize": 3243226,
-      "duration": 173.52,
-      "channels": 2,
-      "bitrate": 128,
-      "samplerate": 44100,
-      "artist": [
-        "artist name"
-      ],
-      "album": [
-        "album name"
-      ],
-      "title": [
-        "track name"
-      ],
-      "track": 4,
-      "genre": [
-        "Jazz"
-      ],
-      "year": [
-        "2010"
-      ],
-      "comment": [
-        "Some comment here"
-      ]
-    }
+```console
+$ python3 -m tinytag /some/music.mp3
+{
+  "filename": "/some/music.mp3",
+  "filesize": 3243226,
+  "mime_type": "audio/mpeg",
+  "is_lossless": false,
+  "duration": 173.52,
+  "channels": 2,
+  "bitrate": 128,
+  "samplerate": 44100,
+  "artist": [
+    "artist name"
+  ],
+  "album": [
+    "album name"
+  ],
+  "title": [
+    "track name"
+  ],
+  "track": [
+    "4"
+  ],
+  "genre": [
+    "Jazz"
+  ],
+  "year": [
+    "2010"
+  ],
+  "comment": [
+    "Some comment here"
+  ]
+}
+```
 
 Check `python3 -m tinytag --help` for all CLI options, for example other
 output formats.
@@ -156,12 +165,17 @@ These are helpful when you need quick access to common metadata.
 
 #### File/Audio Properties
 
-    tag.bitdepth      # bit depth as integer (for lossless audio)
-    tag.bitrate       # bitrate in kBits/s as float
-    tag.duration      # audio duration in seconds as float
-    tag.filename      # filename as string
-    tag.filesize      # file size in bytes as integer
-    tag.samplerate    # samples per second as integer
+```python
+tag.filename: str | None         # file name
+tag.filesize: int                # file size in bytes
+tag.bitdepth: int | None         # audio bit depth
+tag.bitrate: float | None        # audio bitrate in kbps
+tag.channels: int | None         # number of audio channels
+tag.duration: float | None       # audio duration in seconds
+tag.is_lossless: bool | None     # is audio lossless? (added in tinytag 2.3.0)
+tag.mime_type: str | None        # audio MIME type (added in tinytag 2.3.0) 
+tag.samplerate: int | None       # audio samples per second
+```
 
 > [!WARNING]  
 > The `tag.audio_offset` attribute is obsolete as of tinytag 2.0.0, and will
@@ -169,25 +183,75 @@ These are helpful when you need quick access to common metadata.
 
 #### Metadata Fields
 
-    tag.album         # album as string
-    tag.albumartist   # album artist as string
-    tag.artist        # artist name as string
-    tag.comment       # file comment as string
-    tag.composer      # composer as string
-    tag.disc          # disc number as integer
-    tag.disc_total    # total number of discs as integer
-    tag.genre         # genre as string
-    tag.title         # title of the song as string
-    tag.track         # track number as integer
-    tag.track_total   # total number of tracks as integer
-    tag.year          # year or date as string
+```python
+tag.album: str | None            # album name
+tag.albumartist: str | None      # album artist name
+tag.artist: str | None           # artist name
+tag.comment: str | None          # file comment
+tag.composer: str | None         # composer name
+tag.disc: int | None             # disc number
+tag.disc_total: int | None       # total number of discs
+tag.genre: str | None            # genre
+tag.title: str | None            # title
+tag.track: int | None            # track number
+tag.track_total: int | None      # total number of tracks
+tag.year: str | None             # year/date
+```
+
+#### Audio MIME Types
+
+At present, tinytag may return the audio MIME types documented in this section.
+When available, a `codecs` parameter as described in the [RFC 6381](https://www.rfc-editor.org/info/rfc6381)
+standard is included.
+
+For standard codec values, see:
+  * `audio/mp4`: [RFC 6381](https://www.rfc-editor.org/info/rfc6381)
+  * `audio/ogg`: [RFC 5334](https://www.rfc-editor.org/info/rfc5334)
+             and [RFC 7845](https://www.rfc-editor.org/info/rfc7845)
+  * `audio/wav`: [RFC 2361](https://www.rfc-editor.org/info/rfc2361)
+
+No official standards exists for `codecs` values for the
+`application/vnd.ms-asf` and `audio/aiff` MIME types. The most appropriate
+value provided by the format is used.
+
+    # ASF
+    application/vnd.ms-asf
+    application/vnd.ms-asf; codecs="<1..>"  # WAVE format tag, e.g. "161" (WMA)
+
+    # AIFF
+    audio/aiff
+    audio/aiff; codecs="<FourCC>"  # AIFF-C compression type, e.g. "alaw"
+
+    # FLAC
+    audio/flac
+
+    # MP4
+    audio/mp4
+    audio/mp4; codecs="alac"
+    audio/mp4; codecs="mp4a.oo[.A]"  # E.g. "mp4a.40.2" for AAC-LC
+
+    # MP3 / MP2 / MP1
+    audio/mpeg
+
+    # OGG
+    audio/ogg
+    audio/ogg; codecs="flac"
+    audio/ogg; codecs="opus"
+    audio/ogg; codecs="speex"
+    audio/ogg; codecs="vorbis"
+
+    # WAV
+    audio/wav
+    audio/wav; codecs="<1..>"  # WAVE format tag, e.g. "1" for PCM
 
 ### Additional Metadata
 
 For additional values of the same field type, uncommon metadata fields, or
 metadata specific to certain file formats, use `other`:
 
-    tag.other         # a dictionary of additional fields
+```python
+tag.other: OtherFields           # a dictionary of additional fields
+```
 
 > [!WARNING]  
 > The `other` dictionary has replaced the `extra` dictionary in tinytag 2.0.0.
@@ -220,6 +284,7 @@ present when files provide such metadata:
     show_movement
     url
     work
+    xmp
 
 Additional `other` field names not documented above may be present, but are
 format-specific and may change or disappear in future tinytag releases. If
@@ -252,8 +317,10 @@ print(catalog_numbers)
 
 Output:
 
-    > 10
-    > ['10']
+```console
+> 10
+> ['10']
+```
 
 When a file contains multiple values for a [common metadata field](#common-metadata)
 (e.g. `artist`), the primary value is accessed through the common attribute
@@ -275,8 +342,10 @@ print(additional_artists)
 
 Output:
 
-    > main artist
-    > ['another artist', 'yet another artist']
+```console
+> main artist
+> ['another artist', 'yet another artist']
+```
 
 ### All Metadata
 
@@ -284,10 +353,12 @@ If you need to receive all available metadata as key-value pairs in a flat
 dictionary, use the `as_dict()` method. This combines the common attributes
 and `other` dictionary, which can be more convenient in some cases.
 
-    from tinytag import TinyTag
+```python
+from tinytag import TinyTag
 
-    tag: TinyTag = TinyTag.get('/some/music.mp3')
-    metadata: dict = tag.as_dict()
+tag: TinyTag = TinyTag.get('/some/music.mp3')
+metadata: dict = tag.as_dict()
+```
 
 ### Images
 
@@ -297,14 +368,18 @@ keyword argument to `TinyTag.get()`.
 If you need to receive an image of a specific kind, including its description,
 use `images`:
 
-    tag.images        # available embedded images
+```python
+tag.images: Images             # available embedded images
+```
 
 The following common image attributes are available, providing the first
-located image of each kind:
+located `Image` object of each kind:
 
-    tag.images.front_cover  # front cover as 'Image' object
-    tag.images.back_cover   # back cover as 'Image' object
-    tag.images.media        # media (e.g. CD label) as 'Image' object
+```python
+tag.images.front_cover: Image  # front cover
+tag.images.back_cover: Image   # back cover
+tag.images.media: Image        # media (e.g. CD label)
+```
 
 When present, any additional images are available in an `images.other`
 dictionary, using the following standardized key names:
@@ -336,10 +411,13 @@ Provided values are always lists containing at least one `Image` object.
 
 The `Image` object provides the following attributes:
 
-    data           # image data as bytes
-    name           # image name/kind as string
-    mime_type      # image MIME type as string
-    description    # image description as string
+```python
+image.data: bytes               # image data
+image.size: int                 # image size in bytes (added in tinytag 2.3.0) 
+image.name: str                 # image name/kind
+image.mime_type: str | None     # image MIME type
+image.description: str | None   # image description
+```
 
 To receive any available image, prioritizing the front cover, use `images.any`:
 
@@ -351,11 +429,13 @@ image: Image | None = tag.images.any
 
 if image is not None:
     data: bytes = image.data
+    size: int = image.size
     name: str = image.name
-    mime_type: str = image.mime_type
-    description: str = image.description
+    mime_type: str | None = image.mime_type
+    description: str | None = image.description
 
     print(len(data))
+    print(size)
     print(name)
     print(mime_type)
     print(description)
@@ -363,10 +443,13 @@ if image is not None:
 
 Output:
 
-    > 74452
-    > front_cover
-    > image/jpeg
-    > some image description
+```console
+> 74452
+> 74452
+> front_cover
+> image/jpeg
+> some image description
+```
 
 > [!WARNING]  
 > `tag.images.any` has replaced `tag.get_image()` in tinytag 2.0.0.
@@ -383,7 +466,7 @@ cover_image: Image = images.front_cover
 
 if cover_image is not None:
     data: bytes = cover_image.data
-    description: str = cover_image.description
+    description: str | None = cover_image.description
 ```
 
 To receive an additional image, e.g. `bright_colored_fish`:
@@ -401,6 +484,19 @@ if fish_images:
     description = image.description
 ```
 
+### Magic Byte Detection
+
+By default, tinytag will determine the file type by 1. checking the file name
+extension, and 2. reading and inspecting magic bytes in the file header.
+
+In case you want to disable magic byte detection, e.g. to minimize read
+operations when many non-audio files exist in a folder, pass a
+`check_magic_bytes` argument with a value of `False` (added in tinytag 2.3.0).
+
+```python
+tag: TinyTag = TinyTag.get('invalid_file.jpg', check_magic_bytes=False)
+```
+
 ### Encoding
 
 To open files using a specific encoding, you can use the `encoding` parameter.
@@ -408,7 +504,7 @@ This parameter is however only used for formats where the encoding is not
 explicitly specified.
 
 ```python
-TinyTag.get('a_file_with_gbk_encoding.mp3', encoding='gbk')
+tag: TinyTag = TinyTag.get('a_file_with_gbk_encoding.mp3', encoding='gbk')
 ```
 
 ### File-like Objects
@@ -417,18 +513,64 @@ To use a file-like object (e.g. BytesIO) instead of a file path, pass a
 `file_obj` keyword argument:
 
 ```python
-TinyTag.get(file_obj=your_file_obj)
+tag: TinyTag = TinyTag.get(file_obj=your_file_obj)
 ```
 
 ### Exceptions
 
-    TinyTagException        # Base class for exceptions
-    ParseError              # Parsing an audio file failed
-    UnsupportedFormatError  # File format is not supported
+```python
+TinyTagException        # Base class for exceptions
+ParseError              # Parsing an audio file failed
+UnsupportedFormatError  # File format is not supported
+```
 
 
 ## Changelog
 
+### 2.3.0  (2026-07-31)
+
+- Add 'mime_type' attribute for audio MIME type/codec
+- Add 'is_lossless' attribute to indicate lossless audio
+- Add 'size' attribute to images for size in bytes
+- Add option to disable magic byte detection
+- Make XMP metadata available under 'other.xmp' field
+- Make bit depth available for lossy files providing it
+- Add .asf, .ogv and .wmv to list of supported file extensions
+- Mark deprecated 'extra' dictionary as obsolete
+- Fix incorrect key when adding common images to 'other' dictionary
+- Fix disc/track numbers not being returned as lists in 'as_dict()'
+- Only set audio properties with a positive value
+- Always read tags and audio properties in a single pass
+- ID3: Parse multi-value text frames correctly
+- ID3: Parse COMM and USLT frames correctly
+- ID3: Fix some errors in parsed size calculations
+- ID3: Exclude a few frames with custom structures
+- MPEG: Read VBRI and Xing Info headers for duration/bitrate
+- MPEG: Fix parsing of layer I and MPEG-2 layer III audio properties
+- MPEG: Fix slightly incorrect duration estimation
+- MPEG/MP4: Raise ParseError if header is invalid
+- MP4: Add 'image/bmp' and 'image/gif' MIME types
+- MP4: Fix infinite loop if size of certain sub-atoms is zero
+- MP4: Fix incorrect parsing of descriptor size
+- MP4: Don't read image data when image reading is disabled
+- OGG: Parse multi-stream files correctly
+- Speex: Don't read vendor string as comment
+- FLAC: Provide actual audio bitrate instead of overall bitrate
+- FLAC: Parse VORBIS_COMMENT and PICTURE blocks with invalid size
+- FLAC: Ignore subsequent STREAMINFO blocks
+- WAV: Include unknown fields in 'other' dictionary
+- WAV: Calculate bitrate/duration correctly
+- AIFF/WAV: Read whole ID3 chunk before parsing
+- ASF: Support parsing additional metadata objects
+- ASF: Stop parsing if object size is smaller than header
+- ASF: Make magic header detection more strict
+- Various performance improvements
+- Various code refactors
+
+### 2.2.1  (2026-03-15)
+
+- ID3: Prevent infinite loop due to malformed SYLT strings
+
 ### 2.2.0  (2025-12-15)
 
 - Add support for movement, work and grouping fields
@@ -636,7 +778,7 @@ TinyTag.get(file_obj=your_file_obj)
 
 - fixed decoding of UTF-16LE ID3v2 Tags, improved overall stability
 
-### 0.14.0 (2016-06-05):
+### 0.14.0 (2016-06-05)
 
 - MP4/M4A and Opus support