voxkit.engines

  1"""Engines are speech toolkit backends. Each engine provides one or more tools
  2where each tool is a unit of functionality (e.g. alignment, training, transcription).
  3
  4API
  5---
  6- **EngineManager.list_engines**: List registered engine IDs
  7- **EngineManager.get_engine**: Retrieve engine instance by ID
  8- **EngineManager.get_tool_providers**: Get engines providing a specific tool type
  9- **AVAILABLE_TOOLS**: Literal type for compatible tool types
 10
 11Available Engines
 12-----------------
 13**MFAEngine**
 14    Montreal Forced Aligner integration. Provides alignment using pretrained
 15    acoustic models and training via model adaptation.
 16    Tools: ``alignment``, ``training``
 17
 18**W2TGEngine**
 19    Wav2TextGrid integration using Wav2Vec 2.0 models.
 20    Tools: ``alignment``, ``training``
 21
 22**FasterWhisperEngine**
 23    Faster-Whisper integration for transcription. Produces .lab transcript files
 24    from audio using CTranslate2 backend.
 25    Tools: ``transcription``
 26
 27Storage Structure
 28-----------------
 29Engine settings and models are stored under the engine's directory::
 30
 31    ~/.voxkit/{engine_id}/
 32    ├── aligner/
 33    │   └── aligner_settings.json
 34    ├── train/
 35    │   ├── trainer_settings.json
 36    │   └── {model_id}/
 37    └── transcribe/
 38        └── transcriber_settings.json
 39
 40Notes
 41-----
 42- Each engine's ``id`` property serves as its unique identifier
 43- Tools are configured via ``SettingsConfig`` objects with UI field definitions
 44- Settings are persisted to JSON and validated before use
 45"""
 46
 47from __future__ import annotations
 48
 49from typing import List
 50
 51from .base import AlignmentEngine
 52from .constants import AVAILABLE_TOOLS
 53from .faster_whisper_engine import FasterWhisperEngine
 54from .mfa_engine import MFAEngine
 55from .w2tg_engine import W2TGEngine
 56
 57
 58class EngineManager:
 59    """
 60    Manager class for registered engines.
 61
 62    Provides a unified interface to list and retrieve engines.
 63
 64    Methods:
 65        list_engines(): Return a list of registered engine IDs.
 66        get_engine(engine_id): Retrieve an engine by ID.
 67        get_tool_providers(tool): Return a list of engines that provide the specified tool type.
 68    """
 69
 70    def __init__(self, engines: dict[str, AlignmentEngine]):
 71        self._engines = engines
 72
 73    def list_engines(self) -> List[str]:
 74        """Return a list of registered engine IDs."""
 75        keys = list(self._engines.keys())
 76        return keys
 77
 78    def get_engine(self, engine_id: str) -> AlignmentEngine:
 79        """Return the registered engine instance for the given ID."""
 80        try:
 81            return self._engines[engine_id]
 82        except KeyError:
 83            raise ValueError(f"No engine with id: {engine_id}")
 84
 85    def get_tool_providers(self, tool: AVAILABLE_TOOLS) -> dict[str, AlignmentEngine]:
 86        """Return a list of engines that provide the specified tool type."""
 87        engines = {}
 88        for _, engine in self._engines.items():
 89            if engine.has_tool(tool):
 90                engines[engine.id] = engine
 91        return engines
 92
 93
 94# Singleton instance for unified export/interface
 95w2tg = W2TGEngine(id="W2TGENGINE")
 96mfa = MFAEngine(id="MFAENGINE")
 97faster_whisper = FasterWhisperEngine(id="FASTERWHISPERENGINE")
 98engines = EngineManager({mfa.id: mfa, faster_whisper.id: faster_whisper, w2tg.id: w2tg})
 99
100__all__ = ["engines", "AVAILABLE_TOOLS"]