transparentmeta.use_case.read package

Submodules

transparentmeta.use_case.read.factory module

This module provides factory functions for creating instances of concrete MetadataReader classes and ReadUseCase.

transparentmeta.use_case.read.factory.build_metadata_reader(audio_format, transparency_metadata_field='transparency', signature_field='signature')[source]

Creates an instance of the appropriate concrete MetadataReader based on audio format.

Parameters:

  • audio_format (str) – The audio format, either “mp3” or “wav”.

  • transparency_metadata_field (str) – ID3 TXXX field for storing metadata.

  • signature_field (str) – ID3 TXXX field for storing the metadata signature.

Returns:

An instance of MP3MetadataReader or

WAVMetadataReader.

Return type:

metadata_reader (MetadataReader)

Raises:

UnsupportedAudioFormatError – If the audio format is unsupported.

transparentmeta.use_case.read.factory.build_read_use_case(public_key, audio_format, transparency_metadata_field='transparency', signature_field='signature')[source]

Creates an instance of ReadUseCase by resolving all dependencies.

Parameters:

  • public_key (Ed25519PublicKey) – The public key used for signature verification.

  • audio_format (str) – The audio format, either “mp3” or “wav”.

  • transparency_metadata_field (str) – ID3 TXXX field for storing metadata. Defaults to “transparency”.

  • signature_field (str) – ID3 TXXX field for storing the metadata signature. Defaults to “signature”.

Returns:

An instance of ReadUseCase configured

for the specified audio format.

Return type:

read_use_case (ReadUseCase)

Raises:

UnsupportedAudioFormatError – If the audio format is unsupported.

transparentmeta.use_case.read.metadata_reader module

This module provides an abstract MetadataReader class that defines the interface for reading metadata and a digital signature from audio files using ID3, using the Mutagen library for audio file handling.

class transparentmeta.use_case.read.metadata_reader.AudioFileDataReading(is_success, metadata=None, signature=None)[source]

Bases: object

Represents the result of reading metadata and signature from an audio file.

metadata

The serialized metadata string, if found.

Type:

Optional[str]

signature

The digital signature string, if found.

Type:

Optional[str]

is_success

Indicates whether both metadata and signature were successfully retrieved.

Type:

bool

__init__(is_success, metadata=None, signature=None)
is_success: bool
metadata: Optional[str] = None
signature: Optional[str] = None
class transparentmeta.use_case.read.metadata_reader.MetadataReader(transparency_metadata_field='transparency', signature_field='signature')[source]

Bases: ABC

Abstract base class for reading metadata and a digital signature from ID3 metadata tags.

Subclasses should implement the _load_audio() method for specific file formats (e.g., MP3, WAV).

This class ensures consistency in how transparency metadata and its signature are retrieved.

transparency_metadata_field

ID3 TXXX field used to store transparency metadata. Defaults to “transparency”.

Type:

str

signature_field

ID3 TXXX field used to store the metadata signature. Defaults to “signature”.

Type:

str

__init__(transparency_metadata_field='transparency', signature_field='signature')[source]

Initializes the MetadataReader with custom metadata and signature fields.

Parameters:

  • transparency_metadata_field (str) – ID3 TXXX field used to store transparency metadata.

  • signature_field (str) – ID3 TXXX field used to store the signature.

read(filepath)[source]

Reads metadata and its signature from the specified audio file.

This method uses the tags defined by transparency_metadata_field and signature_field to extract the information from ID3 tags.

Parameters:

filepath (Path) – Path to the audio file to read.

Returns:

An object

containing the metadata, signature, and success info. If either the metadata or the signature is missing, is_success will be False.

Return type:

audio_file_data_reading (AudioFileDataReading)

transparentmeta.use_case.read.mp3_metadata_reader module

This module provides an MP3MetadataReader class that reads transparency metadata and a digital signature from MP3 files using Mutagen’s ID3 tagging system.

class transparentmeta.use_case.read.mp3_metadata_reader.MP3MetadataReader(transparency_metadata_field='transparency', signature_field='signature')[source]

Bases: MetadataReader

Reads transparency metadata and a digital signature from MP3 files.

This class loads an MP3 file and retrieves values from custom ID3 TXXX fields, providing consistent access to signed metadata.

