vocal-api 0.3.0__tar.gz

vocal_api-0.3.0/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# UV
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Model cache
+.cache/
+models/
+*.ckpt
+*.pth
+*.pt
+*.safetensors
+
+# Audio files (test data)
+*.mp3
+*.wav
+*.m4a
+*.ogg
+*.flac
+
+# Logs
+*.log
+logs/
+
+# Environment variables
+.env
+.env.local
+
+# OS
+Thumbs.db

vocal_api-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include ../../../README.md
+include ../../../LICENSE
+recursive-include vocal_api *.py

vocal_api-0.3.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: vocal-api
+Version: 0.3.0
+Summary: FastAPI server for Vocal - Ollama-style Voice Model Management
+Project-URL: Homepage, https://github.com/niradler/vocal
+Project-URL: Documentation, https://github.com/niradler/vocal#readme
+Project-URL: Repository, https://github.com/niradler/vocal
+Project-URL: Issues, https://github.com/niradler/vocal/issues
+Author: Vocal Contributors
+License: SSPL-1.0
+Keywords: api,fastapi,openai-compatible,speech-to-text,stt,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: vocal-core>=0.3.0

vocal_api-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "vocal-api"
+version = "0.3.0"
+description = "FastAPI server for Vocal - Ollama-style Voice Model Management"
+requires-python = ">=3.11"
+license = { text = "SSPL-1.0" }
+authors = [
+    { name = "Vocal Contributors" }
+]
+keywords = ["fastapi", "api", "speech-to-text", "tts", "stt", "openai-compatible"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic>=2.5.0",
+    "python-multipart>=0.0.6",
+    "vocal-core>=0.3.0",
+    "aiofiles>=25.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/niradler/vocal"
+Documentation = "https://github.com/niradler/vocal#readme"
+Repository = "https://github.com/niradler/vocal"
+Issues = "https://github.com/niradler/vocal/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

vocal_api-0.3.0/vocal_api/__init__.py

@@ -0,0 +1,9 @@
+from .config import settings
+from .main import app
+
+__version__ = settings.VERSION
+
+__all__ = [
+    "app",
+    "settings",
+]

vocal_api-0.3.0/vocal_api/config.py

@@ -0,0 +1,21 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings"""
+
+    APP_NAME: str = "Vocal API"
+    VERSION: str = "0.1.0"
+    DEBUG: bool = True
+
+    CORS_ORIGINS: list[str] = ["*"]
+
+    MAX_UPLOAD_SIZE: int = 25 * 1024 * 1024
+
+    model_config = {
+        "env_file": ".env",
+        "case_sensitive": True,
+    }
+
+
+settings = Settings()

vocal_api-0.3.0/vocal_api/dependencies.py

@@ -0,0 +1,43 @@
+from vocal_core import ModelRegistry
+
+from .services import ModelService, TranscriptionService, TTSService
+
+_registry: ModelRegistry | None = None
+_transcription_service: TranscriptionService | None = None
+_model_service: ModelService | None = None
+_tts_service: TTSService | None = None
+
+
+def get_registry() -> ModelRegistry:
+    """Get or create ModelRegistry singleton"""
+    global _registry
+    if _registry is None:
+        _registry = ModelRegistry()
+    return _registry
+
+
+def get_transcription_service() -> TranscriptionService:
+    """Get or create TranscriptionService singleton"""
+    global _transcription_service
+    if _transcription_service is None:
+        registry = get_registry()
+        _transcription_service = TranscriptionService(registry, keep_alive_seconds=300)
+    return _transcription_service
+
+
+def get_model_service() -> ModelService:
+    """Get or create ModelService singleton"""
+    global _model_service
+    if _model_service is None:
+        registry = get_registry()
+        _model_service = ModelService(registry)
+    return _model_service
+
+
+def get_tts_service() -> TTSService:
+    """Get or create TTSService singleton"""
+    global _tts_service
+    if _tts_service is None:
+        registry = get_registry()
+        _tts_service = TTSService(registry, keep_alive_seconds=300)
+    return _tts_service

vocal_api-0.3.0/vocal_api/main.py

@@ -0,0 +1,75 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.openapi.utils import get_openapi
+
+from .config import settings
+from .dependencies import get_transcription_service, get_tts_service
+from .routes import models_router, system_router, transcription_router, tts_router
+
+app = FastAPI(
+    title="Vocal API",
+    description="Generic Speech AI Platform (STT + TTS)",
+    version=settings.VERSION,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(transcription_router)
+app.include_router(models_router)
+app.include_router(tts_router)
+app.include_router(system_router)
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize services and start background tasks"""
+    transcription_service = get_transcription_service()
+    await transcription_service.start_cleanup_task()
+
+    tts_service = get_tts_service()
+    await tts_service.start_cleanup_task()
+
+
+@app.get("/", tags=["health"])
+async def root():
+    """API health check"""
+    return {
+        "status": "ok",
+        "message": "Vocal API - Ollama-style voice model management",
+        "version": settings.VERSION,
+    }
+
+
+@app.get("/health", tags=["health"])
+async def health():
+    """Detailed health check"""
+    return {
+        "status": "healthy",
+        "api_version": settings.VERSION,
+    }
+
+
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title="Vocal API",
+        version=settings.VERSION,
+        description="Generic Speech AI Platform (STT + TTS)",
+        routes=app.routes,
+    )
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+
+app.openapi = custom_openapi

