transparentmeta.use_case.write package

Submodules

transparentmeta.use_case.write.factory module

This module provides factory functions for creating instances of concrete MetadataWriter classes and WriteUseCase.

transparentmeta.use_case.write.factory.build_metadata_writer(audio_format, transparency_metadata_field='transparency', signature_field='signature')

Creates an instance of the appropriate concrete MetadataWriter 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 MP3MetadataWriter or

WAVMetadataWriter.

Return type:

metadata_writer (MetadataWriter)

Raises:

UnsupportedAudioFormatError – If the audio format is unsupported.

transparentmeta.use_case.write.factory.build_write_use_case(private_key, audio_format, transparency_metadata_field='transparency', signature_field='signature')

Creates an instance of WriteUseCase resolving all dependencies.

Parameters:

• private_key (Ed25519PrivateKey) – The private key used for signing.

• 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 WriteUseCase configured

for the specified audio format.

Return type:

write_use_case (WriteUseCase)

Raises:

UnsupportedAudioFormatError – If the audio format is unsupported.

transparentmeta.use_case.write.metadata_writer module

This module provides an abstract MetadataWriter class that defines the interface for writing metadata and a digital signature to audio files using ID3.

class transparentmeta.use_case.write.metadata_writer.MetadataWriter(transparency_metadata_field='transparency', signature_field='signature')

Bases: ABC

Abstract base class for writing metadata and a digital signature to audio files using ID3 tagging.

This class provides a standard interface for writing metadata in ID3-based formats like MP3 and WAV. It ensures metadata consistency across different audio file types by using TXXX frames.

The class uses the mutagen library to inject ID3 tags into audio files.

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

transparency_metadata_field

ID3 TXXX field for storing metadata.

Type:

str

signature_field

ID3 TXXX field for storing the metadata signature.

Type:

str

__init__(transparency_metadata_field='transparency', signature_field='signature')

Initializes the MetadataWriter with custom metadata and signature fields.

Parameters:

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

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

abstractmethod write(filepath, metadata, signature)

Writes metadata and a digital signature to an audio file. This method must be implemented by subclasses.

Parameters:

• filepath (Path) – The path to the audio file.

• metadata (str) – The serialized metadata string with transparency info.

• signature (str) – The signature string.

Return type:

None

transparentmeta.use_case.write.mp3_metadata_writer module

This module provides a MP3MetadataWriter class that writes metadata and a digital signature to MP3 files using the Mutagen library for ID3 tagging.

class transparentmeta.use_case.write.mp3_metadata_writer.MP3MetadataWriter(transparency_metadata_field='transparency', signature_field='signature')

Bases: MetadataWriter

Writes metadata and a digital signature to MP3 files.

write(filepath, metadata, signature)

Writes metadata and signature to ID3 TXXX fields of an MP3 file.

Parameters:

• filepath (Path) – The MP3 file path.

• metadata (str) – Serialized use_case string with transparency info.

• signature (str) – The signature string.

Return type:

None

transparentmeta.use_case.write.wav_metadata_writer module

This module provides a WAVMetadataWriter class that writes metadata and a digital signature to WAV files using the Mutagen library for ID3 tagging.

class transparentmeta.use_case.write.wav_metadata_writer.WAVMetadataWriter(transparency_metadata_field='transparency', signature_field='signature')

Bases: MetadataWriter

Writes metadata and a digital signature to WAV files using Mutagen.

write(filepath, metadata, signature)

Writes metadata and signature ID3 TXXX fields of a WAV file.

Parameters:

• filepath (Path) – The WAV file path.

• metadata (str) – Serialized metadata string with transparency info.

• signature (str) – The signature string.

Return type:

None

transparentmeta.use_case.write.write_use_case module

This module provides a WriteUseCase class with the core business logic for the process of serializing metadata, signing it, and writing it to ID3 tags in audio files.

This class acts as a facade over MetadataSerializer, Signer, and MetadataWriter.

class transparentmeta.use_case.write.write_use_case.WriteUseCase(metadata_serializer, signer, metadata_writer)

Bases: object

Facade for managing metadata writing, serialization, and signing in one go. It takes care of the core business logic for writing metadata to audio files.

This class simplifies metadata writing by: 1. Serializing metadata using MetadataSerializer. 2. Creating a signature using Signer. 3. Writing metadata and its signature to an audio file using a concrete

MetadataWriter.

metadata_serializer

Handles serialization.

Type:

MetadataSerializer

signer

Handles signing metadata.

Type:

Signer

metadata_writer

Writes metadata to audio files.

Type:

MetadataWriter

__init__(metadata_serializer, signer, metadata_writer)

Initializes the WriteUseCase with serializer, signer, and writer.

Parameters:

• metadata_serializer (MetadataSerializer) – The Metadata serializer.

• signer (Signer) – The signer for generating metadata signatures.

• metadata_writer (MetadataWriter) – The writer for embedding metadata.

property metadata_writer: MetadataWriter

Gets the current metadata writer.

Returns:

The active metadata writer instance.

Return type:

MetadataWriter

write(write_request)

Serializes metadata, signs it, and writes it to the audio file in ID3 tags.

Parameters:

write_request (WriteRequest) – The request containing the filepath and metadata to write.

Return type:

None

transparentmeta.use_case.write.writer_selector module

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

class transparentmeta.use_case.write.writer_selector.WriterSelector(metadata_writers=mappingproxy({'mp3': <transparentmeta.use_case.write.mp3_metadata_writer.MP3MetadataWriter object>, 'wav': <transparentmeta.use_case.write.wav_metadata_writer.WAVMetadataWriter object>, 'wave': <transparentmeta.use_case.write.wav_metadata_writer.WAVMetadataWriter object>}))

Bases: object

Selects the appropriate MetadataWriter 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 writer instances. It abstracts away the logic of format-specific handling, promoting modularity and extensibility.

metadata_writers

A mapping of file extensions to metadata writer instances.

Type:

MetadataWriterRegistry

__init__(metadata_writers=mappingproxy({'mp3': <transparentmeta.use_case.write.mp3_metadata_writer.MP3MetadataWriter object>, 'wav': <transparentmeta.use_case.write.wav_metadata_writer.WAVMetadataWriter object>, 'wave': <transparentmeta.use_case.write.wav_metadata_writer.WAVMetadataWriter object>}))

Initializes the WriterSelector with a registry of available metadata writers.

Parameters:

metadata_writers (MetadataWriterRegistry) – An immutable dictionary mapping file extensions to their corresponding metadata writer implementations.

get_writer(file_format)

Selects the appropriate metadata writer based on the file extension.

Parameters:

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

Returns:

The corresponding metadata

writer for the file extension.

Return type:

metadata_writer (MetadataWriter)

Module contents