Transcriber Service

Сервис расшифровки аудиозаписей. Два входа — Telegram-бот и HTTP API.

Возможности

• Приём аудио из Telegram: голосовые сообщения, аудиофайлы и документы с аудио
• Приём аудиофайлов через HTTP API
• Конвертация в ogg через ffmpeg
• Распознавание речи через Yandex SpeechKit
• Отслеживание статуса задач расшифровки
• SQLite для хранения метаданных, метрики Prometheus

Технологии

• Веб-фреймворк: gin-gonic/gin
• Telegram: go-telegram-bot-api
• Распознавание: Yandex SpeechKit + Yandex Object Storage (S3)
• Конвертация: ffmpeg
• SQL Builder: doug-martin/goqu
• Миграции БД: pressly/goose
• База данных: SQLite
• Метрики: prometheus/client_golang

Установка и запуск

1. Клонируйте репозиторий
2. Установите зависимости:

   go mod tidy
   

3. Скопируйте образец конфига и заполните его:

   cp config.dist.toml config.toml
   

4. Запустите приложение:

   go run . -c config.toml
   

Сервер запустится на порту из [server] port, по умолчанию 8080. Нужен установленный ffmpeg.

Белый список Telegram

Бот отвечает только тем, кто перечислен в конфиге. Кого и по какому признаку он пускает — docs/security.md, «Что разграничивает доступ»; известные прорехи образца конфига, включая недостающий ключ белого списка, — docs/conventions/config.md.

Деплой

Деплой запускается из pet-project-server:

inv pl -- transcriber

Плейбук сам зовёт task image (контракт роли app_image): образ собирается локально и едет на сервер через docker save/load, реестр не участвует. Локально образ можно собрать и руками — task image даст transcriber:dev.

HTTP API

Четыре маршрута: POST /api/audio — приём записи, GET /api/status/:id — готовность задачи, GET /metrics — метрики Prometheus с префиксом transcriber_, GET /health — проверка живости.

Контракт приёма и опроса нормативен и живёт в openspec/specs/intake/spec.md: поля запроса и ответа, коды и условия. Менять его — необратимое действие (CLAUDE.md, «Работа»), и второго описания у него быть не должно.

Состояния задач

Перечень состояний, переходы между ними и число воркеров — docs/database.md, разделы «Таблицы» и «Представление данных»; как сложен конвейер целиком — docs/architecture.md.

Структура проекта

transcriber/
├── main.go                 # Точка входа: конфиг, миграции, сборка зависимостей, запуск
├── internal/
│   ├── entity/             # Модели: задача, файл, результат распознавания
│   ├── contract/           # Интерфейсы адаптеров и репозиториев, типы ошибок
│   ├── config/             # Разбор config.toml
│   ├── metrics/            # Метрики Prometheus
│   ├── service/            # Конвейер расшифровки
│   ├── controller/
│   │   ├── http/           # HTTP-обработчики
│   │   ├── tg/             # Telegram-бот
│   │   └── worker/         # Фоновые воркеры
│   └── adapter/
│       ├── converter/ffmpeg/    # Конвертация аудио
│       ├── metaviewer/ffmpeg/   # Длительность аудио
│       ├── recognizer/yandex/   # SpeechKit + Object Storage
│       ├── telegram/            # Отправка сообщений
│       └── repo/sqlite/         # Репозитории
├── migrations/             # Миграции goose, вшиты в бинарник через go:embed
└── data/
    ├── files/              # Директория для сохранения файлов
    └── transcriber.db      # SQLite база данных (создается автоматически)

База данных

Две таблицы, files и transcribe_jobs. Колонки, ключи, правило времени и идентификаторов, а также механика захвата задачи воркером — docs/database.md.

Разработка

Миграции накатываются автоматически при старте сервиса — они вшиты в бинарник через //go:embed. Достаточно положить новый файл в migrations/.

Создать файл миграции и накатить или откатить её вручную:

# Создание новой миграции
goose -dir migrations create migration_name sql

# Применение миграций
goose -dir migrations sqlite3 data/transcriber.db up

# Откат миграций
goose -dir migrations sqlite3 data/transcriber.db down

Проверки перед коммитом — одной командой:

task gate

Что она гоняет, чем краснеет и какой отказ считается объявленным долгом — CLAUDE.md, раздел «Гейт».