vocal_api-0.3.0/vocal_api/routes/__init__.py

@@ -0,0 +1,11 @@
+from .models import router as models_router
+from .system import router as system_router
+from .transcription import router as transcription_router
+from .tts import tts_router
+
+__all__ = [
+    "transcription_router",
+    "models_router",
+    "tts_router",
+    "system_router",
+]

vocal_api-0.3.0/vocal_api/routes/models.py

@@ -0,0 +1,122 @@
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+
+from ..dependencies import get_model_service
+from ..models.model import (
+    ModelDownloadProgress,
+    ModelInfo,
+    ModelListResponse,
+)
+from ..services import ModelService
+
+router = APIRouter(prefix="/v1/models", tags=["models"])
+
+
+@router.get(
+    "",
+    response_model=ModelListResponse,
+    summary="List models",
+    description="List all available models (Ollama-style)",
+)
+async def list_models(
+    status: str | None = None,
+    task: str | None = None,
+    service: ModelService = Depends(get_model_service),
+) -> ModelListResponse:
+    """
+    List all available models
+
+    Query params:
+    - status: Filter by status (available, downloading, not_downloaded)
+    - task: Filter by task (stt, tts)
+    """
+    models = await service.list_models(status_filter=status, task=task)
+    return ModelListResponse(models=models, total=len(models))
+
+
+@router.get(
+    "/{model_id:path}",
+    response_model=ModelInfo,
+    summary="Get model info",
+    description="Get detailed information about a specific model",
+)
+async def get_model(model_id: str, service: ModelService = Depends(get_model_service)) -> ModelInfo:
+    """Get detailed model information"""
+    model = await service.get_model(model_id)
+    if not model:
+        raise HTTPException(404, f"Model {model_id} not found")
+    return model
+
+
+@router.post(
+    "/{model_id:path}/download",
+    response_model=ModelDownloadProgress,
+    summary="Download model",
+    description="Download a model for local use (Ollama-style pull)",
+)
+async def download_model(
+    model_id: str,
+    background_tasks: BackgroundTasks,
+    service: ModelService = Depends(get_model_service),
+) -> ModelDownloadProgress:
+    """
+    Start downloading a model
+
+    Returns immediately with initial status.
+    Check progress with GET /models/{model_id}/download/status
+    """
+    model = await service.get_model(model_id)
+    if not model:
+        raise HTTPException(404, f"Model {model_id} not found")
+
+    async def download_task():
+        async for progress in service.download_model(model_id):
+            pass
+
+    background_tasks.add_task(download_task)
+
+    return ModelDownloadProgress(
+        model_id=model_id,
+        status="downloading",
+        progress=0.0,
+        downloaded_bytes=0,
+        total_bytes=0,
+        message="Starting download...",
+    )
+
+
+@router.get(
+    "/{model_id:path}/download/status",
+    response_model=ModelDownloadProgress,
+    summary="Get download status",
+)
+async def get_download_status(model_id: str, service: ModelService = Depends(get_model_service)) -> ModelDownloadProgress:
+    """Check model download progress"""
+    status = await service.get_download_status(model_id)
+    if not status:
+        model = await service.get_model(model_id)
+        if not model:
+            raise HTTPException(404, f"Model {model_id} not found")
+
+        if model.status == "available":
+            return ModelDownloadProgress(
+                model_id=model_id,
+                status="available",
+                progress=1.0,
+                downloaded_bytes=model.size,
+                total_bytes=model.size,
+                message="Model already downloaded",
+            )
+
+        raise HTTPException(404, "No active download for this model")
+
+    return status
+
+
+@router.delete("/{model_id:path}", summary="Delete model", description="Remove a downloaded model")
+async def delete_model(model_id: str, service: ModelService = Depends(get_model_service)):
+    """Delete a downloaded model"""
+    success = await service.delete_model(model_id)
+    if not success:
+        raise HTTPException(404, f"Model {model_id} not found or not downloaded")
+
+    return {"status": "deleted", "model_id": model_id}

