mstt 0.2.0

mstt-A command-line tool and Python library for running speech-to-text against multiple models.

Modern Speech-to-Text (MSTT)

Modern Speech-to-Text (MSTT) is a Python library designed to provide a unified and extensible interface for various Speech-to-Text (STT) models. It aims to simplify the process of integrating different STT services and models into your applications, offering a consistent API regardless of the underlying STT engine.

Features

• Unified API: Interact with multiple STT models through a single, consistent interface.
• Extensible Design: Easily add support for new STT models and services.
• Local and Cloud Support: Seamlessly switch between local models and cloud-based STT APIs.
• Plugin System: Integrate custom STT models or enhance existing functionalities via a flexible plugin system.

Installation

To install MSTT, you can use pip:

pip install mstt

If you want to install with specific STT model backends, you can specify them as extras. For example, to install with funasr support:

pip install mstt[funasr]

Usage

Basic Transcription

Here's a basic example of how to use MSTT to transcribe an audio file:

from mstt import MSTT

# Initialize MSTT with a specific model (e.g., 'funasr')
# Ensure the 'mstt-funasr' package is installed if you use 'funasr'
mstt = MSTT(model_id="funasr")

# Transcribe an audio file
audio_file_path = "path/to/your/audio.wav"
result = mstt.transcribe(audio_file_path)

print(f"Transcription: {result.text}")
print(f"Segments: {result.segments}")

Available Models

MSTT supports various models through its plugin system. You can list available models:

from mstt import MSTT

available_models = MSTT.list_models()
print("Available STT Models:")
for model_id, description in available_models.items():
    print(f"- {model_id}: {description}")

Command Line Interface (CLI)

MSTT also provides a command-line interface for quick transcriptions:

mstt transcribe --model funasr --audio path/to/your/audio.wav

Run mstt --help for more CLI options.

Creating Custom Plugins

MSTT is designed to be extensible through a plugin system. You can create your own STT model plugins and register them with MSTT.

Plugin Structure

A plugin typically consists of:

1. A Model Implementation: A Python class that inherits from mstt.models.STTModel and implements the transcribe method.
2. A Registration Module: A Python module that registers your model with MSTT using the mstt.register_model decorator.

Example: A Simple Custom Plugin

Let's say you want to create a plugin for a hypothetical MyCustomSTT model. You would create a Python package (e.g., mstt_mycustom):

mstt_mycustom/
├── pyproject.toml
├── src/
│   └── mstt_mycustom/
│       ├── __init__.py
│       ├── models.py
│       └── register.py

src/mstt_mycustom/models.py:

from mstt.models import STTModel, TranscriptionResult

class MyCustomSTTModel(STTModel):
    def __init__(self, model_id: str, device: str = "cpu"):
        super().__init__(model_id, device)
        # Initialize your custom model here
        print(f"Initializing MyCustomSTTModel with ID: {model_id} on device: {device}")

    def transcribe(self, audio_file_path: str) -> TranscriptionResult:
        # Implement your transcription logic here
        # This is a placeholder for demonstration
        print(f"Transcribing {audio_file_path} using MyCustomSTTModel")
        dummy_text = "This is a custom transcription result."
        dummy_segments = [
            {"start": 0.0, "end": 2.0, "text": "This is a custom"},
            {"start": 2.1, "end": 4.0, "text": "transcription result."}
        ]
        return TranscriptionResult(text=dummy_text, segments=dummy_segments)

src/mstt_mycustom/register.py:

from mstt import register_model
from .models import MyCustomSTTModel

@register_model("mycustom")
def register_mycustom_model():
    return MyCustomSTTModel

pyproject.toml (important for plugin discovery):

[project.entry-points.mstt]
mycustom = "mstt_mycustom.register"

Installing Your Plugin

After setting up your plugin package, you can install it in editable mode for development:

pip install -e /path/to/your/mstt_mycustom

Or, if you package it, install it like any other Python package:

pip install mstt-mycustom

Once installed, MSTT will automatically discover and load your mycustom model, and you can use it like any other built-in model:

from mstt import MSTT

mstt = MSTT(model_id="mycustom")
result = mstt.transcribe("path/to/your/audio.wav")
print(result.text)

Contributing

We welcome contributions to MSTT! If you'd like to contribute, please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Write and run tests (pytest).
5. Commit your changes (git commit -am 'Add new feature').
6. Push to the branch (git push origin feature/your-feature-name).
7. Create a new Pull Request.

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.