API

Use the core engine without the UI.

Basic Usage

import asyncio
from reader.core import ReaderEngine

async def main():
    engine = ReaderEngine()
    await engine.setup()

    result = engine.synthesize("Hello world")
    engine.play()
    engine.wait()
    engine.save("output.mp3")

asyncio.run(main())

Streaming

async def stream_example():
    engine = ReaderEngine()
    await engine.setup()

    async for samples, sample_rate in engine.synthesize_stream("Long text here..."):
        # Each chunk plays as it's generated
        print(f"Got chunk: {len(samples)} samples")

    # Save combined audio
    engine.save("output.mp3")

Configuration

from reader.core import ReaderEngine, ReaderConfig, TTSConfig

config = ReaderConfig(
    tts=TTSConfig(
        voice="bf_emma",
        speed=1.2
    )
)
engine = ReaderEngine(config)

Methods

setup()

Initialize engine and download models if needed.

await engine.setup()

synthesize(text)

Generate audio without playing.

result = engine.synthesize("Text to speak")
# result contains: samples, sample_rate, duration, etc.

synthesize_stream(text)

Stream audio chunks as they're generated.

async for samples, sample_rate in engine.synthesize_stream(text):
    # Process each chunk
    pass

play()

Play the last synthesized audio.

engine.play()

stop()

Stop playback.

engine.stop()

wait()

Block until playback finishes.

engine.wait()

save(path)

Export to file. Format determined by extension.

engine.save("output.mp3")

set_voice(voice_id)

Change voice.

engine.set_voice("am_adam")

set_speed(speed)

Change speed. Range: 0.5 to 2.0.

engine.set_speed(1.5)

set_preprocessing(enabled)

Enable/disable abbreviation expansion.

engine.set_preprocessing(True)

Available Voices

from reader.core import LANGUAGES, VOICES

# All voice IDs
print(VOICES)

# Voices by language
for lang, data in LANGUAGES.items():
    print(f"{lang}: {len(data['voices'])} voices")

Example: Batch Processing

import asyncio
from pathlib import Path
from reader.core import ReaderEngine

async def batch_convert(texts: list[str], output_dir: Path):
    engine = ReaderEngine()
    await engine.setup()

    for i, text in enumerate(texts):
        engine.synthesize(text)
        engine.save(output_dir / f"audio_{i:03d}.mp3")
        print(f"Saved {i+1}/{len(texts)}")

asyncio.run(batch_convert(
    ["First text", "Second text", "Third text"],
    Path("./output")
))