vocal_api-0.3.0/vocal_api/routes/system.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter
+
+from vocal_core.utils import get_device_info
+
+router = APIRouter(prefix="/v1/system", tags=["system"])
+
+
+@router.get("/device")
+async def get_device():
+    """
+    Get device and hardware information
+
+    Returns information about available compute devices (CPU, GPU)
+    and optimization settings being used.
+    """
+    return get_device_info()

vocal_api-0.3.0/vocal_api/routes/transcription.py

@@ -0,0 +1,81 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+
+from ..config import settings
+from ..dependencies import get_transcription_service
+from ..models.transcription import (
+    TranscriptionFormat,
+    TranscriptionRequest,
+    TranscriptionResponse,
+)
+from ..services import TranscriptionService
+
+router = APIRouter(prefix="/v1/audio", tags=["transcription"])
+
+
+@router.post(
+    "/transcriptions",
+    response_model=TranscriptionResponse,
+    summary="Transcribe audio",
+    description="Transcribe audio file to text using specified model",
+)
+async def create_transcription(
+    file: Annotated[UploadFile, File(description="Audio file to transcribe")],
+    model: Annotated[str, Form(description="Model ID")] = "Systran/faster-whisper-tiny",
+    language: Annotated[str | None, Form(description="Language code")] = None,
+    prompt: Annotated[str | None, Form(description="Style prompt")] = None,
+    response_format: Annotated[TranscriptionFormat, Form(description="Output format")] = TranscriptionFormat.JSON,
+    temperature: Annotated[float, Form(ge=0.0, le=1.0)] = 0.0,
+    service: TranscriptionService = Depends(get_transcription_service),
+) -> TranscriptionResponse:
+    """
+    Transcribe an audio file.
+
+    **Supported formats:** mp3, mp4, wav, m4a, flac, ogg, webm
+    **Max file size:** 25MB
+
+    Returns transcription with optional word/segment timestamps.
+    """
+    file.file.seek(0, 2)
+    size = file.file.tell()
+    file.file.seek(0)
+
+    if size > settings.MAX_UPLOAD_SIZE:
+        raise HTTPException(400, f"File too large. Max {settings.MAX_UPLOAD_SIZE // (1024 * 1024)}MB.")
+
+    request = TranscriptionRequest(
+        model=model,
+        language=language,
+        prompt=prompt,
+        response_format=response_format,
+        temperature=temperature,
+    )
+
+    try:
+        result = await service.transcribe(file, request)
+        return result
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+    except Exception as e:
+        raise HTTPException(500, f"Transcription failed: {str(e)}")
+
+
+@router.post(
+    "/translations",
+    response_model=TranscriptionResponse,
+    summary="Translate audio to English",
+    description="Translate audio to English text",
+)
+async def create_translation(
+    file: Annotated[UploadFile, File()],
+    model: Annotated[str, Form()] = "Systran/faster-whisper-tiny",
+    service: TranscriptionService = Depends(get_transcription_service),
+) -> TranscriptionResponse:
+    """Translate audio to English."""
+    try:
+        return await service.translate(file, model)
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+    except Exception as e:
+        raise HTTPException(500, f"Translation failed: {str(e)}")

vocal_api-0.3.0/vocal_api/routes/tts.py

