transparentmeta.sdk package

Submodules

transparentmeta.sdk.factory module

This module provides factory functions for creating instances of TransparentMetadataWriter and TransparentMetadataReader with a simple function call.

Developers should use these functions as the primary interface for instantiating these classes, which serve as the main entry points for writing and reading digitally-signed metadata in audio files using transparentmeta.

transparentmeta.sdk.factory.build_transparent_metadata_reader(public_key)

Creates an instance of TransparentReader with all dependencies resolved.

Parameters:

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

Returns:

An instance

of TransparentReader ready to be used for metadata reading

Return type:

transparent_metadata_reader (TransparentMetadataReader)

transparentmeta.sdk.factory.build_transparent_metadata_writer(private_key)

Creates an instance of TransparentWriter with all dependencies resolved.

Parameters:

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

Returns:

An instance

of TransparentWriter ready to be used for metadata writing

Return type:

transparent_metadata_writer (TransparentMetadataWriter)

transparentmeta.sdk.transparent_metadata_reader module

SDK entry point for reading digitally signed metadata from audio files.

The TransparentMetadataReader class acts as a user-facing API that handles deserialization and signature verification of metadata embedded in MP3 or WAV files through a single method call.

class transparentmeta.sdk.transparent_metadata_reader.TransparentMetadataReader(read_use_case, reader_selector)

Bases: object

High-level interface for reading transparency metadata from audio files.

The TransparentMetadataReader coordinates the extraction, deserialization, and signature verification of metadata embedded in supported audio formats. It delegates verification to the ReadUseCase and uses a ReaderSelector to choose the appropriate metadata reader based on file extension.

read_use_case

Handles deserialization and signature verification.

Type:

ReadUseCase

reader_selector

Selects the appropriate reader based on file format.

Type:

ReaderSelector

__init__(read_use_case, reader_selector)

Initializes the TransparentMetadataReader.

Parameters:

• read_use_case (ReadUseCase) – The use case for metadata extraction and signature verification.

• reader_selector (ReaderSelector) – Resolves format-specific readers based on the extension of the audio file passed.

read(filepath)

Reads and verifies transparency metadata from an audio file.

Selects the appropriate metadata reader based on file extension (e.g., ‘mp3’, ‘wav’, ‘wave’), extracts and deserializes the metadata, and verifies its digital signature.

Parameters:

filepath (Path) – Path to the audio file from which metadata should be read and verified.

Returns:

Contains the extracted metadata, validation status,

and any related error information.

Return type:

ReadResult

transparentmeta.sdk.transparent_metadata_writer module

SDK entry point for writing digitally signed metadata to audio files.

This module defines the TransparentMetadataWriter class, which acts as a high-level orchestrator for embedding transparency metadata into AI-generated audio content (e.g., MP3 or WAV). It handles metadata preparation, format-specific writer selection, and invocation of the underlying write use case.

class transparentmeta.sdk.transparent_metadata_writer.TransparentMetadataWriter(write_use_case, writer_selector)

Bases: object

High-level interface for writing transparency metadata to audio files.

The TransparentMetadataWriter coordinates the serialization, signing, and embedding of metadata into supported audio formats. It delegates signing to the WriteUseCase and uses a WriterSelector to choose the appropriate metadata writer based on file extension.

write_use_case

Handles signing and writing of metadata.

Type:

WriteUseCase

writer_selector

Resolves the appropriate writer for each file format.

Type:

WriterSelector

__init__(write_use_case, writer_selector)

Initializes the TransparentMetadataWriter.

Parameters:

• write_use_case (WriteUseCase) – The use case handling metadata signing and writing.

• writer_selector (WriterSelector) – Format resolver for metadata writers.

write(filepath, metadata)

Writes signed transparency metadata to an audio file.

This method constructs a WriteRequest from the given metadata, selects the appropriate metadata writer based on the file extension, and delegates the actual write operation to the WriteUseCase.

Parameters:

• filepath (Path) – Path to the target audio file (e.g., ‘track.mp3’).

