release v0.3.3-beta

.github/workflows/ci.yml

@@ -25,7 +25,8 @@ jobs:
             Resources/install_runtime.sh \
             "$RUNNER_TEMP/VoiceSwitch-Runtime" \
             worker/asr_worker.py \
-            worker/text_worker.py
+            worker/text_worker.py \
+            gigaam
 
       - name: Validate installer retry diagnostics
         run: |

.github/workflows/release.yml

@@ -28,6 +28,8 @@ jobs:
           notes_file="RELEASE_NOTES_${GITHUB_REF_NAME}.md"
           args=(
             "$GITHUB_REF_NAME"
+            dist/VoiceSwitch-*.dmg
+            dist/VoiceSwitch-*.dmg.sha256
             dist/VoiceSwitch-*.zip
             dist/VoiceSwitch-*.zip.sha256
             --title "VoiceSwitch ${GITHUB_REF_NAME}"

.gitignore

@@ -5,6 +5,7 @@
 dist/
 Runtime/
 outputs/
+backups/
 *.xcuserstate
 *.wav
 *.jsonl

INSTALL.md

@@ -2,25 +2,84 @@
 
 ## Готовый beta-релиз
 
-1. Скачайте arm64 ZIP из раздела
-   [GitHub Releases](https://github.com/mitimaicode/VoiceSwitch/releases).
-2. Сверьте SHA-256 при необходимости:
-
-   ```zsh
-   shasum -a 256 VoiceSwitch-*.zip
-   ```
-
-3. Распакуйте архив и перенесите `VoiceSwitch.app` в `/Applications`.
-4. Поскольку beta пока не нотарифицирована Apple, щёлкните приложение правой
-   кнопкой, выберите **Открыть** и подтвердите запуск.
-5. В меню VoiceSwitch нажмите **Установить модели**.
-
-Установщик загружает закреплённую версию `uv`, изолированный Python 3.12,
-Python-зависимости, ffmpeg и веса GigaAM, Whisper, Qwen3-ASR 1.7B и
-текстового редактора Qwen3-4B.
+### 1. Скачивание
+
+Откройте [GitHub Releases](https://github.com/mitimaicode/VoiceSwitch/releases)
+и скачайте файл с окончанием `macos-arm64.dmg` из самого нового релиза.
+DMG — рекомендуемый и самый простой вариант. ZIP предназначен для тех, у кого
+образ диска не открывается.
+
+При необходимости сверьте SHA-256 с соседним файлом `.sha256`:
+
+```zsh
+shasum -a 256 VoiceSwitch-*.dmg
+```
+
+### 2. Копирование в «Программы»
+
+1. Дважды нажмите скачанный DMG.
+2. Перетащите `VoiceSwitch.app` на ярлык **«Программы»** внутри открывшегося
+   окна.
+3. Дождитесь завершения копирования и закройте DMG.
+
+Не запускайте VoiceSwitch прямо из DMG или папки «Загрузки»: путь приложения
+важен для разрешения автоматической вставки.
+
+### 3. Первый запуск неподписанной beta
+
+Публичная версия подписана ad-hoc и не нотарифицирована Apple, потому что
+проект не использует платную подписку Apple Developer.
+
+1. Откройте Finder → **Программы**.
+2. Нажмите `VoiceSwitch` правой кнопкой мыши.
+3. Выберите **Открыть**.
+4. В предупреждении macOS ещё раз нажмите **Открыть**.
+
+Обычный двойной щелчок при первом запуске может показать сообщение, что Apple
+не удалось проверить разработчика. В этом случае закройте предупреждение и
+используйте правый клик → **Открыть**.
+
+### 4. Выбор моделей
+
+Встроенный мастер предлагает три стартовых комплекта:
+
+| Комплект | Состав | Примерный объём | Для чего |
+|---|---|---:|---|
+| Русская диктовка | GigaAM | 2,5 ГБ | Рекомендуемый первый запуск |
+| Русский + английский | GigaAM и Whisper | 4 ГБ | Смешанная речь |
+| Все возможности | Все ASR-модели и Qwen3-4B | 10 ГБ | Сравнение и локальная редактура |
+
+Whisper, Qwen3-ASR и редактор Qwen3-4B можно установить позднее из меню
+VoiceSwitch. Установщик загружает закреплённую версию `uv`, изолированный
+Python 3.12, Python-зависимости, ffmpeg и только выбранные веса.
 Администраторский пароль не требуется; системный Python и shell-профиль не
 изменяются.
 
+### 5. Разрешения macOS
+
+Мастер последовательно попросит:
+
+- **Микрофон** — для записи речи;
+- **Распознавание речи** — только при использовании системной модели Apple;
+- **Универсальный доступ** — для глобальной клавиши и автоматической вставки.
+
+Для универсального доступа нажмите **Открыть настройки**, найдите VoiceSwitch
+в разделе **Конфиденциальность и безопасность → Универсальный доступ** и
+включите переключатель. macOS может запросить Touch ID или пароль владельца
+Mac. Вернитесь в VoiceSwitch и нажмите **Проверить снова**.
+
+### 6. Первая проверка
+
+1. Откройте любое поле ввода и поставьте в него курсор.
+2. Нажмите `fn + Option` — появится красный индикатор записи.
+3. Произнесите короткую фразу.
+4. Нажмите `fn + Option` повторно.
+5. Дождитесь завершения распознавания и зелёного индикатора.
+
+Готовый текст должен появиться в исходном поле. Одновременно он сохраняется в
+буфере обмена, поэтому при проблеме его можно вставить вручную через
+`Command + V`.
+
 ### Если загрузка моделей прервалась
 
 Не удаляйте папку Runtime. Нажмите **Продолжить установку** в меню
@@ -38,34 +97,52 @@ VoiceSwitch показывает этап и причину последнего
 Перед публикацией issue удалите из журнала локальные пути или другие данные,
 которые не хотите раскрывать. Обычно достаточно приложить последние 30 строк.
 
-## Разрешения macOS
-
-VoiceSwitch просит только разрешения, необходимые для работы:
+## Текст распознаётся, но не вставляется
 
-- **Микрофон** — запись речи;
-- **Распознавание речи** — локальный системный движок Apple;
-- **Универсальный доступ** — глобальная горячая клавиша и вставка текста в
-  активное приложение.
+Это означает, что модели работают, но macOS не разрешила VoiceSwitch послать
+команду вставки. Расшифровка при этом уже находится в буфере обмена.
 
-Если текст распознаётся, но не вставляется:
+Сначала выполните простой вариант:
 
 1. откройте **Системные настройки → Конфиденциальность и безопасность →
    Универсальный доступ**;
-2. включите VoiceSwitch;
-3. полностью завершите и снова запустите приложение.
+2. выключите и снова включите переключатель VoiceSwitch;
+3. подтвердите действие через Touch ID или пароль;
+4. полностью завершите VoiceSwitch через пункт **Выход** и откройте снова из
+   `/Applications`.
 
-Если переключатель выключается снова после первой диктовки, удалите
-устаревшую TCC-запись:
+После обновления проверьте, что в списке нет старой копии VoiceSwitch из DMG,
+«Загрузок» или другой папки. Разрешён должен быть установленный файл:
+
+```text
+/Applications/VoiceSwitch.app
+```
+
+Если переключатель выглядит включённым, но вставка не работает, сбросьте
+только разрешение универсального доступа VoiceSwitch:
 
 ```zsh
 tccutil reset Accessibility io.github.mitimaicode.VoiceSwitch
 ```
 
-После этого нажмите `+` в списке «Универсальный доступ», выберите установленный
-`/Applications/VoiceSwitch.app` и перезапустите приложение.
+Затем снова откройте VoiceSwitch, нажмите **Разрешить доступ**, включите его в
+списке и перезапустите приложение. Микрофон, модели и расшифровки эта команда
+не удаляет.
 
 Без универсального доступа распознанный текст копируется в буфер обмена.
 
+## Обновление
+
+1. Завершите VoiceSwitch через пункт **Выход**.
+2. Откройте новый DMG.
+3. Перетащите новую версию на «Программы» и подтвердите замену.
+4. Откройте приложение правой кнопкой → **Открыть**.
+
+Модели повторно загружать не нужно: они находятся отдельно в
+`~/Library/Application Support/VoiceSwitch`. Из-за ad-hoc подписи macOS может
+попросить заново включить универсальный доступ после замены приложения — это
+ограничение бесплатной публичной beta.
+
 ## Файлы и удаление
 
 Приложение:
@@ -87,7 +164,7 @@ tccutil reset Accessibility io.github.mitimaicode.VoiceSwitch
 
 - только Apple Silicon и macOS 14+;
 - Apple SpeechAnalyzer доступен только на macOS 26+;
-- первая установка требует около 12 ГБ свободного места и может быть долгой;
+- рекомендуемая установка требует около 2,5 ГБ; полный комплект — около 10 ГБ;
 - приложение пока не подписано сертификатом Apple Developer ID;
 - автоматическое обновление ещё не реализовано.
 

README.md

@@ -45,25 +45,42 @@ VoiceSwitch записывает речь по глобальной горяче
 - Mac с Apple Silicon (`M1` или новее);
 - macOS 14 Sonoma или новее;
 - рекомендуется 16 ГБ оперативной памяти;
-- около 12 ГБ свободного места для Python, зависимостей и четырёх загружаемых моделей;
+- около 2,5 ГБ для рекомендуемой установки с GigaAM или около 10 ГБ для всех моделей;
 - интернет только во время первоначальной установки моделей.
 
 ## Установка
 
-1. Откройте раздел [Releases](https://github.com/mitimaicode/VoiceSwitch/releases)
-   и скачайте архив `VoiceSwitch-…-macos-arm64.zip`.
-2. Распакуйте архив и перенесите `VoiceSwitch.app` в «Программы».
-3. При первом запуске щёлкните приложение правой кнопкой и выберите
-   **Открыть**. Подтвердите запуск beta-версии.
-4. Нажмите значок VoiceSwitch в строке меню и выберите
-   **Установить модели**. Загрузка занимает несколько гигабайт.
-5. Разрешите доступ к микрофону. Для глобальной клавиши и автоматической
-   вставки включите VoiceSwitch в
+1. Откройте [GitHub Releases](https://github.com/mitimaicode/VoiceSwitch/releases),
+   выберите самый новый релиз и скачайте `VoiceSwitch-…-macos-arm64.dmg`.
+2. Откройте DMG и обязательно перетащите `VoiceSwitch.app` на ярлык
+   **«Программы»**. Не запускайте приложение прямо из DMG.
+3. Откройте папку «Программы», щёлкните VoiceSwitch правой кнопкой и выберите
+   **Открыть**. Затем ещё раз подтвердите **Открыть** в предупреждении macOS.
+4. В мастере выберите стартовый комплект. Для первой проверки рекомендуется
+   **«Русская диктовка»**: только GigaAM, около 2,5 ГБ. Остальные модели и
+   локальный редактор можно добавить позже.
+5. Разрешите микрофон и включите VoiceSwitch в разделе
    **Системные настройки → Конфиденциальность и безопасность →
-   Универсальный доступ**.
+   Универсальный доступ**. Это необходимо для `fn + Option` и автоматической
+   вставки.
+6. Поставьте курсор в любое поле ввода, нажмите `fn + Option`, произнесите
+   фразу и нажмите сочетание повторно. Дождитесь зелёного индикатора.
 
 Подробности и решение типовых проблем приведены в [INSTALL.md](INSTALL.md).
 
+### Обновление без повторной загрузки моделей
+
+Завершите VoiceSwitch, замените старый `/Applications/VoiceSwitch.app` новой
+версией и снова откройте приложение правой кнопкой. Модели, настройки и журнал
+хранятся отдельно в `~/Library/Application Support/VoiceSwitch`, поэтому
+скачивать их заново не требуется.
+
+Публичная beta не подписана Apple Developer ID. После замены приложения macOS
+иногда отключает универсальный доступ. Если распознавание работает, но текст
+только копируется в буфер обмена, выключите и снова включите VoiceSwitch в
+разделе **Универсальный доступ**, затем перезапустите приложение. Полная
+инструкция восстановления приведена в [INSTALL.md](INSTALL.md#текст-распознаётся-но-не-вставляется).
+
 Если этап установки прервётся, нажмите **Продолжить установку**: VoiceSwitch
 восстановит недостающие зависимости и использует уже загруженные файлы.
 Причина сбоя показывается в меню, а полный журнал сохраняется в
@@ -89,7 +106,9 @@ VoiceSwitch записывает речь по глобальной горяче
 компактное сообщение для переписки. Если редактор вернёт ошибку, VoiceSwitch
 автоматически вставит исходную расшифровку.
 
-Модель загружается лениво. При переключении предыдущая загружаемая модель
+Модель загружается лениво. Если выбранный движок ещё не установлен,
+VoiceSwitch покажет его размер и предложит загрузить только этот компонент.
+При переключении предыдущая загруженная модель
 выгружается, чтобы не занимать память. Apple использует системные ресурсы
 распознавания и может отдельно запросить разрешение «Распознавание речи».
 
@@ -168,9 +187,13 @@ chmod +x scripts/*.sh Resources/install_runtime.sh
 Создание компактного release-архива без весов моделей:
 
 ```zsh
-./scripts/package_release.sh 0.3.2-beta
+./scripts/package_release.sh 0.3.3-beta
 ```
 
+Публичный release-скрипт по умолчанию использует ad-hoc подпись. Для стабильной
+локальной подписи разработки можно передать имя собственной code-signing
+identity через `VOICESWITCH_CODESIGN_IDENTITY`.
+
 ## Обратная связь
 
 - воспроизводимые ошибки — [Issues](https://github.com/mitimaicode/VoiceSwitch/issues);