@@ -0,0 +1,98 @@
+from fastapi import APIRouter, Depends, HTTPException, Response
+from pydantic import BaseModel, Field
+
+from ..dependencies import get_tts_service
+from ..services.tts_service import TTSService
+
+router = APIRouter(prefix="/v1/audio", tags=["audio"])
+
+
+class TTSRequest(BaseModel):
+    """Text-to-Speech request (OpenAI-compatible)"""
+
+    model: str = Field(..., description="TTS model to use (e.g., 'hexgrad/Kokoro-82M')")
+    input: str = Field(..., description="The text to synthesize")
+    voice: str | None = Field(None, description="Voice ID to use")
+    speed: float = Field(1.0, ge=0.25, le=4.0, description="Speech speed multiplier")
+    response_format: str = Field("wav", description="Audio format (currently only 'wav' supported)")
+
+
+class VoiceInfo(BaseModel):
+    """Voice information"""
+
+    id: str
+    name: str
+    language: str
+    gender: str | None = None
+
+
+class VoicesResponse(BaseModel):
+    """Response containing list of voices"""
+
+    voices: list[VoiceInfo]
+    total: int
+
+
+@router.post(
+    "/speech",
+    response_class=Response,
+    responses={200: {"content": {"audio/wav": {}}, "description": "Audio file in WAV format"}},
+)
+async def text_to_speech(request: TTSRequest, service: TTSService = Depends(get_tts_service)):
+    """
+    Generate speech from text (OpenAI-compatible endpoint)
+
+    This endpoint synthesizes audio from text using the specified TTS model.
+
+    - **model**: TTS model to use (e.g., 'hexgrad/Kokoro-82M', 'coqui/XTTS-v2')
+    - **input**: The text to convert to speech
+    - **voice**: Optional voice ID (use /v1/audio/voices to list available voices)
+    - **speed**: Speech speed multiplier (0.25 to 4.0, default: 1.0)
+    - **response_format**: Audio format (currently only 'wav' supported)
+    """
+    try:
+        result = await service.synthesize(
+            model_id=request.model,
+            text=request.input,
+            voice=request.voice,
+            speed=request.speed,
+            output_format=request.response_format,
+        )
+
+        return Response(
+            content=result.audio_data,
+            media_type=f"audio/{result.format}",
+            headers={
+                "Content-Disposition": f"attachment; filename=speech.{result.format}",
+                "X-Duration": str(result.duration),
+                "X-Sample-Rate": str(result.sample_rate),
+            },
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"TTS error: {str(e)}")
+
+
+@router.get("/voices", response_model=VoicesResponse)
+async def list_voices(model: str | None = None, service: TTSService = Depends(get_tts_service)):
+    """
+    List available TTS voices
+
+    Returns a list of all available voices that can be used for speech synthesis.
+
+    - **model**: Optional model ID to list voices for a specific model
+    """
+    try:
+        voices = await service.get_voices(model_id=model)
+
+        voice_infos = [VoiceInfo(id=v.id, name=v.name, language=v.language, gender=v.gender) for v in voices]
+
+        return VoicesResponse(voices=voice_infos, total=len(voice_infos))
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to list voices: {str(e)}")
+
+
+tts_router = router

vocal_api-0.3.0/vocal_api/services/__init__.py

@@ -0,0 +1,9 @@
+from .model_service import ModelService
+from .transcription_service import TranscriptionService
+from .tts_service import TTSService
+
+__all__ = [
+    "TranscriptionService",
+    "ModelService",
+    "TTSService",
+]

vocal_api-0.3.0/vocal_api/services/model_service.py