transparentmeta.use_case.read.read_use_case module

This module provides a ReadUseCase class with the core business logic for reading, verifying, and deserializing transparency metadata from audio files. It acts as a facade over MetadataReader, SignatureVerifier, and MetadataSerializer.

class transparentmeta.use_case.read.read_use_case.ReadUseCase(metadata_reader, signature_verifier, metadata_serializer)[source]

Bases: object

Facade for managing the reading, signature verification, and deserialization of transparency metadata from audio files.

This class simplifies the process by: 1. Extracting metadata and its signature from an audio file using

MetadataReader.

  1. Verifying the signature using SignatureVerifier.

  2. Deserializing the metadata using MetadataSerializer.

metadata_reader

The reader responsible for extracting metadata and signature from the file.

Type:

MetadataReader

signature_verifier

Verifies the digital signature of the metadata.

Type:

SignatureVerifier

metadata_serializer

Deserializes the raw metadata string into a metadata object.

Type:

MetadataSerializer

__init__(metadata_reader, signature_verifier, metadata_serializer)[source]

Initializes the ReadUseCase with reader, verifier, and serializer.

Parameters:
property metadata_reader: MetadataReader

Gets the current metadata reader.

Returns:

The active metadata reader instance.

Return type:

MetadataReader

read(read_request)[source]

Reads metadata and its signature from the audio file, verifies the signature, and deserializes the metadata.

Parameters:

read_request (ReadRequest) – Path to the audio file.

Returns:

A result object indicating whether the read was

successful, and if so, includes the deserialized metadata.

Return type:

ReadResult

transparentmeta.use_case.read.reader_selector module

Module for selecting the appropriate metadata reader based on audio file format.

This module defines a registry of available metadata readers (e.g., for MP3 and WAV) and provides the ReaderSelector class to dispatch the correct reader instance based on the file extension. It serves as an abstraction layer to decouple audio format-specific logic from higher-level orchestration.

class transparentmeta.use_case.read.reader_selector.ReaderSelector(metadata_readers=mappingproxy({'mp3': <transparentmeta.use_case.read.mp3_metadata_reader.MP3MetadataReader object>, 'wav': <transparentmeta.use_case.read.wav_metadata_reader.WAVMetadataReader object>, 'wave': <transparentmeta.use_case.read.wav_metadata_reader.WAVMetadataReader object>}))[source]

Bases: object

Selects the appropriate MetadataReader based on the audio file extension.

This class acts as a lightweight strategy resolver for mapping file extensions (such as ‘mp3’, ‘wav’, or ‘wave’) to their corresponding metadata reader instances. It abstracts away the logic of format-specific handling, promoting modularity and extensibility.

metadata_readers

An immutable mapping of file extensions to metadata reader instances.

Type:

Mapping[str, MetadataReader]

__init__(metadata_readers=mappingproxy({'mp3': <transparentmeta.use_case.read.mp3_metadata_reader.MP3MetadataReader object>, 'wav': <transparentmeta.use_case.read.wav_metadata_reader.WAVMetadataReader object>, 'wave': <transparentmeta.use_case.read.wav_metadata_reader.WAVMetadataReader object>}))[source]

Initializes the ReaderSelector with a registry of metadata readers.

Parameters:

  • metadata_readers (Mapping[str, MetadataReader]) – An immutable

  • corresponding (dictionary mapping file extensions to their)

  • implementations. (metadata reader)

get_reader(file_format)[source]

Selects the appropriate metadata reader based on the file extension.

Parameters:

file_format (str) – The file extension of the audio file (e.g., ‘mp3’, ‘wav’).

Returns:

The corresponding metadata

reader for the file extension.

Return type:

metadata_reader (MetadataReader)

transparentmeta.use_case.read.wav_metadata_reader module

This module provides a WAVMetadataReader class that reads transparency metadata and a digital signature from WAV files using Mutagen’s ID3 tagging system.

class transparentmeta.use_case.read.wav_metadata_reader.WAVMetadataReader(transparency_metadata_field='transparency', signature_field='signature')[source]

Bases: MetadataReader

Reads transparency metadata and a digital signature from WAV files.

This class loads a WAV file and retrieves values from custom ID3 TXXX fields, enabling consistent extraction of signed metadata.

Module contents