transparentmeta.utils package

Submodules

transparentmeta.utils.encoding_utils module

Utility functions for encoding and decoding strings and bytes.

transparentmeta.utils.encoding_utils.decode_bytes_to_hexadecimal_string(byte_data, character_encoding)[source]

Decodes bytes to a hexadecimal string.

Parameters:

  • byte_data (bytes) – The bytes to encode.

  • character_encoding (str) – The character encoding to use (e.g., “utf-8”).

Returns:

The hexadecimal representation of the bytes encoded with the

specified character encoding.

Return type:

str

transparentmeta.utils.encoding_utils.encode_hexadecimal_string_to_bytes(hex_string)[source]

Encodes a hexadecimal string to bytes.

Parameters:

hex_string (str) – The hexadecimal string to decode.

Returns:

The corresponding byte representation.

Return type:

bytes

Raises:

InvalidHexadecimalStringError – If the input is not a valid hexadecimal string.

transparentmeta.utils.encoding_utils.encode_string_to_bytes(string, character_encoding)[source]

Encodes a string to bytes using the specified character encoding.

Parameters:

  • string (str) – The string to encode.

  • character_encoding (str) – The character encoding to use (e.g., “utf-8”).

Returns:

The byte representation of the string encoded with the specified

character encoding.

Return type:

bytes

transparentmeta.utils.exceptions module

This module hosts all custom exceptions used in utils.

exception transparentmeta.utils.exceptions.InvalidHexadecimalStringError(string)[source]

Bases: Exception

Raised when a string is not a valid hexadecimal string.

__init__(string)[source]

transparentmeta.utils.file_utils module

Utility functions for file-related operations.

This module provides helper functions to work with files, such as extracting file extensions in a normalized format.

transparentmeta.utils.file_utils.get_file_extension(filepath)[source]

Extracts the file extension from a given filepath.

Parameters:

filepath (Path) – The path to the file.

Returns:

The file extension in lowercase without the leading dot.

Return type:

str

transparentmeta.utils.metadata_tags_utils module

Utility functions for adding ID3v2 tags in audio files.

This module provides helpers to create, modify, and check ID3v2 tags in MP3 and WAV audio files using the mutagen library.

These functions are used to embed or validate structured transparency metadata within audio files.

transparentmeta.utils.metadata_tags_utils.create_id3_tags_in_file_if_none_exists(audio)[source]

Ensures that the audio file has ID3 tags. If not, it adds empty tags.

While ID3 tags are native to MP3 files, mutagen also allows adding ID3 tags to WAV files by squeezing a custom ID3 chunk into the RIFF header of the WAV file.

Parameters:

audio (MutagenID3AudioTypes) – The audio file object with ID3 support.

Returns:

The audio file object with ID3 tags added if they were

missing.

Return type:

MutagenID3AudioTypes

transparentmeta.utils.metadata_tags_utils.does_file_contain_any_id3_tags(audio)[source]

Checks if the audio file contains any ID3 tags.

Parameters:

audio (MutagenID3AudioTypes) – The audio file object with ID3 support.

Returns:

True if the audio file contains any tags, False otherwise.

Return type:

bool

transparentmeta.utils.metadata_tags_utils.set_txxx_id3_tag(audio, field, value)[source]

Sets a specific TXXX id3v2 tag in an audio file. TXXX tags are used for custom text information in ID3 tags, defined by users.

Parameters:

  • audio (MutagenID3AudioTypes) – The audio file object.

  • field (str) – The TXXX field to set.

  • value (str) – The value to set for the specified field.

Returns:

The modified audio file object with the updated tag.

Return type:

MutagenID3AudioTypes

Module contents