@@ -0,0 +1,96 @@
+from collections.abc import AsyncIterator
+
+from vocal_core import ModelRegistry
+
+from ..models.model import (
+    ModelDownloadProgress,
+    ModelInfo,
+)
+
+
+class ModelService:
+    """Service for managing models"""
+
+    def __init__(self, registry: ModelRegistry):
+        self.registry = registry
+        self._download_status: dict[str, ModelDownloadProgress] = {}
+
+    async def list_models(self, status_filter: str | None = None, task: str | None = None) -> list[ModelInfo]:
+        """List all available models"""
+        models = await self.registry.list_models(task=task, status_filter=status_filter)
+
+        return [self._convert_model_info(m) for m in models]
+
+    async def get_model(self, model_id: str) -> ModelInfo | None:
+        """Get model information"""
+        model = await self.registry.get_model(model_id)
+        if not model:
+            return None
+        return self._convert_model_info(model)
+
+    async def download_model(self, model_id: str, quantization: str | None = None) -> AsyncIterator[ModelDownloadProgress]:
+        """Download a model"""
+        self._download_status[model_id] = ModelDownloadProgress(
+            model_id=model_id,
+            status="downloading",
+            progress=0.0,
+            downloaded_bytes=0,
+            total_bytes=0,
+            message="Starting download...",
+        )
+
+        try:
+            async for downloaded, total, status in self.registry.download_model(model_id, quantization=quantization):
+                progress = (downloaded / total) if total > 0 else 0.0
+
+                self._download_status[model_id] = ModelDownloadProgress(
+                    model_id=model_id,
+                    status=status.value,
+                    progress=progress,
+                    downloaded_bytes=downloaded,
+                    total_bytes=total,
+                    message=f"Downloaded {downloaded}/{total} bytes",
+                )
+
+                yield self._download_status[model_id]
+
+        except Exception as e:
+            self._download_status[model_id] = ModelDownloadProgress(
+                model_id=model_id,
+                status="error",
+                progress=0.0,
+                downloaded_bytes=0,
+                total_bytes=0,
+                message=f"Download failed: {str(e)}",
+            )
+            yield self._download_status[model_id]
+
+    async def get_download_status(self, model_id: str) -> ModelDownloadProgress | None:
+        """Get download status for a model"""
+        return self._download_status.get(model_id)
+
+    async def delete_model(self, model_id: str) -> bool:
+        """Delete a downloaded model"""
+        return await self.registry.delete_model(model_id)
+
+    def _convert_model_info(self, model) -> ModelInfo:
+        """Convert core ModelInfo to API ModelInfo"""
+        return ModelInfo(
+            id=model.id,
+            name=model.name,
+            provider=model.provider.value,
+            description=model.description,
+            size=model.size,
+            size_readable=model.size_readable,
+            parameters=model.parameters,
+            languages=model.languages,
+            backend=model.backend.value,
+            status=model.status.value,
+            source_url=model.source_url,
+            license=model.license,
+            recommended_vram=model.recommended_vram,
+            task=model.task.value,
+            local_path=model.local_path,
+            created_at=model.created_at,
+            updated_at=model.updated_at,
+        )

vocal_api-0.3.0/vocal_api/services/transcription_service.py

