aix.audio

Audio operations interface for AIX.

Provides text-to-speech (TTS) and speech-to-text (transcription) capabilities.

Examples

Text to speech:

>>> from aix.audio import text_to_speech
>>> audio = text_to_speech("Hello, world!")
>>> audio.save("hello.mp3")

Transcription:

>>> from aix.audio import transcribe
>>> text = transcribe("speech.mp3")
>>> print(text)
'Hello, this is a test recording.'

Functions

text_to_speech(text, *[, model, voice, ...])	Convert text to speech audio.
transcribe(audio, *[, engine, model, ...])	Transcribe audio to text.
transcribe_with_timestamps(audio, *[, ...])	Transcribe audio with detailed timestamps.
translate_audio(audio, *[, model, prompt, ...])	Translate audio from any language to English.

Classes

GeneratedAudio(data[, model, text, voice, ...])	Wrapper for generated audio.
TranscriptionResult(text[, language, ...])	Result of audio transcription.

class aix.audio.GeneratedAudio(data, model=None, text=None, voice=None, format='mp3')

Bases: object

Wrapper for generated audio.

Provides convenient access to audio data and saving.

Examples

>>> audio = GeneratedAudio(data=b'...', model="tts-1")
>>> audio.save("output.mp3")
>>> data = audio.as_bytes()

as_bytes()

Get audio as bytes.

Return type:

bytes

Returns:

Audio data as bytes

play()

Play the audio.

Requires a system audio player or library like pygame/pyaudio.

Examples

>>> audio.play()

save(path)

Save audio to file.

Parameters:

path (Union[str, Path]) – Output file path

Examples

>>> audio.save("output.mp3")
>>> audio.save("speech.wav")

class aix.audio.TranscriptionResult(text, language=None, duration=None, segments=None, model=None)

Bases: object

Result of audio transcription.

Contains the transcribed text and optional metadata like segments and timestamps.

Examples

>>> result = TranscriptionResult(text="Hello world")
>>> print(result.text)
'Hello world'

aix.audio.text_to_speech(text, *, model=None, voice=None, speed=None, response_format='mp3', api_key=None, **kwargs)

Convert text to speech audio.

Parameters:

• text (str) – Text to convert to speech

• model (str) – TTS model to use (e.g., ‘tts-1’, ‘tts-1-hd’)

• voice (str) – Voice to use (‘alloy’, ‘echo’, ‘fable’, ‘onyx’, ‘nova’, ‘shimmer’)

• speed (float) – Playback speed (0.25 to 4.0)

• response_format (str) – Audio format (‘mp3’, ‘opus’, ‘aac’, ‘flac’)

• **kwargs – Additional provider-specific parameters

Return type:

GeneratedAudio

Returns:

GeneratedAudio object

Raises:

ImportError – If LiteLLM is not installed

Examples

>>> from aix.audio import text_to_speech
>>> audio = text_to_speech("Hello, how are you?")
>>> audio.save("greeting.mp3")

>>> # Different voice and speed
>>> audio = text_to_speech(
...     "This is a test.",
...     voice="nova",
...     speed=1.2
... )

>>> # High quality
>>> audio = text_to_speech(
...     "Important announcement",
...     model="tts-1-hd",
...     voice="onyx"
... )

aix.audio.transcribe(audio, *, engine=None, model=None, language=None, prompt=None, response_format='text', temperature=None, timestamp_granularities=None, api_key=None, **kwargs)

Transcribe audio to text.

By default this routes through LiteLLM (OpenAI-style transcription). Pass engine= to instead delegate to a scribed backend — one façade over many ASR engines (local Whisper / faster-whisper / vosk, or cloud Deepgram / AssemblyAI / Groq / ElevenLabs / Google …) with speaker diarization and SRT/VTT output. The return type is unchanged either way, so existing callers are unaffected.

Parameters:

• audio (Union[str, Path, BinaryIO, bytes]) – Audio file path, file object, or bytes.

• engine (str) – Optional scribed backend id (e.g. "faster-whisper", "deepgram"). When given, transcription is delegated to scribed (which resolves that engine’s own credentials); the LiteLLM path is bypassed. Requires pip install 'aix[scribed]'. See scribed.list_backends().

• model (str) – Transcription model (e.g. 'whisper-1'); for a scribed engine, the engine-specific model (e.g. a Whisper size).

• language (str) – Source language (ISO-639-1 code, e.g. 'en', 'es').

• prompt (str) – Optional text to guide the model’s style (LiteLLM path).

• response_format (str) – 'text' (default) → str; 'srt'/'vtt' → subtitle str (scribed path); else → TranscriptionResult.

• temperature (float) – Sampling temperature (LiteLLM path).

• timestamp_granularities (list[str]) – Timestamp types (‘word’, ‘segment’) (LiteLLM path).

• **kwargs – Additional parameters (forwarded to LiteLLM, or to the scribed backend — e.g. diarize=True).

Return type:

Union[str, TranscriptionResult]

Returns:

str for response_format in {text, srt, vtt}, else a TranscriptionResult.

Examples

>>> from aix.audio import transcribe
>>> text = transcribe("recording.mp3")
>>> # delegate to a scribed engine (local, free, diarized SRT):
>>> srt = transcribe(
...     "meeting.wav", engine="faster-whisper", response_format="srt"
... )
>>> dg = transcribe(
...     "call.mp3", engine="deepgram", diarize=True,
...     response_format="verbose_json",
... )

aix.audio.transcribe_with_timestamps(audio, *, granularity='segment', model=None, **kwargs)

Transcribe audio with detailed timestamps.

Parameters:

• audio (Union[str, Path, BinaryIO, bytes]) – Audio file path, file object, or bytes

• granularity (str) – Timestamp granularity (‘word’ or ‘segment’)

• model (str) – Transcription model

• **kwargs – Additional parameters for transcribe()

Return type:

TranscriptionResult

Returns:

TranscriptionResult with detailed segments

Examples

>>> from aix.audio import transcribe_with_timestamps
>>> result = transcribe_with_timestamps("lecture.mp3")
>>> for segment in result.segments:
...     start = segment['start']
...     end = segment['end']
...     text = segment['text']
...     print(f"[{start:.2f}-{end:.2f}] {text}")

aix.audio.translate_audio(audio, *, model=None, prompt=None, api_key=None, **kwargs)

Translate audio from any language to English.

Note

Currently uses Whisper’s translation capability which translates to English.

Parameters:

• audio (Union[str, Path, BinaryIO, bytes]) – Audio file path, file object, or bytes

• model (str) – Translation model (typically ‘whisper-1’)

• prompt (str) – Optional text to guide translation

• **kwargs – Additional provider-specific parameters

Return type:

str

Returns:

Translated text in English

Examples

>>> from aix.audio import translate_audio
>>> english_text = translate_audio("spanish_audio.mp3")
>>> print(english_text)
'This is the English translation.'