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

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

## Цель

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

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

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

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

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

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

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

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

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

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

## Референсы

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

- **Yandex SpeechKit, отложенное распознавание** — модель `deferred-general`,
  которой пользуемся: она и задаёт потолок по длине записи и формату.
- **Whisper и его серверные обёртки** — запасной путь, если внешний сервис
  перестанет устраивать по цене или по качеству русской речи.
- **PocketBase** — кандидат в хранилище взамен сегодняшнего SQLite. Источником
  учётных записей его не рассматриваем: вход решено делать через OIDC у Authelia
  ([architecture.md](architecture.md), «Открытые вопросы»).