@@ -0,0 +1,196 @@
+import asyncio
+import tempfile
+import time
+from pathlib import Path
+
+import aiofiles
+from fastapi import UploadFile
+
+from vocal_core import FasterWhisperAdapter, ModelRegistry, TranscriptionResult
+
+from ..models.transcription import (
+    TranscriptionRequest,
+    TranscriptionResponse,
+    TranscriptionSegment,
+    TranscriptionWord,
+)
+
+
+class TranscriptionService:
+    """Service for handling transcription requests with Ollama-style keep-alive"""
+
+    def __init__(self, registry: ModelRegistry, keep_alive_seconds: int = 300):
+        self.registry = registry
+        self.adapters: dict[str, FasterWhisperAdapter] = {}
+        self.last_used: dict[str, float] = {}
+        self.keep_alive_seconds = keep_alive_seconds
+        self._cleanup_task = None
+
+    async def start_cleanup_task(self):
+        """Start background task to cleanup unused models"""
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+    async def _cleanup_loop(self):
+        """Background task to unload models after keep_alive expires"""
+        while True:
+            try:
+                await asyncio.sleep(60)
+                current_time = time.time()
+                models_to_unload = []
+
+                for model_id, last_used_time in self.last_used.items():
+                    if current_time - last_used_time > self.keep_alive_seconds:
+                        models_to_unload.append(model_id)
+
+                for model_id in models_to_unload:
+                    if model_id in self.adapters:
+                        adapter = self.adapters[model_id]
+                        await adapter.unload_model()
+                        del self.adapters[model_id]
+                        del self.last_used[model_id]
+
+            except Exception:
+                pass
+
+    async def transcribe(self, file: UploadFile, request: TranscriptionRequest) -> TranscriptionResponse:
+        """
+        Transcribe audio file
+
+        Args:
+            file: Uploaded audio file
+            request: Transcription parameters
+
+        Returns:
+            TranscriptionResponse with text and metadata
+        """
+        model_id = request.model
+
+        model_info = await self.registry.get_model(model_id)
+        if not model_info:
+            raise ValueError(f"Model {model_id} not found in registry")
+
+        model_path = self.registry.get_model_path(model_id)
+
+        if not model_path:
+            raise ValueError(f"Model {model_id} not downloaded. Download it first: POST /v1/models/{model_id}/download")
+
+        adapter = await self._get_or_create_adapter(model_id, model_path)
+        self.last_used[model_id] = time.time()
+
+        temp_file = None
+        temp_path = None
+        try:
+            temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".audio")
+            temp_path = temp_file.name
+            temp_file.close()
+
+            content = await file.read()
+
+            async with aiofiles.open(temp_path, "wb") as f:
+                await f.write(content)
+
+            word_timestamps = "word" in request.timestamp_granularities
+
+            result = await adapter.transcribe(
+                audio=temp_path,
+                language=request.language,
+                task="transcribe",
+                temperature=request.temperature,
+                word_timestamps=word_timestamps,
+            )
+
+            return self._convert_result(result)
+
+        finally:
+            if temp_path and Path(temp_path).exists():
+                Path(temp_path).unlink()
+
+    async def translate(self, file: UploadFile, model_id: str) -> TranscriptionResponse:
+        """
+        Translate audio to English
+
+        Args:
+            file: Uploaded audio file
+            model_id: Model to use
+
+        Returns:
+            TranscriptionResponse with translated text
+        """
+        model_path = self.registry.get_model_path(model_id)
+        if not model_path:
+            raise ValueError(f"Model {model_id} not downloaded")
+
+        adapter = await self._get_or_create_adapter(model_id, model_path)
+        self.last_used[model_id] = time.time()
+
+        temp_file = None
+        temp_path = None
+        try:
+            temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".audio")
+            temp_path = temp_file.name
+            temp_file.close()
+
+            content = await file.read()
+
+            async with aiofiles.open(temp_path, "wb") as f:
+                await f.write(content)
+
+            result = await adapter.transcribe(
+                audio=temp_path,
+                task="translate",
+            )
+
+            return self._convert_result(result)
+
+        finally:
+            if temp_path and Path(temp_path).exists():
+                Path(temp_path).unlink()
+
+    async def _get_or_create_adapter(self, model_id: str, model_path: Path) -> FasterWhisperAdapter:
+        """Get or create adapter for model"""
+        if model_id not in self.adapters:
+            adapter = FasterWhisperAdapter()
+            await adapter.load_model(model_path)
+            self.adapters[model_id] = adapter
+
+        return self.adapters[model_id]
+
+    def _convert_result(self, result: TranscriptionResult) -> TranscriptionResponse:
+        """Convert core TranscriptionResult to API TranscriptionResponse"""
+        segments = None
+        if result.segments:
+            segments = [
+                TranscriptionSegment(
+                    id=seg.id,
+                    start=seg.start,
+                    end=seg.end,
+                    text=seg.text,
+                    tokens=seg.tokens,
+                    temperature=seg.temperature,
+                    avg_logprob=seg.avg_logprob,
+                    compression_ratio=seg.compression_ratio,
+                    no_speech_prob=seg.no_speech_prob,
+                )
+                for seg in result.segments
+            ]
+
+        words = None
+        if result.words:
+            words = [
+                TranscriptionWord(
+                    word=w.word,
+                    start=w.start,
+                    end=w.end,
+                    probability=w.probability,
+                )
+                for w in result.words
+            ]
+
+        return TranscriptionResponse(
+            text=result.text,
+            language=result.language,
+            duration=result.duration,
+            segments=segments,
+            words=words,
+        )

vocal_api-0.3.0/vocal_api/services/tts_service.py

