stt/README.md

# STT Module

Модуль транскрибации речи в текст (Speech-to-Text) на базе Whisper.

## Структура

```
stt/
├── __init__.py              # Экспорты модуля
├── whisper_transcriber.py   # Основной класс транскрибера
├── audio_processor.py       # Обработка аудио
└── README.md                # Документация
```

## WhisperTranscriber

Основной класс для транскрибации медицинских диктовок.

### Возможности

- ✅ Поддержка GPU/CPU
- ✅ Локальные модели Whisper
- ✅ Медицинские промпты для улучшения точности
- ✅ Различные форматы аудио (wav, mp3, flac и др.)
- ✅ Временные метки (timestamps)
- ✅ Автоматический выбор устройства

## Примеры использования

### Базовая транскрибация

```python
from stt import WhisperTranscriber
from pathlib import Path

# Инициализация
transcriber = WhisperTranscriber(
    model_path=Path("./"),  # путь к папке с моделью
    device="auto",          # auto, cuda, cpu
    dtype="float32",        # float32, float16, bfloat16
    language="russian"
)

# Транскрибация файла
result = transcriber.transcribe_file(
    audio_path=Path("audio.wav")
)

print(f"Текст: {result['text']}")
```

### С медицинским промптом

```python
from stt import WhisperTranscriber
from knowledge_base import MedicalTermManager

# Загружаем медицинские термины
term_manager = MedicalTermManager("medical_terms.txt")
medical_prompt = term_manager.get_terms_as_text()

# Инициализация транскрибера
transcriber = WhisperTranscriber(model_path=Path("./"))

# Транскрибация с промптом
result = transcriber.transcribe_file(
    audio_path=Path("medical_dictation.wav"),
    medical_prompt=medical_prompt
)

print(result['text'])
```

### С временными метками

```python
result = transcriber.transcribe_file(
    audio_path=Path("audio.wav"),
    return_timestamps=True
)

print(f"Текст: {result['text']}")
print(f"Временные метки:")
for chunk in result['timestamps']:
    print(f"  {chunk['timestamp']}: {chunk['text']}")
```

### Обработка аудио

```python
from stt import load_audio, resample_audio, get_audio_duration

# Загрузка аудио
audio = load_audio(Path("audio.wav"), sr=16000)

# Получить длительность
duration = get_audio_duration(audio, sr=16000)
print(f"Длительность: {duration:.2f} сек")

# Ресемплинг
audio_resampled = resample_audio(audio, orig_sr=16000, target_sr=8000)
```

### Информация о модели

```python
transcriber = WhisperTranscriber(model_path=Path("./"))
info = transcriber.get_model_info()

print(f"Модель: {info['model_path']}")
print(f"Устройство: {info['device']}")
print(f"CUDA доступна: {info['cuda_available']}")
if info['cuda_device_name']:
    print(f"GPU: {info['cuda_device_name']}")
```

## Интеграция с pipeline

```python
from stt import WhisperTranscriber
from knowledge_base import MedicalTermManager
from corrector import MedicalLLMCorrector

# Шаг 1: Загрузка медицинских терминов
term_manager = MedicalTermManager("medical_terms.txt")
medical_prompt = term_manager.get_terms_as_text()

# Шаг 2: STT транскрибация
transcriber = WhisperTranscriber(model_path=Path("./"))
stt_result = transcriber.transcribe_file(
    audio_path=Path("dictation.wav"),
    medical_prompt=medical_prompt
)

original_text = stt_result['text']
print(f"STT: {original_text}")

# Шаг 3: LLM коррекция
corrector = MedicalLLMCorrector()
corrector.medical_terms = medical_prompt
corrected_text, corrections = corrector.correct_transcription(original_text)

print(f"LLM: {corrected_text}")
print(f"Исправлений: {len(corrections)}")
```

## Параметры WhisperTranscriber

### __init__

- `model_path` (Path): Путь к папке с моделью Whisper
- `device` (str): Устройство для вычислений
  - `"auto"` - автоматический выбор (CUDA > MPS > CPU)
  - `"cuda"` - NVIDIA GPU
  - `"cpu"` - Процессор
- `dtype` (str): Тип данных
  - `"float32"` - полная точность (медленнее, но точнее)
  - `"float16"` - половинная точность (быстрее, GPU)
  - `"bfloat16"` - brain float (оптимально для новых GPU)
- `language` (str): Язык транскрибации (по умолчанию "russian")

### transcribe / transcribe_file

- `audio` / `audio_path`: Аудио данные или путь к файлу
- `medical_prompt` (Optional[str]): Медицинский промпт для улучшения точности
- `return_timestamps` (bool): Возвращать временные метки

## Audio Processor Functions

### load_audio(audio_path, sr=16000)

Загрузить аудио файл с автоматическим ресемплингом.

### resample_audio(audio, orig_sr, target_sr)

Изменить частоту дискретизации.

### get_audio_duration(audio, sr=16000)

Получить длительность аудио в секундах.

### validate_audio(audio_path)

Проверить валидность аудио файла.

## Поддерживаемые форматы аудио

- WAV
- MP3
- FLAC
- OGG
- M4A
- WMA

Все форматы автоматически конвертируются в нужную частоту дискретизации (16000 Hz).

## Требования

```
torch>=2.3.0
transformers>=4.44.0
librosa>=0.10.2
soundfile>=0.12.1
```

## Производительность

### GPU (CUDA)

- float16: ~10x быстрее CPU
- bfloat16: оптимально для A100/H100

### CPU

- float32: высокая точность, медленно
- Рекомендуется для небольших файлов

## Troubleshooting

### CUDA out of memory

Используйте `dtype="float16"` или уменьшите размер аудио.

### Низкая точность транскрибации

1. Добавьте медицинский промпт
2. Проверьте качество аудио
3. Используйте более крупную модель Whisper