# Zvuk — спецификация модуля для агентов

> Машиночитаемое описание продукта Zvuk для агентов и систем интеграции.
> Версия документа: 1.0, 2026-10-22. Canonical: https://zvukvtekst.ru/agent.md
> Человекочитаемый сайт: https://zvukvtekst.ru/ · llms.txt: https://zvukvtekst.ru/llms.txt

## Что делает модуль

Локальное распознавание речи и обработка текста на macOS без отправки данных наружу:

- **Диктовка**: аудио с микрофона → текст; вставка в приложение в фокусе или в буфер обмена.
- **Транскрипция файлов**: аудио/видеофайл → текст с таймкодами (Pro).
- **Пунктуация и полировка**: автоматическая пунктуация, уборка слов-паразитов, приведение регистра (локальная LLM, Pro).
- **Словарь и замены**: пользовательский словарь терминов, имён, замен.
- **Режимы**: предустановленные и пользовательские пресеты (сообщение, письмо, заметка, код; до 2 своих во Free, без лимита в Pro).
- **Перевод RU↔EN**: текст на русском → английский и обратно (Pro).

## Платформа

- macOS 13.3 или новее, Apple Silicon и Intel.
- Поставка: приложение для macOS, установка из DMG (Zvuk-2.0.dmg, ~0.6 МБ + модель 150 МБ – 3 ГБ при первом запуске).
- Модели распознавания: GigaAM (SberDevices, лицензия MIT), Whisper (OpenAI, лицензия MIT) — скачиваются один раз, работают офлайн.

## Входы и выходы

| Направление | Вход | Выход |
|---|---|---|
| Диктовка | микрофон (push-to-talk или переключатель) | текст в приложении в фокусе либо в буфере обмена |
| Транскрипция файла | аудио/видеофайл (до 60 мин, чанкование long-form) | текст с таймкодами в приложении |
| Перевод | текст RU → команда перевода | текст EN (и обратно EN → RU) |
| Словарь | пара «написание → замена» | замена применяется при каждой диктовке |

## Данные и приватность

- Обработка полностью на устройстве: аудио, транскрипции, словарь и промпты не покидают Mac.
- Облачных моделей и облачной обработки в продукте нет (архитектурно).
- Аккаунт (email, дата рождения) используется только для лицензий; аналитика сайта — собственная, без cookies (Umami).
- Открытые лицензии моделей: GigaAM — MIT, Whisper — MIT.

## Подключение (шаги)

1. Скачать DMG: https://zvukvtekst.ru/download/
2. Открыть DMG, перетащить Zvuk в «Программы».
3. Запустить; при первом запуске разрешить доступ к микрофону (Системные настройки → Конфиденциальность и безопасность → Микрофон).
4. При необходимости включить «Вставку через буфер обмена» (Настройки → Интеграция); имитация ввода работает без Accessibility-доступа, но в некоторых приложениях удобнее буфер.
5. Скачать модель распознавания (предлагается при первом запуске): GigaAM base (~600 МБ) для русского; Whisper medium/large-v3 для многоязычного.
6. Назначить хоткей (по умолчанию удержание правого Option) — диктовка готова.

## Ограничения

- Только macOS; версий для Windows/Linux/iOS/Android нет (в планах Windows/Linux, без дат).
- Запись одной сессии — до 60 минут; более длинный материал обрабатывается транскрипцией файла с чанкованием.
- Облачных моделей нет и не предусмотрено; офлайн-работа — базовый режим.
- Перевод: только RU↔EN (поддержка языков СНГ — в планах).

## Действия модуля (для встраивания)

| Действие | Вход | Выход | Как проверить результат | Статус |
|---|---|---|---|---|
| Начать диктовку | хоткей (удержание правого ⌥) или кнопка в меню-баре | распознанный текст вставлен в поле с фокусом | продиктовать фразу в заметки; сверить текст | ✅ работает |
| Остановить диктовку | отпустить хоткей / повторная команда | вставка завершена, буфер содержит текст | отпустить ⌥ и проверить буфер обмена | ✅ работает |
| Перевести RU↔EN | выделенный или продиктованный текст + команда перевода | переведённый текст | «Встреча переносится на пятницу» → «The meeting is moved to Friday.» | ✅ Pro |
| Постоянный режим | переключатель вместо удержания (Настройки → Горячие клавиши) | непрерывная диктовка до повторной команды | включить, продиктать абзац, выключить | ✅ работает |
| Транскрибировать файл | перетащить аудио/видео в окно приложения | текст с таймкодами | сравнить фрагмент транскрипции с записью | ✅ Pro |
| Заметки встреч | аудио конференции с системы | заметки с метками спикеров | проверить разметку «кто что сказал» | 🔜 в планах (macOS) |
| Перевод языков СНГ | текст/речь (uk, kk, be…) | переведённый текст | — | 🔜 в планах |
| Облачный контур | — | — | не планируется в текущей архитектуре | 🔜 в планах (без дат) |

## Примеры (исходная фраза → результат)

1. Пунктуация RU. Сказано: «привет это тест голосового ввода работаем без рук» → Результат: «Привет, это тест голосового ввода — работаем без рук.»
2. EN фраза. Сказано: «hello world this is a voice typing test» → Результат: «Hello world, this is a voice typing test.»
3. Длинная речь (60+ сек). Сказано (фрагмент заметки): «итак план на неделю в среду заморозка фич в пятницу демо документацию дописать до четверга правки скинуть на review» → Результат: «Итак, план на неделю: в среду — заморозка фич, в пятницу — демо. Документацию дописать до четверга, правки скинуть на review.»
4. Перевод RU→EN (Pro). Сказано: «встреча переносится на пятницу скинь правки до четверга» → Результат: «The meeting is moved to Friday — please send your edits by Thursday.»
5. Словарная замена. Словарь: «гигам → GigaAM». Сказано: «смотри документацию на гигам» → Результат: «Смотри документацию на GigaAM».

## Контакты

- Общие вопросы: hello@zvuk.io
- Документы: /terms/ (оферта), /privacy/ (политика конфиденциальности), /refund/ (возвраты).