• metadata (Dict) –

  A dictionary of metadata fields. Must match the structure expected by Metadata. Example:

  {

  “company”: “Transparent Audio”, “model”: “v2.1”, “created_at”: datetime.utcnow(), “ai_usage_level”: AIUsageLevel.AI_ASSISTED, “content_id”: “12345abcd”, “user_id”: “user_67890”, “private_key_id”: “dummy_private_key_id”, “additional_info”: {

  ”attribution”: {

  “lyrics”: “John Doe”, “composer”: “Jane Smith”

  }

  }

  }

Return type:

None

Module contents

Exposes the main interfaces of the transparentmeta SDK for direct import from the transparentmeta.sdk package.

class transparentmeta.sdk.TransparentMetadataReader(read_use_case, reader_selector)

Bases: object

High-level interface for reading transparency metadata from audio files.

The TransparentMetadataReader coordinates the extraction, deserialization, and signature verification of metadata embedded in supported audio formats. It delegates verification to the ReadUseCase and uses a ReaderSelector to choose the appropriate metadata reader based on file extension.

read_use_case

Handles deserialization and signature verification.

Type:

ReadUseCase

reader_selector

Selects the appropriate reader based on file format.

Type:

ReaderSelector

__init__(read_use_case, reader_selector)

Initializes the TransparentMetadataReader.

Parameters:

• read_use_case (ReadUseCase) – The use case for metadata extraction and signature verification.

• reader_selector (ReaderSelector) – Resolves format-specific readers based on the extension of the audio file passed.

read(filepath)

Reads and verifies transparency metadata from an audio file.

Selects the appropriate metadata reader based on file extension (e.g., ‘mp3’, ‘wav’, ‘wave’), extracts and deserializes the metadata, and verifies its digital signature.

Parameters:

filepath (Path) – Path to the audio file from which metadata should be read and verified.

Returns:

Contains the extracted metadata, validation status,

and any related error information.

Return type:

ReadResult

class transparentmeta.sdk.TransparentMetadataWriter(write_use_case, writer_selector)

Bases: object

High-level interface for writing transparency metadata to audio files.

The TransparentMetadataWriter coordinates the serialization, signing, and embedding of metadata into supported audio formats. It delegates signing to the WriteUseCase and uses a WriterSelector to choose the appropriate metadata writer based on file extension.

write_use_case

Handles signing and writing of metadata.

Type:

WriteUseCase

writer_selector

Resolves the appropriate writer for each file format.

Type:

WriterSelector

__init__(write_use_case, writer_selector)

Initializes the TransparentMetadataWriter.

Parameters:

• write_use_case (WriteUseCase) – The use case handling metadata signing and writing.

• writer_selector (WriterSelector) – Format resolver for metadata writers.

write(filepath, metadata)

Writes signed transparency metadata to an audio file.

This method constructs a WriteRequest from the given metadata, selects the appropriate metadata writer based on the file extension, and delegates the actual write operation to the WriteUseCase.

Parameters:

• filepath (Path) – Path to the target audio file (e.g., ‘track.mp3’).

• metadata (Dict) –

  A dictionary of metadata fields. Must match the structure expected by Metadata. Example:

  {

  “company”: “Transparent Audio”, “model”: “v2.1”, “created_at”: datetime.utcnow(), “ai_usage_level”: AIUsageLevel.AI_ASSISTED, “content_id”: “12345abcd”, “user_id”: “user_67890”, “private_key_id”: “dummy_private_key_id”, “additional_info”: {

  ”attribution”: {

  “lyrics”: “John Doe”, “composer”: “Jane Smith”

  }

  }

  }

Return type:

None

transparentmeta.sdk.build_transparent_metadata_reader(public_key)

Creates an instance of TransparentReader with all dependencies resolved.

Parameters:

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

Returns:

An instance

of TransparentReader ready to be used for metadata reading

Return type:

transparent_metadata_reader (TransparentMetadataReader)

transparentmeta.sdk.build_transparent_metadata_writer(private_key)

Creates an instance of TransparentWriter with all dependencies resolved.

Parameters:

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

Returns:

An instance

of TransparentWriter ready to be used for metadata writing

Return type:

transparent_metadata_writer (TransparentMetadataWriter)