Metadata-Version: 2.4
Name: cjm-transcription-plugin-system
Version: 0.0.34
Summary: A flexible plugin system for audio transcription intended to make it easy to add support for multiple backends.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-transcription-plugin-system
Project-URL: Documentation, https://cj-mills.github.io/cjm-transcription-plugin-system
Keywords: nbdev,jupyter,notebook,python
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cjm_plugin_system>=0.0.45
Requires-Dist: cjm_transcription_adapter_interface>=0.0.7
Requires-Dist: cjm_forced_alignment_adapter_interface>=0.0.7
Dynamic: license-file

# cjm-transcription-plugin-system


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_transcription_plugin_system
```

## Project Structure

    nbs/
    ├── core.ipynb                       # REMOVE-AFTER-OVERHAUL(option-c-cascade): class-identical legacy
    ├── forced_alignment_core.ipynb      # REMOVE-AFTER-OVERHAUL(option-c-cascade): class-identical legacy
    ├── forced_alignment_interface.ipynb # Domain-specific plugin interface for word-level audio-text alignment
    ├── forced_alignment_storage.ipynb   # REMOVE-AFTER-OVERHAUL(option-c-cascade): class-identical legacy
    ├── plugin_interface.ipynb           # Domain-specific plugin interface for audio transcription
    └── storage.ipynb                    # REMOVE-AFTER-OVERHAUL(option-c-cascade): class-identical legacy

Total: 6 notebooks

## Module Dependencies

``` mermaid
graph LR
    core["core<br/>Core Data Structures (compat shim)"]
    forced_alignment_core["forced_alignment_core<br/>Forced Alignment Core (compat shim)"]
    forced_alignment_interface["forced_alignment_interface<br/>Forced Alignment Plugin Interface"]
    forced_alignment_storage["forced_alignment_storage<br/>Forced Alignment Storage (compat shim)"]
    plugin_interface["plugin_interface<br/>Transcription Plugin Interface"]
    storage["storage<br/>Transcription Storage (compat shim)"]

    forced_alignment_interface --> forced_alignment_core
    plugin_interface --> core
```

*2 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Forced Alignment Plugin Interface (`forced_alignment_interface.ipynb`)

> Domain-specific plugin interface for word-level audio-text alignment

#### Import

``` python
from cjm_transcription_plugin_system.forced_alignment_interface import (
    ForcedAlignmentPlugin
)
```

#### Classes

``` python
class ForcedAlignmentPlugin(PluginInterface):
    """
    Abstract base class for all forced alignment plugins.
    
    Extends PluginInterface with forced-alignment-specific requirements:
    - `supported_formats`: List of audio file extensions this plugin can handle
    - `execute`: Accepts an audio file path and transcript text, returns ForcedAlignResult
    
    Input contract: plugins receive a path to a decodable audio file. Producing a
    model-ready file (format / sample-rate / channel normalization) is the caller's
    responsibility — e.g. an upstream ffmpeg step in the orchestration pipeline —
    not the plugin's. This keeps the interface library dependency-light.
    """
    
    def supported_formats(self) -> List[str]:  # e.g., ['wav', 'mp3', 'flac']
            """List of supported audio file extensions (without the dot)."""
            ...
    
        @abstractmethod
        def execute(
            self,
            audio: Union[str, Path],  # Path to a decodable audio file
            text: str,                # Transcript text to align against
            **kwargs
        ) -> ForcedAlignResult:  # Word-level alignment result
        "List of supported audio file extensions (without the dot)."
    
    def execute(
            self,
            audio: Union[str, Path],  # Path to a decodable audio file
            text: str,                # Transcript text to align against
            **kwargs
        ) -> ForcedAlignResult:  # Word-level alignment result
        "Perform forced alignment of text against audio.

`audio` is a path to a decodable audio file; the caller guarantees it is in
a form the plugin/model can consume."
```

### Transcription Plugin Interface (`plugin_interface.ipynb`)

> Domain-specific plugin interface for audio transcription

#### Import

``` python
from cjm_transcription_plugin_system.plugin_interface import (
    TranscriptionPlugin
)
```

#### Classes

``` python
class TranscriptionPlugin(PluginInterface):
    """
    Abstract base class for all transcription plugins.
    
    Extends PluginInterface with transcription-specific requirements:
    - `supported_formats`: List of audio file extensions this plugin can handle
    - `execute`: Accepts an audio file path (str or Path), returns TranscriptionResult
    
    Input contract: plugins receive a path to a decodable audio file. Producing a
    model-ready file (format / sample-rate / channel normalization) is the caller's
    responsibility — e.g. an upstream ffmpeg step in the orchestration pipeline —
    not the plugin's. This keeps the interface library dependency-light (no audio
    I/O deps such as numpy/soundfile in the shared consumer environment).
    """
    
    def supported_formats(self) -> List[str]: # e.g., ['wav', 'mp3', 'flac']
            """List of supported audio file extensions (without the dot)."""
            ...
    
        @abstractmethod
        def execute(
            self,
            audio: Union[str, Path], # Path to a decodable audio file
            **kwargs
        ) -> TranscriptionResult: # Transcription result with text, confidence, segments
        "List of supported audio file extensions (without the dot)."
    
    def execute(
            self,
            audio: Union[str, Path], # Path to a decodable audio file
            **kwargs
        ) -> TranscriptionResult: # Transcription result with text, confidence, segments
        "Transcribe audio to text.

`audio` is a path to a decodable audio file; the caller guarantees it is in
a form the plugin/model can consume."
```
