transcriber/docs/passport.md

# Паспорт проекта

Зачем это и для кого. [architecture.md](architecture.md) отвечает «как
устроено», [tasks/ROADMAP.md](../tasks/ROADMAP.md) — «в каком порядке», паспорт —
«зачем и для кого».

## Цель

Превращать записанную речь в текст, который можно читать и искать, и хранить
этот текст вместе с записью.

**Сервис — архив, и это решено 2026-08-11.** Прежде граница читалась «отдаём
текст и на этом заканчиваем»; теперь расшифровки и исходные записи лежат
бессрочно, а список отбирается по темам. Причина в основном сценарии: семейный
архив загружают один раз, а возвращаются к нему годами.

**Потребители** — список закрытый: он определяет, что считать нужным, а что
интересным.

| Кто | Что ему нужно от нас |
| --- | --- |
| Владелец сервиса | Загрузить диктофонную запись или видео из семейного архива с телефона и получить текст. Видеть, кто сколько загрузил и во что это обошлось |
| Приглашённый пользователь | Войти в приложение через свою учётную запись, загрузить запись, забрать текст, вернуться к ней через месяц. Приложение ставится на телефон; каждый видит только свои записи |
| Пользователь Telegram | Отправить боту голосовое сообщение и получить текст ответом. Работает сегодня |
| Внешняя программа | Отдать файл по HTTP, представившись своим токеном, и опросить готовность. Работает сегодня, но токенов нет и доступ не разграничен |

**Основной вход — приложение**, бот и HTTP API дополняют его. До 2026-08-11
основным был бот, и порядок здесь перевёрнут сознательно: диктофонная запись на
несколько часов через Telegram не проходит вовсе.

Цель достигнута, когда:

- запись любого распространённого формата принимается без предварительной
  подготовки, включая дорожку из видео;
- запись длиной до шести часов доходит до текста, а не прерывается ошибкой при
  достижении предела;
- сервисом пользуются несколько человек, и записи одного не видны другому;
- текст доступен там же, где загружали, — в приложении и в Telegram. Человек
  узнаёт о его готовности, не держа приложение открытым;
- расшифровка не теряется: к записи возвращаются через месяц и находят её по
  заголовку и темам;
- владелец видит расход по каждому пользователю и понимает, во что обходится
  приглашение ещё одного человека.

## Что целью не является

Граница домена. По ней в теме `architecture` судят, не перенесено ли понятие
через границу.

- **Правка текста руками.** Машинную вычитку расшифровки отдаём — литературный
  текст стоит рядом с сырым, — а редактором не становимся: текст руками не
  правим, не размечаем и не экспортируем в форматы документов. Граница сдвинута
  2026-08-11: до того запрет читался «расшифровку отдаём как есть».
- **Разговор о записи.** Ответы на вопросы по содержанию и поиск по смыслу — за
  границей. Заголовок, пересказ и темы **внутри** границы: она сдвинута
  2026-08-10, и до того запись читалась «мы отдаём текст, а не выводы из него».
  Направление — цель [text-insights](../tasks/items/text-insights.md).
- **Собственные модели.** Не обучаем и не держим у себя ни модель распознавания,
  ни языковую модель: и речь, и выводы из текста считает внешний сервис.
- **Управление учётными записями.** Пользователей заводит и проверяет внешний
  провайдер, свою регистрацию и свои пароли не делаем. Одно исключение появилось
  2026-08-11 вместе с решением про PocketBase: в её панель администратора
  владелец входит своим паролем, потому что закрыть её провайдером она не
  умеет.
- **Живая расшифровка.** Работаем с готовой записью, поток в реальном времени не
  обрабатываем.
- **Диктофон.** Запись звука делает телефон, а приложение принимает готовый
  файл. Своей записи и работы без сети не делаем — граница цели
  [web-access](../tasks/items/web-access.md).
- **Файловое хранилище общего назначения.** Храним аудио и видео, отданные ради
  речи в них. Складом произвольных файлов, папками и общим доступом к чужим
  записям сервис не становится.
- **Учёт денег.** Считаем объём, минуты и токены по каждому пользователю и
  показываем их владельцу. Цен, счетов и отказов по исчерпании квоты не делаем:
  пользователя, потратившего слишком много, останавливает разговор или отзыв
  доступа в Authelia.

## Типовые сценарии

Первые два — основные, и сегодня не работает ни один: приложения нет.

1. **Семейный архив.** Человек открывает приложение на телефоне, выбирает до
   десяти записей разом — диктофонные дорожки и видео, — и закрывает его.
   Загрузка показывает ход. Файл, который уже загружали, не грузится второй
   раз. Когда текст готов, приходит уведомление; в списке запись видна
   заголовком и темами.
2. **Возвращение к записи.** Через месяц человек открывает список, находит
   запись по заголовку или теме и читает вычитанный текст, а при нужде — сырую
   расшифровку.
3. **Голосовое из Telegram.** Пользователь шлёт боту голосовое сообщение, бот
   отвечает «обрабатываю», через минуту приходит текст ответом на то же
   сообщение. Записи, чей текст длиннее предела сообщения Telegram, приходят
   несколькими частями. Работает сегодня.
4. **Файл через Telegram.** То же для аудиофайла или документа с аудио: бот
   отличает их по MIME-типу и расширению. Работает сегодня.
5. **Загрузка по HTTP.** Программа шлёт `POST /api/audio` со своим токеном,
   получает идентификатор задачи и опрашивает `GET /api/status/:id`, пока не
   увидит `done` и текст. Работает сегодня, но без токена и без разграничения
   доступа.
6. **Отказ на середине.** Конвертация или распознавание не удались — задача
   переходит в `failed`, а пользователь получает сообщение о том, что именно не
   вышло, и предложение повторить.

## Референсы

Где смотреть prior art, когда упёрлись.

- **Yandex SpeechKit, отложенное распознавание** — модель `deferred-general`,
  которой пользуемся: она и задаёт потолок по длине записи и формату.
- **Whisper и его серверные обёртки** — запасной путь, если внешний сервис
  перестанет устраивать по цене или по качеству русской речи.
- **PocketBase** — хранилище взамен сегодняшнего SQLite, решено 2026-08-11
  ([adr](adr/ADR-2026-08-11-pocketbase-storage-with-admin-panel.md)). Учётные
  записи оно хранит и получает от Authelia своим провайдером OIDC, но источником
  их не становится: заводит и проверяет людей по-прежнему Authelia.