@@ -0,0 +1,139 @@
+import asyncio
+import time
+from pathlib import Path
+
+from vocal_core import ModelRegistry
+from vocal_core.adapters.tts import SimpleTTSAdapter, TTSAdapter, TTSResult, Voice
+
+
+class TTSService:
+    """Service for handling TTS operations with Ollama-style keep-alive"""
+
+    def __init__(self, registry: ModelRegistry, keep_alive_seconds: int = 300):
+        self.registry = registry
+        self.adapters: dict[str, TTSAdapter] = {}
+        self.last_used: dict[str, float] = {}
+        self.keep_alive_seconds = keep_alive_seconds
+        self._cleanup_task = None
+
+    async def start_cleanup_task(self):
+        """Start background task to cleanup unused models"""
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+    async def _cleanup_loop(self):
+        """Background task to unload models after keep_alive expires"""
+        while True:
+            try:
+                await asyncio.sleep(60)
+                current_time = time.time()
+                models_to_unload = []
+
+                for model_id, last_used_time in self.last_used.items():
+                    if current_time - last_used_time > self.keep_alive_seconds:
+                        models_to_unload.append(model_id)
+
+                for model_id in models_to_unload:
+                    if model_id in self.adapters:
+                        adapter = self.adapters[model_id]
+                        if hasattr(adapter, "unload_model"):
+                            await adapter.unload_model()
+                        del self.adapters[model_id]
+                        del self.last_used[model_id]
+
+            except Exception:
+                pass
+
+    async def synthesize(
+        self,
+        model_id: str,
+        text: str,
+        voice: str | None = None,
+        speed: float = 1.0,
+        output_format: str = "wav",
+    ) -> TTSResult:
+        """
+        Synthesize text to speech using specified model
+
+        Args:
+            model_id: TTS model identifier (use "pyttsx3" for system TTS)
+            text: Text to convert to speech
+            voice: Voice ID to use
+            speed: Speech speed multiplier
+            output_format: Output audio format
+
+        Returns:
+            TTSResult with audio data
+        """
+        if model_id == "pyttsx3":
+            adapter = await self._get_or_create_simple_adapter()
+            self.last_used[model_id] = time.time()
+            return await adapter.synthesize(text=text, voice=voice, speed=speed, output_format=output_format)
+
+        model_info = await self.registry.get_model(model_id)
+        if not model_info:
+            raise ValueError(f"Model {model_id} not found in registry")
+
+        if model_info.task.value != "tts":
+            raise ValueError(f"Model {model_id} is not a TTS model (task: {model_info.task})")
+
+        model_path = self.registry.get_model_path(model_id)
+
+        if not model_path:
+            raise ValueError(f"Model {model_id} not downloaded. Download it first: POST /v1/models/{model_id}/download")
+
+        adapter = await self._get_or_create_adapter(model_id, model_path, model_info.backend.value)
+        self.last_used[model_id] = time.time()
+
+        return await adapter.synthesize(text=text, voice=voice, speed=speed, output_format=output_format)
+
+    async def get_voices(self, model_id: str | None = None) -> list[Voice]:
+        """
+        Get list of available voices
+
+        Args:
+            model_id: Optional model ID to get voices for specific model
+
+        Returns:
+            List of Voice objects
+        """
+        if not model_id or model_id == "pyttsx3":
+            adapter = await self._get_or_create_simple_adapter()
+            self.last_used["pyttsx3"] = time.time()
+            return await adapter.get_voices()
+
+        model_path = self.registry.get_model_path(model_id)
+        if not model_path:
+            raise ValueError(f"Model {model_id} not downloaded")
+
+        model_info = await self.registry.get_model(model_id)
+        if not model_info:
+            raise ValueError(f"Model {model_id} not found")
+
+        adapter = await self._get_or_create_adapter(model_id, model_path, model_info.backend.value)
+        self.last_used[model_id] = time.time()
+        return await adapter.get_voices()
+
+    async def _get_or_create_simple_adapter(self) -> SimpleTTSAdapter:
+        """Get or create the simple system TTS adapter"""
+        if "pyttsx3" not in self.adapters:
+            adapter = SimpleTTSAdapter()
+            await adapter.load_model(Path("."))
+            self.adapters["pyttsx3"] = adapter
+        return self.adapters["pyttsx3"]
+
+    async def _get_or_create_adapter(self, model_id: str, model_path: Path, backend: str) -> TTSAdapter:
+        """Get or create TTS adapter for model"""
+        if model_id not in self.adapters:
+            adapter = self._create_adapter(backend)
+            await adapter.load_model(model_path)
+            self.adapters[model_id] = adapter
+
+        return self.adapters[model_id]
+
+    def _create_adapter(self, backend: str) -> TTSAdapter:
+        """Create appropriate TTS adapter based on backend"""
+        if backend in ("onnx", "custom"):
+            return SimpleTTSAdapter()
+        else:
+            return SimpleTTSAdapter()