audio_utils

Audio utilities for combining and tagging MP3s.

These utilities are useful for working with multiple MP3s generated by a TTS model from chunks of a larger body of text. For example, combining the MP3s into a single MP3 and adding ID3 tags, including cover art.

Functions:

Name	Description
combine_mp3_buffers	Combines multiple in-memory MP3 buffers into a single MP3 file buffer and applies tags and album art.

combine_mp3_buffers

combine_mp3_buffers(
    mp3_buffers: list[BytesIO],
    tags: dict[str, str] | None = None,
    album_art: BytesIO | None = None,
    album_art_mime: str = "image/png",
) -> BytesIO

Combines multiple in-memory MP3 buffers into a single MP3 file buffer and applies tags and album art.

Use this function to combine TTS-generated MP3s that were created from chunked text input.

Parameters:

Name	Type	Description	Default
mp3_buffers	list[BytesIO]	List of in-memory MP3 buffers to combine.	required
tags	dict[str, str] | None	Dictionary of tags to apply to the output MP3.	None
album_art	BytesIO | None	In-memory buffer for the album art image.	None
album_art_mime	str	MIME type for the album art (typically 'image/png' or 'image/jpeg').	'image/png'

Raises:

Type	Description
ValueError	If no buffers are provided, if buffers are invalid MP3, or if their codec parameters (bitrate, sample rate) differ.

Examples:

Combine two in-memory MP3 files and tag the result:

buffer1 = io.BytesIO(open("file1.mp3", "rb").read())
buffer2 = io.BytesIO(open("file2.mp3", "rb").read())

tags = {
    "title": "Combined Audio",
    "artist": "AI Composer",
    "album": "AI Album",
    "genre": "Books & Spoken",
}

# Load cover image PNG from disk
with open("cover.png", "rb") as img_file:
    album_art_bytes = io.BytesIO(img_file.read())

combined_mp3 = await combine_mp3_buffers(
    [buffer1, buffer2],
    tags=tags,
    album_art=album_art_bytes,
    album_art_mime="image/png",
)

# Write MP3 to file
with open("output.mp3", "wb") as out_file:
    combined_mp3.seek(0)
    out_file.write(combined_mp3.read())