voco 0.0.2

Modular audio model inference runtime with plugin architecture

VOCO

Modular audio inference runtime with plugin architecture.

Overview

Voco separates the core runtime from model implementations. Install only what you need, use a consistent API across different models.

Core concept: One interface for multiple TTS/audio models.

router = AudioRouter()
router.load("kokoro", alias="tts")
router.infer("tts", text="Hello world")

Switch models without changing your code:

router.load("other-model", alias="tts")  # Same interface
router.infer("tts", text="Hello world")

Install

# Core (lightweight, no dependencies)
pip install voco

# Install plugins you need
pip install voco-kokoro  # for Kokoro TTS

Usage

from voco.core import AudioRouter
import voco_kokoro

router = AudioRouter()
router.load("kokoro", alias="tts", device="cpu")

for result in router.infer("tts", text="Hello world", voice="af_heart"):
    audio = result.audio

How It Works

Voco separates the core runtime from model plugins:

1. Core (voco): Router, caching, plugin loader - no heavy dependencies
2. Plugins (voco-kokoro, voco-gtts, etc.): Each model is a separate package with its own dependencies

Load models dynamically at runtime:

router = AudioRouter()
router.load("kokoro", alias="tts")  # Loads voco-kokoro plugin
audio = router.infer("tts", text="Hello world")

Switch models without changing code:

router.load("gtts", alias="tts")  # Replace with Google TTS
audio = router.infer("tts", text="Hello world")  # Same interface

Features

• Zero dependencies in core
• Consistent API across models
• Plugin architecture
• Optional caching layer (experimental)
• Type safe

Caching (Experimental)

Optional file-based cache for repeated inference calls.

router = AudioRouter(cache=True)

# First call generates and caches
audio = router.infer("tts", text="Hello world")

# Subsequent calls return cached result
audio = router.infer("tts", text="Hello world")

Configuration

router = AudioRouter(
    cache=True,
    cache_config={
        "max_size_mb": 500,           # Max cache size
        "ttl_seconds": 86400,         # Time to live (1 hour - 30 days)
        "warn_at_percent": 80,        # Warning threshold
    }
)

Management

router.cache.stats()              # View cache usage
router.cache.clear()              # Clear all cache
router.cache.clear(model="tts")   # Clear specific model

Per-Call Control

# Skip cache for specific call
audio = router.infer("tts", text="Hello", cache=False)

Notes

voco uses file-based cache and stored in ~/.voco/cache/. Keys are generated from model name, text, and parameters by default.

Useful for repeated phrases. Not recommended for unique text or privacy-sensitive content and realtime environments.

Plugins

Each plugin is a separate PyPI package with its own dependencies. Install only what you need.

Available Plugins

• voco-kokoro - Kokoro TTS

Creating Plugins

Plugins register themselves via Python entry points. See CONTRIBUTING.md for the plugin development guide.

# Your plugin structure
voco-myplugin/
├── voco_myplugin/
│   └── __init__.py  # Implements BaseAudioModel
└── pyproject.toml   # Defines entry point

Development

See CONTRIBUTING.md for detailed setup and plugin development guide.

git clone https://github.com/yourusername/voco.git
cd voco
pip install -e .
pip install -e plugins/voco-kokoro
python examples/generate_audio.py

License

MIT