diff --git a/GITHUB_GUIDE.md b/GITHUB_GUIDE.md deleted file mode 100644 index 3e021fb..0000000 --- a/GITHUB_GUIDE.md +++ /dev/null @@ -1,423 +0,0 @@ -# 🚀 Руководство по публикации Votobu на GitHub - -## 📋 Checklist перед публикацией - -### ✅ Обязательно: -- [x] README.md актуален и информативен -- [x] LICENSE файл создан (MIT) -- [x] .gitignore настроен -- [x] Все файлы документации готовы -- [x] Проект работает локально -- [x] Нет чувствительных данных (пароли, токены) - -### ✅ Рекомендуется: -- [x] CONTRIBUTING.md создан -- [x] Issue templates настроены -- [x] Pull request template готов -- [x] CHANGELOG.md актуален -- [x] Все TODO выполнены или задокументированы - ---- - -## 🎯 Шаг 1: Подготовка проекта - -### Проверить что все работает: - -```bash -# 1. Протестировать компоненты -python test_components.py - -# 2. Запустить приложение -python src/main.py - -# 3. Проверить что иконки созданы -dir assets\ -``` - -### Очистить лишние файлы: - -```bash -# Удалить временные файлы -del /s /q __pycache__ -del /s /q *.pyc -del /s /q *.log - -# Удалить артефакты сборки (если есть) -rmdir /s /q build -rmdir /s /q dist -``` - ---- - -## 🌐 Шаг 2: Создание репозитория на GitHub - -### Вариант А: Через веб-интерфейс - -1. **Перейдите на GitHub.com** - - Войдите в свой аккаунт - - Нажмите "+" → "New repository" - -2. **Заполните информацию:** - - **Repository name:** `Votobu` - - **Description:** `🎤 Voice-to-Text Hotkey Application - преобразование голоса в текст одной клавишей` - - **Public** ✅ (чтобы другие могли использовать) - - **НЕ добавляйте** README, .gitignore, LICENSE (у нас уже есть) - -3. **Создайте репозиторий** - - Нажмите "Create repository" - -### Вариант Б: Через GitHub CLI - -```bash -# Установите GitHub CLI: https://cli.github.com/ -gh repo create Votobu --public --description "🎤 Voice-to-Text Hotkey Application" -``` - ---- - -## 💻 Шаг 3: Инициализация Git локально - -### Если Git еще не инициализирован: - -```bash -# Перейдите в папку проекта -cd E:\github\Votobu - -# Инициализировать Git -git init - -# Настроить user info (если еще не настроено) -git config user.name "Ваше Имя" -git config user.email "your.email@example.com" - -# Добавить все файлы -git add . - -# Первый commit -git commit -m "🎉 Initial commit: Votobu v1.0.2" -``` - -### Если Git уже инициализирован: - -```bash -# Проверить статус -git status - -# Добавить новые файлы -git add . - -# Commit -git commit -m "📦 Prepare for GitHub release" -``` - ---- - -## 🔗 Шаг 4: Связать с GitHub - -```bash -# Добавить remote (замените YOUR-USERNAME) -git remote add origin https://github.com/YOUR-USERNAME/Votobu.git - -# Проверить что remote добавлен -git remote -v - -# Push на GitHub -git branch -M main -git push -u origin main -``` - -### При ошибке аутентификации: - -GitHub больше не поддерживает пароли. Нужен Personal Access Token: - -1. **Создайте токен:** - - GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) - - Generate new token - - Выберите scope: `repo` - - Скопируйте токен - -2. **Используйте токен как пароль:** - ```bash - git push -u origin main - # Username: ваш-username - # Password: вставьте токен - ``` - ---- - -## 🏷️ Шаг 5: Создание первого релиза - -### Через веб-интерфейс: - -1. **На странице репозитория:** - - Нажмите "Releases" → "Create a new release" - -2. **Заполните:** - - **Tag:** `v1.0.2` - - **Title:** `🎉 Votobu v1.0.2 - Initial Release` - - **Description:** Скопируйте из CHANGELOG.md - -3. **Добавьте файлы (опционально):** - - Соберите .exe: `build.bat` - - Прикрепите `dist/Votobu.exe` - - Прикрепите `Votobu-Offline-Installer.zip` - -4. **Publish release** - -### Через Git tags: - -```bash -# Создать tag -git tag -a v1.0.2 -m "Release v1.0.2" - -# Push tag -git push origin v1.0.2 -``` - ---- - -## 📝 Шаг 6: Настройка репозитория - -### Описание и топики: - -1. **Перейдите в Settings репозитория** - -2. **Добавьте описание:** - ``` - 🎤 Voice-to-Text Hotkey Application powered by OpenAI Whisper. - Преобразование голоса в текст по нажатию клавиши. Локально, быстро, приватно. - ``` - -3. **Добавьте Topics:** - - `voice-recognition` - - `speech-to-text` - - `whisper` - - `python` - - `pyqt5` - - `windows` - - `hotkeys` - - `voice-to-text` - - `offline` - - `privacy` - -### Настройка Features: - -- ✅ **Issues** - включить -- ✅ **Wiki** - включить (опционально) -- ✅ **Discussions** - включить -- ⬜ **Projects** - пока не нужно -- ⬜ **Sponsorships** - опционально - -### About section: - -- **Website:** (если есть) -- **Topics:** добавьте релевантные теги -- **Include in the home page:** ✅ - ---- - -## 🖼️ Шаг 7: Добавление визуалов (опционально) - -### Скриншоты: - -Создайте папку `screenshots/` и добавьте: -- Скриншот иконки в трее -- Скриншот окна настроек -- GIF демонстрация работы - -### Обновите README.md: - -```markdown -## 📸 Скриншоты - -![System Tray](screenshots/tray.png) -![Settings Window](screenshots/settings.png) - -## 🎬 Demo - -![Demo](screenshots/demo.gif) -``` - -### Создать demo GIF: - -Используйте: -- [ScreenToGif](https://www.screentogif.com/) -- [LICEcap](https://www.cockos.com/licecap/) -- [Kap](https://getkap.co/) - ---- - -## 🎨 Шаг 8: GitHub Repo Shield Badges - -Добавьте в README.md красивые badges: - -```markdown -![Python](https://img.shields.io/badge/Python-3.8+-blue.svg) -![Version](https://img.shields.io/github/v/release/YOUR-USERNAME/Votobu) -![License](https://img.shields.io/badge/License-MIT-green.svg) -![Platform](https://img.shields.io/badge/Platform-Windows-lightgrey.svg) -![Stars](https://img.shields.io/github/stars/YOUR-USERNAME/Votobu) -![Issues](https://img.shields.io/github/issues/YOUR-USERNAME/Votobu) -``` - ---- - -## 📢 Шаг 9: Продвижение проекта - -### На Reddit: -- r/Python -- r/opensource -- r/selfhosted -- r/programming - -### На Hacker News: -- [Show HN: Votobu - Voice to Text with hotkeys](https://news.ycombinator.com/submit) - -### На Product Hunt: -- Создайте пост с описанием - -### В Twitter/X: -``` -🎤 Представляю Votobu - Voice-to-Text приложение! - -✨ Зажмите F9 → Говорите → Получите текст -🔒 Полностью локально (OpenAI Whisper) -🆓 Open Source (MIT) - -GitHub: https://github.com/YOUR-USERNAME/Votobu - -#Python #OpenSource #VoiceRecognition -``` - ---- - -## 🔄 Шаг 10: Поддержка и обновления - -### Регулярно: - -1. **Отвечайте на Issues** (в течение 24-48 часов) -2. **Ревьюйте Pull Requests** -3. **Обновляйте документацию** -4. **Выпускайте новые версии** - -### При новой версии: - -```bash -# 1. Обновить версию -# Измените в src/__init__.py: -__version__ = "1.0.3" - -# 2. Обновить CHANGELOG.md - -# 3. Commit и tag -git add . -git commit -m "🔖 Release v1.0.3" -git tag -a v1.0.3 -m "Release v1.0.3" - -# 4. Push -git push origin main -git push origin v1.0.3 - -# 5. Создать GitHub Release -``` - ---- - -## 📊 Шаг 11: Мониторинг и аналитика - -### GitHub Insights: - -Следите за: -- ⭐ Stars -- 👀 Watchers -- 🍴 Forks -- 📥 Clones -- 👥 Contributors - -### GitHub Traffic: - -- Views (просмотры) -- Unique visitors -- Clones -- Referring sites - ---- - -## 🎯 Целевые показатели - -### Первый месяц: -- 🎯 10+ stars -- 🎯 5+ watchers -- 🎯 2-3 issues -- 🎯 1-2 contributors - -### Первые 3 месяца: -- 🎯 50+ stars -- 🎯 20+ watchers -- 🎯 10+ issues (закрыто) -- 🎯 5+ contributors -- 🎯 1-2 fork PR - ---- - -## ✅ Финальный Checklist - -Перед публикацией проверьте: - -- [ ] README.md информативен и красив -- [ ] LICENSE корректен (MIT) -- [ ] .gitignore полный -- [ ] Нет секретов в коде (пароли, API keys) -- [ ] Проект собирается и работает -- [ ] Документация актуальна -- [ ] CONTRIBUTING.md понятен -- [ ] Issue templates настроены -- [ ] Все файлы добавлены в Git -- [ ] First commit сделан -- [ ] Remote добавлен -- [ ] Push на GitHub успешен -- [ ] Релиз создан -- [ ] Описание и topics добавлены -- [ ] README выглядит хорошо на GitHub - ---- - -## 🎉 Готово! - -Ваш проект опубликован на GitHub! - -**URL репозитория:** -``` -https://github.com/YOUR-USERNAME/Votobu -``` - -**Поделитесь:** -```markdown -🎤 Проект опубликован! - -GitHub: https://github.com/YOUR-USERNAME/Votobu - -⭐ Ставьте звездочку если нравится! -🍴 Fork для своих модификаций! -🐛 Issues для багов и идей! -``` - ---- - -## 📞 Полезные ссылки - -- [GitHub Guides](https://guides.github.com/) -- [GitHub Docs](https://docs.github.com/) -- [Open Source Guide](https://opensource.guide/) -- [Choose a License](https://choosealicense.com/) -- [Shields.io](https://shields.io/) - для badges -- [GitHub CLI](https://cli.github.com/) - ---- - -
- -**Поздравляем с публикацией вашего первого Open Source проекта!** 🎊 - -
- diff --git a/HOTFIX_v1.0.1.md b/HOTFIX_v1.0.1.md deleted file mode 100644 index 502564e..0000000 --- a/HOTFIX_v1.0.1.md +++ /dev/null @@ -1,233 +0,0 @@ -# 🔧 Hotfix v1.0.1 - Исправление Qt Platform Plugin Error - -**Дата:** 2025-11-09 -**Статус:** ✅ ИСПРАВЛЕНО - ---- - -## 🐛 Проблема - -При запуске приложения возникала критическая ошибка: - -``` -qt.qpa.plugin: Could not find the Qt platform plugin "windows" in "" -This application failed to start because no Qt platform plugin could be initialized. -``` - -### Причина - -PyQt5 на Windows не мог найти свои платформенные плагины из-за неправильно установленной переменной окружения `QT_PLUGIN_PATH`. - ---- - -## ✅ Решение - -### 1. Код исправлен в `src/main.py` - -Добавлен автоматический поиск и установка пути к Qt плагинам **ПЕРЕД** импортом PyQt5: - -```python -import sys -import os -from pathlib import Path - -# Исправление проблемы с Qt platform plugin на Windows -if sys.platform == 'win32': - # Найти путь к PyQt5 - import site - for site_dir in site.getsitepackages(): - qt_plugin_path = Path(site_dir) / 'PyQt5' / 'Qt5' / 'plugins' - if qt_plugin_path.exists(): - os.environ['QT_PLUGIN_PATH'] = str(qt_plugin_path) - break - - # Альтернативный путь - if 'QT_PLUGIN_PATH' not in os.environ: - pyqt5_path = Path(sys.executable).parent / 'Lib' / 'site-packages' / 'PyQt5' / 'Qt5' / 'plugins' - if pyqt5_path.exists(): - os.environ['QT_PLUGIN_PATH'] = str(pyqt5_path) - -# Теперь безопасно импортировать PyQt5 -from PyQt5.QtWidgets import QApplication -from PyQt5.QtCore import QObject, pyqtSignal -``` - -### 2. Обновлен `requirements.txt` - -Изменена версия PyQt5 на более стабильную: - -```diff -- PyQt5==5.15.10 -+ PyQt5==5.15.9 -``` - -### 3. Улучшен `install.bat` - -Добавлены шаги для корректной установки PyQt5: - -```batch -# Удаление старых версий -pip uninstall PyQt5 PyQt5-Qt5 PyQt5-sip -y - -# Установка всех компонентов явно -pip install PyQt5==5.15.9 PyQt5-sip PyQt5-Qt5 -``` - -### 4. Создан `TROUBLESHOOTING.md` - -Добавлено полное руководство по решению этой и других проблем. - ---- - -## 📝 Инструкция для пользователей - -### Если у вас уже установлен Votobu: - -1. **Обновите код:** - ```bash - git pull - # или скачайте новую версию - ``` - -2. **Переустановите PyQt5:** - ```bash - pip uninstall PyQt5 PyQt5-Qt5 PyQt5-sip -y - pip install PyQt5==5.15.9 PyQt5-sip PyQt5-Qt5 - ``` - -3. **Запустите:** - ```bash - python src/main.py - # или run.bat - ``` - -### Если вы устанавливаете Votobu впервые: - -Просто запустите `install.bat` - все исправления уже включены! - -```bash -install.bat -``` - ---- - -## ✨ Что изменилось - -### Измененные файлы: - -1. ✅ `src/main.py` - добавлен автопоиск Qt плагинов -2. ✅ `requirements.txt` - обновлена версия PyQt5 -3. ✅ `install.bat` - улучшен процесс установки -4. ✅ `run.bat` - добавлены информативные сообщения -5. ✅ `TROUBLESHOOTING.md` - создано руководство по проблемам -6. ✅ `CHANGELOG.md` - добавлена версия 1.0.1 -7. ✅ `src/__init__.py` - обновлен номер версии -8. ✅ `README.md` - добавлен badge версии -9. ✅ `START_HERE.txt` - добавлены ссылки на troubleshooting - ---- - -## 🧪 Тестирование - -### Проверено на: -- ✅ Windows 10 (Python 3.10) -- ✅ Windows 11 (Python 3.10) - -### Тестовые сценарии: -1. ✅ Установка с нуля -2. ✅ Обновление с версии 1.0.0 -3. ✅ Запуск приложения -4. ✅ Запись аудио -5. ✅ Распознавание речи -6. ✅ Копирование в буфер обмена - ---- - -## 🎯 Результат - -**До исправления:** -``` -❌ qt.qpa.plugin: Could not find the Qt platform plugin "windows" -❌ Application failed to start -``` - -**После исправления:** -``` -✅ Запуск Votobu... -✅ Загрузка модели Whisper: base... -✅ Модель загружена успешно -✅ Перехват клавиш запущен. Горячая клавиша: F9 -✅ Votobu успешно запущен! -``` - ---- - -## 📊 Статистика - -- **Затронуто файлов:** 9 -- **Добавлено строк:** ~150 -- **Изменено строк:** ~50 -- **Новых документов:** 2 (TROUBLESHOOTING.md, HOTFIX_v1.0.1.md) -- **Время исправления:** ~30 минут -- **Статус:** ✅ Полностью исправлено - ---- - -## 💡 Техническое объяснение - -### Почему возникала ошибка? - -PyQt5 использует платформенные плагины (platform plugins) для отрисовки GUI на разных ОС: -- **Windows:** `qwindows.dll` -- **Linux:** `qxcb.so` -- **macOS:** `qcocoa.dylib` - -Эти плагины находятся в: -``` -site-packages/PyQt5/Qt5/plugins/platforms/qwindows.dll -``` - -Qt ищет плагины в директории, указанной в переменной `QT_PLUGIN_PATH`. Если эта переменная не установлена, Qt не может найти плагины → ошибка. - -### Как работает исправление? - -1. **Перед импортом PyQt5** код определяет где установлен Python -2. Ищет директорию `site-packages/PyQt5/Qt5/plugins` -3. Устанавливает `os.environ['QT_PLUGIN_PATH']` на найденный путь -4. **После этого** импортирует PyQt5 -5. Qt теперь знает где искать плагины → все работает ✅ - ---- - -## 🔮 Предотвращение в будущем - -Исправление теперь **встроено в код**, поэтому: -- ✅ Работает на любой Windows системе -- ✅ Не требует ручной настройки переменных окружения -- ✅ Автоматически находит правильные пути -- ✅ Совместимо с виртуальными окружениями - ---- - -## 📞 Вопросы? - -Если проблема сохраняется: - -1. Прочитайте [TROUBLESHOOTING.md](TROUBLESHOOTING.md) -2. Запустите `python test_components.py` для диагностики -3. Создайте Issue на GitHub с: - - Версией Python (`python --version`) - - Версией Windows (`winver`) - - Полным текстом ошибки - - Выводом `pip list` - ---- - -
- -**Версия 1.0.1 стабильна и готова к использованию!** ✨ - -[⬅ Назад к README](README.md) | [📖 Документация](QUICKSTART.md) | [🐛 Проблемы](TROUBLESHOOTING.md) - -
- diff --git a/HOTKEYS.md b/HOTKEYS.md deleted file mode 100644 index c13c3ce..0000000 --- a/HOTKEYS.md +++ /dev/null @@ -1,259 +0,0 @@ -# Горячие клавиши в Votobu - -## 🎯 Общая информация - -Votobu поддерживает **широкий спектр горячих клавиш** - от функциональных клавиш до кнопок мыши! - -### Как изменить горячую клавишу: - -1. **ПКМ** на иконку в трее -2. Выберите **"Настройки"** -3. Нажмите **"Изменить клавишу"** -4. **Нажмите** желаемую клавишу или кнопку мыши -5. Нажмите **"Сохранить"** -6. **💡 Рекомендуется перезапустить программу** для гарантированного применения изменений - -> **Примечание:** Хотя программа попытается применить изменения динамически, -> для наилучшей работы (особенно с кнопками мыши) рекомендуется перезапуск. - ---- - -## ⌨️ Поддерживаемые клавиши клавиатуры - -### Функциональные клавиши -``` -F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12 -``` - -**Рекомендуется:** F9 (по умолчанию), F10, F11 - -### Буквы -``` -A, B, C, D, E, F, G, H, I, J, K, L, M, -N, O, P, Q, R, S, T, U, V, W, X, Y, Z -``` - -**Примеры:** -- `R` - удобно для **R**ecord -- `V` - удобно для **V**oice -- `T` - удобно для **T**ext - -### Цифры -``` -0, 1, 2, 3, 4, 5, 6, 7, 8, 9 -``` - -### Специальные клавиши -``` -Space - Пробел -Enter - Ввод -Esc - Escape -Tab - Табуляция -Backspace - Удаление назад -Delete - Удаление вперед -Insert - Вставка -``` - -### Навигация -``` -Home - В начало -End - В конец -Page Up - Страница вверх -Page Down - Страница вниз -Up - Стрелка вверх -Down - Стрелка вниз -Left - Стрелка влево -Right - Стрелка вправо -``` - ---- - -## 🖱️ Поддерживаемые кнопки мыши - -### ⭐ Боковые кнопки (Рекомендуется!) - -**X1 (Боковая назад)** - `mouse_x1` -``` -Обычно находится под большим пальцем на левой стороне мыши. -Идеально для горячей клавиши - не мешает работе! -``` - -**X2 (Боковая вперед)** - `mouse_x2` -``` -Обычно над кнопкой X1. -Также удобно использовать. -``` - -### Основные кнопки - -**Левая кнопка** - `mouse_left` -``` -⚠️ Не рекомендуется - используется для кликов постоянно -``` - -**Правая кнопка** - `mouse_right` -``` -⚠️ Не рекомендуется - используется для контекстных меню -``` - -**Средняя кнопка (колесико)** - `mouse_middle` -``` -✅ Хороший вариант, если не используется для прокрутки -``` - ---- - -## 💡 Рекомендации по выбору - -### 🥇 Лучшие варианты: - -1. **Mouse X1/X2** (боковые кнопки мыши) - - ✅ Не мешают обычной работе - - ✅ Легко нажимать большим пальцем - - ✅ Можно держать зажатыми во время печати - -2. **F9-F12** - - ✅ Редко используются в приложениях - - ✅ Легко найти вслепую - - ✅ Стандартный вариант - -3. **Буква R, V или T** - - ✅ Мнемонически легко запомнить - - ⚠️ Не работает когда фокус в текстовом поле - -### ❌ Не рекомендуется: - -- **Space** - используется для пробелов в тексте -- **Enter** - используется для подтверждения -- **Esc** - используется для отмены -- **Mouse Left/Right** - постоянно используются - ---- - -## 🎮 Примеры конфигураций - -### Для программистов -``` -Горячая клавиша: Mouse X1 (боковая кнопка) -Почему: Рука на мыши, легко нажать большим пальцем, - не мешает печатать и кликать -``` - -### Для писателей -``` -Горячая клавиша: F10 -Почему: Руки на клавиатуре, легко найти, - не конфликтует с горячими клавишами редакторов -``` - -### Для геймеров -``` -Горячая клавиша: Mouse X2 -Почему: Удобно во время игры, быстрый доступ, - не мешает WASD и мышке -``` - -### Для стримеров -``` -Горячая клавиша: F11 -Почему: Вдали от других клавиш, случайно не нажмешь, - легко найти в стрессе -``` - ---- - -## 🔧 Техническая информация - -### Как это работает? - -**Клавиатура:** -- Использует `pynput.keyboard.Listener` -- Глобальный перехват клавиш на уровне ОС -- Работает в любом приложении - -**Мышь:** -- Использует `pynput.mouse.Listener` -- Глобальный перехват кликов мыши -- Работает даже в полноэкранных приложениях - -### Формат хранения - -В файле `config.json`: -```json -{ - "hotkey": "mouse_x1", - ... -} -``` - -Примеры значений: -```json -"hotkey": "f9" // Функциональная клавиша -"hotkey": "r" // Буква -"hotkey": "space" // Специальная клавиша -"hotkey": "mouse_x1" // Кнопка мыши -``` - ---- - -## ❓ FAQ - -### Нужно ли перезапускать программу после изменения горячей клавиши? -**Рекомендуется, но не обязательно.** -- Программа пытается применить изменения автоматически -- Однако для гарантированной работы (особенно с кнопками мыши) лучше перезапустить -- Вы получите уведомление с рекомендацией перезапуска - -**Как перезапустить:** -``` -ПКМ на иконке → Выход → Запустить заново (Votobu_HideConsole.vbs) -``` - -### Можно ли использовать комбинации клавиш (Ctrl+R)? -Пока нет. Планируется в будущих версиях. - -### Почему не работает боковая кнопка мыши? -- Убедитесь, что ваша мышь имеет боковые кнопки -- Проверьте, что кнопки не переназначены в драйвере мыши -- Попробуйте другую боковую кнопку (X1 или X2) - -### Можно ли назначить кнопку на клавиатуре игровой мыши? -Да, если драйвер эмулирует стандартную клавишу (F1-F12 и т.д.) - -### Горячая клавиша не работает в игре? -- Некоторые игры блокируют глобальные hotkeys (античит) -- Попробуйте запустить Votobu от имени администратора -- Используйте кнопку мыши вместо клавиши - ---- - -## 🎯 Тестирование горячих клавиш - -Чтобы проверить, какие клавиши/кнопки работают: - -```bash -python test_hotkeys.py -``` - -Скрипт протестирует: -- F9 -- Буква A -- Space -- Mouse X1 -- Mouse X2 -- Mouse Middle - ---- - -## 🚀 Что дальше? - -После настройки горячей клавиши: -1. Нажмите **"Сохранить"** в настройках -2. Приложение перезапустит перехват -3. Попробуйте новую горячую клавишу! - -📖 **См. также:** -- [README.md](README.md) - основная документация -- [USAGE.md](USAGE.md) - руководство пользователя -- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - решение проблем - diff --git a/NOTIFICATION_EXAMPLES.md b/NOTIFICATION_EXAMPLES.md deleted file mode 100644 index 9c03a3e..0000000 --- a/NOTIFICATION_EXAMPLES.md +++ /dev/null @@ -1,180 +0,0 @@ -# Примеры уведомлений в Votobu - -## 📢 Уведомления при сохранении настроек - -### 1️⃣ При изменении горячей клавиши - -``` -┌─────────────────────────────────────────┐ -│ 🔔 Настройки сохранены │ -├─────────────────────────────────────────┤ -│ Горячая клавиша изменена на: MOUSE_X1 │ -│ │ -│ 💡 Рекомендуется перезапустить программу│ -│ для гарантированного применения │ -│ изменений. │ -│ │ -│ ПКМ на иконке → Выход → Запустить заново│ -└─────────────────────────────────────────┘ -``` - -**Когда показывается:** При изменении горячей клавиши (например, с F9 на Mouse X1) - -**Причина:** Хотя программа пытается применить изменения динамически (перезапуск listener'а), -для гарантированной работы, особенно с кнопками мыши, рекомендуется полный перезапуск. - ---- - -### 2️⃣ При изменении модели Whisper - -``` -┌─────────────────────────────────────────┐ -│ 🔔 Настройки сохранены │ -├─────────────────────────────────────────┤ -│ Модель Whisper изменена. │ -│ Перезапустите программу для применения. │ -└─────────────────────────────────────────┘ -``` - -**Когда показывается:** При изменении модели Whisper (например, с base на small) - -**Причина:** Модель Whisper загружается только при старте программы. Для загрузки новой -модели требуется перезапуск. - ---- - -### 3️⃣ При изменении других настроек - -``` -┌─────────────────────────────────────────┐ -│ 🔔 Настройки сохранены │ -├─────────────────────────────────────────┤ -│ Изменения применены успешно! │ -└─────────────────────────────────────────┘ -``` - -**Когда показывается:** При изменении языка распознавания или других настроек - -**Причина:** Эти изменения применяются немедленно, перезапуск не требуется. - ---- - -## 🎯 Пример использования - -### Сценарий: Пользователь меняет F9 на боковую кнопку мыши - -1. **Пользователь:** Открывает настройки (ПКМ → Настройки) -2. **Пользователь:** Нажимает "Изменить клавишу" -3. **Пользователь:** Кликает боковую кнопку мыши (X1) -4. **Программа:** Показывает "Текущая клавиша: MOUSE_X1" -5. **Пользователь:** Нажимает "Сохранить" -6. **Программа:** Сохраняет настройки -7. **Программа:** Показывает уведомление: - ``` - Настройки сохранены - - Горячая клавиша изменена на: MOUSE_X1 - - 💡 Рекомендуется перезапустить программу - для гарантированного применения изменений. - - ПКМ на иконке → Выход → Запустить заново - ``` -8. **Пользователь:** Видит уведомление и решает: - - ✅ Перезапустить (рекомендуется) → ПКМ → Выход → Votobu_HideConsole.vbs - - ⚠️ Попробовать без перезапуска → Может не работать стабильно - ---- - -## 🔧 Технические детали - -### Код в `src/main.py`: - -```python -def _on_settings_saved(self, new_config: dict) -> None: - """Обработчик сохранения настроек.""" - # Отслеживаем какие настройки изменились - hotkey_changed = new_config.get('hotkey') != self.config_manager.config.get('hotkey') - model_changed = new_config.get('whisper_model') != self.config_manager.config.get('whisper_model') - - # Сохранить конфигурацию - self.config_manager.save_config(new_config) - - # Обновить компоненты - if hotkey_changed: - self.hotkey_manager.change_hotkey(new_config['hotkey']) - - # Показать уведомление - if hotkey_changed: - hotkey_display = new_config['hotkey'].upper() - self.tray_app.show_notification( - "Настройки сохранены", - f"Горячая клавиша изменена на: {hotkey_display}\n\n" - f"💡 Рекомендуется перезапустить программу\n" - f"для гарантированного применения изменений.\n\n" - f"ПКМ на иконке → Выход → Запустить заново" - ) - elif model_changed: - self.tray_app.show_notification( - "Настройки сохранены", - f"Модель Whisper изменена.\n" - f"Перезапустите программу для применения." - ) - else: - self.tray_app.show_notification( - "Настройки сохранены", - "Изменения применены успешно!" - ) -``` - ---- - -## ❓ FAQ - -### Почему не просто автоматически перезапустить программу? - -**Причины:** -1. **Пользовательский контроль** - пользователь решает когда перезапустить -2. **Может быть активная запись** - нельзя прерывать пользователя -3. **Может не требоваться** - для простых изменений динамическое применение работает -4. **Безопасность** - автоматический перезапуск может быть неожиданным - -### Что если не перезапустить? - -**Возможные проблемы:** -- Горячая клавиша может работать нестабильно -- Кнопки мыши могут не реагировать -- Старая клавиша может продолжать работать - -**Динамическое применение (без перезапуска):** -```python -# В hotkey_manager.py: -def change_hotkey(self, new_hotkey: str) -> bool: - was_running = self.running - if was_running: - self.stop() # Останавливаем старый listener - - self.hotkey_str = new_hotkey.lower() - self.hotkey = self._parse_hotkey(self.hotkey_str) - self.is_mouse_button = self._is_mouse_button(self.hotkey_str) - - if was_running: - return self.start() # Запускаем новый listener - return True -``` - -Это **должно работать**, но для **гарантии** лучше перезапустить. - ---- - -## ✅ Резюме - -**Три типа уведомлений:** -1. 🔄 **Горячая клавиша** → Рекомендуется перезапуск + инструкция -2. 🔄 **Модель Whisper** → Требуется перезапуск -3. ✅ **Другие настройки** → Применено немедленно - -**Цель:** Информировать пользователя и дать четкие инструкции. - -**Результат:** Улучшенный UX и меньше проблем с "горячая клавиша не работает". - diff --git a/PACKAGING.md b/PACKAGING.md deleted file mode 100644 index 92271a4..0000000 --- a/PACKAGING.md +++ /dev/null @@ -1,384 +0,0 @@ -# Упаковка и распространение Votobu - -Руководство по созданию различных типов дистрибутивов Votobu. - ---- - -## 🎨 Запуск без консоли - -### Способы скрыть консольное окно: - -#### Вариант 1: Использовать .vbs скрипт (Рекомендуется) - -```bash -# Двойной клик на: -Votobu.vbs -``` - -Полностью скрывает консоль. Приложение работает в фоне. - -#### Вариант 2: Использовать run_silent.bat - -```bash -run_silent.bat -``` - -Запускает через `pythonw.exe` вместо `python.exe`. - -#### Вариант 3: Использовать .pyw файл - -```bash -pythonw.exe src\main.pyw -``` - -#### Вариант 4: Создать ярлык на рабочем столе - -```bash -create_shortcut.bat -``` - -Создаст ярлык на рабочем столе, который запускается без консоли. - -#### Вариант 5: Собрать .exe с --windowed (Лучший вариант) - -```bash -build.bat # Уже включает --windowed флаг -``` - -.exe версия всегда работает без консоли! - ---- - -## 📦 Способы упаковки - -### 1. 🟢 Простая установка (Рекомендуется для пользователей) - -**Использование:** `install.bat` - -**Что делает:** -- Устанавливает все зависимости из PyPI -- Проверяет версию Python -- Создает иконки -- Тестирует установку - -**Требования:** -- Python 3.8+ -- Интернет подключение - -**Команда:** -```bash -install.bat -``` - ---- - -### 2. 💎 Standalone .exe (Автономный исполняемый файл) - -**Использование:** `build.bat` - -**Что создает:** -- Один .exe файл со всеми зависимостями -- Не требует установки Python -- Работает на любом Windows компьютере - -**Требования для сборки:** -- Python 3.8+ с установленным Votobu -- PyInstaller -- ~500 MB свободного места - -**Команды:** -```bash -# Установить зависимости для сборки -pip install -r requirements-dev.txt - -# Собрать .exe -build.bat -``` - -**Результат:** -- `dist/Votobu.exe` - исполняемый файл (~200-300 MB) -- `dist/Votobu-v1.0.2-Windows.zip` - архив для распространения - -**Плюсы:** -- ✅ Не требует Python на целевом компьютере -- ✅ Простая установка - один файл -- ✅ Портативный - можно запускать с флешки - -**Минусы:** -- ❌ Большой размер файла (~300 MB) -- ❌ Долгая сборка (10-20 минут) -- ❌ Все равно требует скачать Whisper модель при первом запуске - ---- - -### 3. 📁 Offline Installer (Оффлайн установщик) - -**Использование:** `portable_installer.bat` - -**Что создает:** -- Архив со всеми wheel файлами зависимостей -- Установка без интернета -- Требует Python на целевом компьютере - -**Требования для создания:** -- Python 3.8+ -- Интернет подключение (для скачивания wheels) -- ~500 MB свободного места - -**Команды:** -```bash -portable_installer.bat -``` - -**Результат:** -- `Votobu-Offline-Installer-v1.0.2.zip` - полный пакет (~400 MB) - -**Содержимое:** -- `wheels/` - все зависимости в формате .whl -- `src/` - исходный код -- `install_offline.bat` - скрипт установки -- Документация - -**Использование на другом компьютере:** -1. Распаковать ZIP -2. Запустить `install_offline.bat` -3. Запустить `run.bat` - -**Плюсы:** -- ✅ Работает без интернета -- ✅ Включает все зависимости -- ✅ Быстрая установка - -**Минусы:** -- ❌ Требует Python -- ❌ Большой размер (~400 MB) - ---- - -## 🎯 Какой способ выбрать? - -### Для конечных пользователей: - -**Есть интернет + есть Python:** -```bash -install.bat ⭐ Рекомендуется -``` - -**Нет Python, но есть интернет:** -```bash -build.bat → Votobu.exe ⭐ Лучший вариант -``` - -**Нет интернета, но есть Python:** -```bash -portable_installer.bat → offline installer -``` - -### Для разработчиков: - -**Разработка:** -```bash -pip install -r requirements-dev.txt -``` - -**Тестирование:** -```bash -python test_components.py -pytest tests/ # если есть тесты -``` - -**Сборка релиза:** -```bash -build.bat # создать .exe -portable_installer.bat # создать offline installer -``` - ---- - -## 📊 Сравнение методов - -| Метод | Размер | Требует Python | Требует интернет | Время установки | Портативность | -|-------|--------|----------------|------------------|-----------------|---------------| -| install.bat | ~100 MB | ✅ Да | ✅ Да | 5-10 мин | ❌ Нет | -| .exe | ~300 MB | ❌ Нет | ⚠️ Первый запуск | 0 сек | ✅ Да | -| offline installer | ~400 MB | ✅ Да | ❌ Нет | 2-5 мин | ⚠️ Частично | - ---- - -## 🛠️ Сборка .exe в деталях - -### Шаг 1: Установка PyInstaller - -```bash -pip install pyinstaller -``` - -### Шаг 2: Сборка - -```bash -pyinstaller ^ - --name=Votobu ^ - --onefile ^ - --windowed ^ - --icon=assets/icon.png ^ - --add-data="assets;assets" ^ - --add-data="config;config" ^ - --hidden-import=whisper ^ - --hidden-import=sounddevice ^ - --hidden-import=pynput ^ - --hidden-import=imageio_ffmpeg ^ - --collect-all=whisper ^ - --collect-all=imageio_ffmpeg ^ - src/main.py -``` - -### Параметры: - -- `--name=Votobu` - имя файла -- `--onefile` - один .exe файл (не папка) -- `--windowed` - без консольного окна -- `--icon` - иконка приложения -- `--add-data` - включить ресурсы -- `--hidden-import` - явно указать модули -- `--collect-all` - собрать все файлы модуля - -### Результат: - -``` -build/ # Временные файлы (можно удалить) -dist/ - └── Votobu.exe # Готовый исполняемый файл -Votobu.spec # Конфигурация PyInstaller -``` - ---- - -## 🚀 Автоматическая сборка релиза - -Создайте файл `release.bat` для полной сборки: - -```batch -@echo off -echo Building complete release package... - -echo Step 1: Clean -if exist build rmdir /s /q build -if exist dist rmdir /s /q dist - -echo Step 2: Build .exe -call build.bat - -echo Step 3: Build offline installer -call portable_installer.bat - -echo Step 4: Create checksums -certutil -hashfile dist\Votobu.exe SHA256 > dist\Votobu.exe.sha256 -certutil -hashfile Votobu-Offline-Installer-v1.0.2.zip SHA256 > Votobu-Offline-Installer-v1.0.2.zip.sha256 - -echo Complete! Release files: -echo - dist\Votobu.exe -echo - dist\Votobu-v1.0.2-Windows.zip -echo - Votobu-Offline-Installer-v1.0.2.zip -pause -``` - ---- - -## 📝 Checklist перед релизом - -### Код: - -- [ ] Обновлен `__version__` в `src/__init__.py` -- [ ] Обновлен `CHANGELOG.md` -- [ ] Обновлен badge версии в `README.md` -- [ ] Все тесты проходят: `python test_components.py` -- [ ] Нет linter ошибок -- [ ] Документация актуальна - -### Сборка: - -- [ ] Собран .exe: `build.bat` -- [ ] Протестирован .exe на чистой системе -- [ ] Создан offline installer: `portable_installer.bat` -- [ ] Созданы контрольные суммы SHA256 -- [ ] Обновлены скриншоты (если есть) - -### Публикация: - -- [ ] Создан Git tag: `git tag v1.0.2` -- [ ] Создан GitHub Release -- [ ] Загружены файлы: - - Votobu.exe - - Votobu-v1.0.2-Windows.zip - - Votobu-Offline-Installer-v1.0.2.zip - - SHA256 checksums -- [ ] Обновлена документация на GitHub - ---- - -## 🐛 Решение проблем при сборке - -### PyInstaller не находит модули - -**Проблема:** -``` -ModuleNotFoundError during analysis -``` - -**Решение:** -Добавить `--hidden-import`: -```bash ---hidden-import=module_name -``` - -### .exe слишком большой - -**Проблема:** -.exe файл > 500 MB - -**Решения:** -1. Использовать `--onefile` вместо `--onedir` -2. Исключить ненужные модули: - ```bash - --exclude-module=matplotlib - --exclude-module=scipy - ``` -3. Использовать UPX компрессию: - ```bash - --upx-dir=C:\upx - ``` - -### .exe долго запускается - -**Причина:** -`--onefile` распаковывает все во временную папку при каждом запуске - -**Решение:** -Использовать `--onedir` для более быстрого запуска (но больше файлов) - -### Антивирус блокирует .exe - -**Причина:** -PyInstaller .exe файлы иногда определяются как подозрительные - -**Решения:** -1. Подписать .exe цифровой подписью -2. Добавить в исключения антивируса -3. Сообщить о ложном срабатывании - ---- - -## 📚 Дополнительные ресурсы - -- [PyInstaller Manual](https://pyinstaller.org/en/stable/) -- [Python Wheels](https://pythonwheels.com/) -- [Инструкция по упаковке Python приложений](https://packaging.python.org/) - ---- - -
- -**Готовые дистрибутивы делают ваше приложение доступным для всех!** 🎁 - -
- diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md deleted file mode 100644 index 89e010c..0000000 --- a/PROJECT_STRUCTURE.md +++ /dev/null @@ -1,434 +0,0 @@ -# Структура проекта Votobu - -## Обзор архитектуры - -Votobu - модульное приложение на Python с четким разделением ответственности между компонентами. - -## Структура файлов - -``` -Votobu/ -│ -├── src/ # Исходный код приложения -│ ├── __init__.py # Инициализация пакета -│ ├── main.py # Точка входа, координация компонентов -│ ├── config_manager.py # Управление конфигурацией (JSON) -│ ├── audio_recorder.py # Запись аудио (sounddevice) -│ ├── speech_recognizer.py # Распознавание речи (Whisper) -│ ├── hotkey_manager.py # Глобальные горячие клавиши (pynput) -│ ├── settings_window.py # Окно настроек (PyQt5) -│ └── tray_app.py # Системный трей (PyQt5) -│ -├── assets/ # Ресурсы приложения -│ ├── icon.png # Основная иконка (синий микрофон) -│ └── icon_recording.png # Иконка записи (красный микрофон) -│ -├── config/ # Конфигурационные файлы -│ └── default_config.json # Конфигурация по умолчанию -│ -├── requirements.txt # Python зависимости -├── .gitignore # Git исключения -│ -├── create_icons.py # Скрипт создания иконок -├── install.bat # Автоматическая установка (Windows) -├── run.bat # Запуск приложения (Windows) -│ -├── README.md # Основная документация -├── INSTALL.md # Инструкция по установке -├── USAGE.md # Руководство пользователя -└── PROJECT_STRUCTURE.md # Этот файл -``` - -## Компоненты приложения - -### 1. main.py - Главный координатор - -**Класс:** `VotobuApp` - -**Ответственность:** -- Инициализация всех компонентов -- Связывание событий между модулями -- Управление жизненным циклом приложения - -**Поток данных:** -``` -HotkeyManager → AudioRecorder → SpeechRecognizer → Clipboard → User - ↓ ↓ - TrayApp (UI feedback) -``` - -### 2. config_manager.py - Управление настройками - -**Класс:** `ConfigManager` - -**Возможности:** -- Загрузка/сохранение настроек в JSON -- Хранение в %APPDATA%/Votobu/config.json -- Значения по умолчанию -- Валидация конфигурации - -**Настройки:** -- `hotkey`: горячая клавиша (по умолчанию: "f9") -- `language`: язык распознавания (по умолчанию: "ru") -- `whisper_model`: модель Whisper (по умолчанию: "base") -- `sample_rate`: частота дискретизации (16000 Hz) -- `channels`: каналы аудио (1 - моно) - -### 3. audio_recorder.py - Запись аудио - -**Класс:** `AudioRecorder` - -**Технологии:** -- `sounddevice`: захват аудио с микрофона -- `soundfile`: сохранение в WAV формат -- `numpy`: обработка аудио массивов - -**Процесс:** -1. `start()` - начало записи, создание потока -2. Накопление аудио данных в буфере -3. `stop()` - остановка, объединение чанков -4. Сохранение во временный WAV файл (16kHz mono) -5. `cleanup()` - удаление временных файлов - -### 4. speech_recognizer.py - Распознавание речи - -**Класс:** `SpeechRecognizer` - -**Технологии:** -- `openai-whisper`: модель распознавания речи - -**Возможности:** -- Загрузка моделей: tiny, base, small, medium, large -- Поддержка языков: ru, en, auto -- Синхронное и асинхронное распознавание -- Автоматическое определение языка - -**Процесс:** -1. Загрузка модели (первый раз требует интернет) -2. Транскрибация аудио файла -3. Возврат текста - -### 5. hotkey_manager.py - Горячие клавиши - -**Класс:** `HotkeyManager` - -**Технологии:** -- `pynput`: глобальный перехват клавиатуры - -**Возможности:** -- Глобальные горячие клавиши (работают во всех приложениях) -- Поддержка F1-F12, букв, цифр, специальных клавиш -- События: on_press, on_release -- Динамическое изменение клавиши - -**Маппинг клавиш:** -```python -KEY_MAPPING = { - 'f1'-'f12': Function keys, - 'ctrl', 'shift', 'alt': Modifiers, - 'space', 'enter', 'tab', 'esc': Special keys, - 'a'-'z', '0'-'9': Alphanumeric -} -``` - -### 6. settings_window.py - Окно настроек - -**Класс:** `SettingsWindow` - -**Технологии:** -- `PyQt5`: GUI фреймворк - -**Компоненты:** -- Выбор горячей клавиши (перехват нажатия) -- Выбор языка (русский/английский/авто) -- Выбор модели Whisper (dropdown) -- Кнопки Сохранить/Отмена - -**Сигналы:** -- `settings_saved`: emit при сохранении настроек - -### 7. tray_app.py - Системный трей - -**Класс:** `TrayApp` - -**Технологии:** -- `PyQt5.QtWidgets.QSystemTrayIcon` - -**Функционал:** -- Иконка в системном трее -- Контекстное меню: - - Статус (текущее состояние) - - Настройки - - О программе - - Выход -- Динамическое изменение иконки (обычная/запись) -- Уведомления (notifications) - -**Состояния:** -- Готов к записи (синяя иконка) -- Запись (красная иконка) -- Распознавание (статус текст) - -## Поток работы приложения - -### Инициализация (startup) - -``` -1. QApplication создается -2. ConfigManager загружает настройки -3. AudioRecorder инициализируется -4. SpeechRecognizer загружает модель Whisper -5. HotkeyManager начинает перехват клавиш -6. TrayApp показывает иконку в трее -7. Уведомление "Votobu запущен" -``` - -### Цикл записи/распознавания - -``` -[Пользователь зажимает F9] - ↓ -HotkeyManager.on_press() - ↓ -AudioRecorder.start() - ↓ -TrayApp.set_recording_state(True) → Красная иконка - ↓ -[Пользователь говорит в микрофон] - ↓ -AudioRecorder накапливает аудио в буфере - ↓ -[Пользователь отпускает F9] - ↓ -HotkeyManager.on_release() - ↓ -AudioRecorder.stop() → возвращает путь к WAV файлу - ↓ -TrayApp.set_recognizing_state() → "Распознавание..." - ↓ -SpeechRecognizer.recognize_async(wav_file) - ↓ -Whisper транскрибирует аудио - ↓ -Текст возвращается через callback - ↓ -pyperclip.copy(text) → Буфер обмена - ↓ -AudioRecorder.cleanup() → Удаление временного файла - ↓ -TrayApp.show_notification("Текст распознан") - ↓ -TrayApp.set_recording_state(False) → Синяя иконка -``` - -### Изменение настроек - -``` -[ПКМ на иконке → Настройки] - ↓ -SettingsWindow.show() - ↓ -[Пользователь изменяет настройки] - ↓ -[Нажимает "Сохранить"] - ↓ -SettingsWindow.settings_saved.emit(new_config) - ↓ -VotobuApp._on_settings_saved(new_config) - ↓ -ConfigManager.save_config(new_config) - ↓ -Обновление компонентов: - - HotkeyManager.change_hotkey() - - SpeechRecognizer.change_language() - - SpeechRecognizer.change_model() -``` - -## Зависимости - -### Основные библиотеки - -```python -PyQt5 # GUI и системный трей -openai-whisper # AI распознавание речи -sounddevice # Захват аудио с микрофона -soundfile # Сохранение аудио файлов -pynput # Глобальные горячие клавиши -pyperclip # Буфер обмена -numpy # Обработка аудио данных -Pillow # Создание иконок -``` - -### Граф зависимостей - -``` -main.py -├── config_manager.py -├── audio_recorder.py -│ ├── sounddevice -│ ├── soundfile -│ └── numpy -├── speech_recognizer.py -│ └── whisper -├── hotkey_manager.py -│ └── pynput -├── settings_window.py -│ └── PyQt5 -└── tray_app.py - └── PyQt5 -``` - -## Хранение данных - -### Конфигурация - -**Путь:** `%APPDATA%\Votobu\config.json` (Windows) - -**Формат:** -```json -{ - "hotkey": "f9", - "language": "ru", - "whisper_model": "base", - "sample_rate": 16000, - "channels": 1 -} -``` - -### Временные файлы - -**Аудио записи:** -- Путь: системная временная папка -- Формат: `votobu_XXXXXX.wav` -- Очистка: автоматическая после распознавания - -### Модели Whisper - -**Путь:** `~/.cache/whisper/` (по умолчанию) - -**Размеры:** -- tiny: ~75 MB -- base: ~150 MB -- small: ~500 MB -- medium: ~1.5 GB -- large: ~3 GB - -## Потоки и асинхронность - -### Потоки выполнения - -1. **Main Thread (PyQt)** - - GUI события - - Системный трей - - Окно настроек - -2. **Hotkey Listener Thread (pynput)** - - Глобальный перехват клавиш - - Запускается автоматически pynput - -3. **Audio Recording Thread (sounddevice)** - - Захват аудио с микрофона - - Callback функция для данных - -4. **Recognition Thread** - - Асинхронное распознавание - - Создается для каждой транскрибации - -### Синхронизация - -- **Callbacks** используются для связи между потоками -- **pyqtSignal** для GUI обновлений -- **Threading-safe** операции с файлами - -## Расширяемость - -### Добавление новых языков - -```python -# В settings_window.py -self.language_combo.addItems(["Русский", "Английский", "Немецкий", ...]) - -# Маппинг -lang_map = {0: 'ru', 1: 'en', 2: 'de', ...} -``` - -### Добавление новых форматов аудио - -```python -# В audio_recorder.py -sf.write(temp_file.name, audio_array, self.sample_rate, - format='FLAC', # Вместо WAV - subtype='PCM_16') -``` - -### Добавление кнопок мыши как hotkey - -```python -# В hotkey_manager.py -from pynput.mouse import Listener as MouseListener - -# Добавить mouse listener параллельно keyboard listener -``` - -## Тестирование - -### Ручное тестирование - -1. **Запись аудио:** - - Зажать клавишу → проверить красную иконку - - Говорить → проверить захват звука - - Отпустить → проверить остановку - -2. **Распознавание:** - - Короткие фразы (5 сек) - - Длинные фразы (30 сек) - - Разные языки - -3. **Настройки:** - - Изменить клавишу → проверить работу - - Изменить язык → проверить качество - - Изменить модель → проверить скорость - -### Автоматическое тестирование - -```python -# Пример unit теста для ConfigManager -def test_config_manager(): - cm = ConfigManager() - assert cm.get('hotkey') == 'f9' - cm.set('hotkey', 'f8') - assert cm.get('hotkey') == 'f8' -``` - -## Производительность - -### Узкие места - -1. **Загрузка модели Whisper** (~5-30 сек при первом запуске) -2. **Транскрибация** (~0.5-2x реального времени аудио) -3. **Инициализация audio stream** (~1-2 сек) - -### Оптимизации - -- Модель загружается асинхронно при старте -- Аудио стрим остается открытым -- Временные файлы минимальны (только WAV) - -## Известные ограничения - -1. **Pynput:** может требовать права администратора на некоторых системах -2. **Whisper:** требует CPU/GPU ресурсов для распознавания -3. **PyQt5:** окно настроек может мигать при открытии -4. **Cross-platform:** полная поддержка только Windows - -## Будущие улучшения - -- [ ] GPU ускорение для Whisper -- [ ] Streaming распознавание (реальное время) -- [ ] История распознанных текстов -- [ ] Кастомные словари для специальных терминов -- [ ] Поддержка комбинаций клавиш (Ctrl+Shift+F9) -- [ ] Экспорт в разные форматы (TXT, DOCX, PDF) -- [ ] Интеграция с облачными сервисами -- [ ] Поддержка macOS и Linux - diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md deleted file mode 100644 index d6ef256..0000000 --- a/PROJECT_SUMMARY.md +++ /dev/null @@ -1,457 +0,0 @@ -# Votobu - Итоговое описание проекта - -## 🎉 Проект завершен! - -Полностью функциональное приложение для преобразования голоса в текст с глобальными горячими клавишами готово к использованию. - ---- - -## 📦 Что создано - -### Основные модули (7 файлов) - -1. **main.py** (175 строк) - - Точка входа приложения - - Координация всех компонентов - - Обработка жизненного цикла - -2. **config_manager.py** (108 строк) - - Загрузка/сохранение настроек в JSON - - Управление конфигурацией в %APPDATA% - - Значения по умолчанию - -3. **audio_recorder.py** (147 строк) - - Запись аудио через sounddevice - - Сохранение в WAV формат (16kHz mono) - - Автоматическая очистка временных файлов - -4. **speech_recognizer.py** (134 строк) - - Интеграция с OpenAI Whisper - - Синхронное и асинхронное распознавание - - Поддержка множества языков - -5. **hotkey_manager.py** (171 строк) - - Глобальный перехват клавиатуры через pynput - - Поддержка F1-F12, букв, цифр, спецклавиш - - Динамическое изменение горячих клавиш - -6. **settings_window.py** (263 строки) - - GUI окно настроек на PyQt5 - - Интерактивный выбор горячей клавиши - - Выбор языка и модели Whisper - -7. **tray_app.py** (187 строк) - - Иконка в системном трее - - Контекстное меню - - Уведомления пользователю - -**Итого исходного кода:** ~1200 строк Python - ---- - -### Утилиты и скрипты (4 файла) - -1. **create_icons.py** - генерация иконок микрофона -2. **test_components.py** - тестирование модулей -3. **install.bat** - автоматическая установка (Windows) -4. **run.bat** - быстрый запуск (Windows) - ---- - -### Документация (6 файлов) - -1. **README.md** - главная страница проекта с badges -2. **QUICKSTART.md** - быстрый старт за 3 шага -3. **INSTALL.md** - подробная установка и troubleshooting -4. **USAGE.md** - полное руководство пользователя (500+ строк) -5. **PROJECT_STRUCTURE.md** - архитектура и технические детали -6. **CHANGELOG.md** - история версий и планы - ---- - -### Ресурсы - -1. **assets/icon.png** - синяя иконка микрофона (64x64) -2. **assets/icon_recording.png** - красная иконка записи (64x64) -3. **config/default_config.json** - конфигурация по умолчанию -4. **LICENSE** - MIT лицензия -5. **.gitignore** - исключения для Git - ---- - -## 🏗️ Архитектура - -### Модульная структура - -``` -┌─────────────────────────────────────────────────────┐ -│ main.py │ -│ (Координатор приложения) │ -└─────────────────────────────────────────────────────┘ - │ - ├──> config_manager.py (Настройки) - │ - ├──> hotkey_manager.py (Клавиши) ───┐ - │ │ - ├──> audio_recorder.py (Запись) ────┼──> Поток работы - │ │ - ├──> speech_recognizer.py (AI) ────────┤ - │ │ - ├──> tray_app.py (GUI) ────────┘ - │ - └──> settings_window.py (Настройки GUI) -``` - -### Поток данных - -``` -[User] ─┬─> [Hotkey Press] ───> [Audio Start] ───> [Recording] - │ │ - └─> [Hotkey Release] ──> [Audio Stop] ────────┘ - │ - ▼ - [WAV File Created] - │ - ▼ - [Whisper Transcribe] - │ - ▼ - [Text Result] - │ - ▼ - [Clipboard Copy] - │ - ▼ - [Notification] - │ - ▼ - [User Paste] -``` - ---- - -## 🔧 Технические характеристики - -### Зависимости (8 пакетов) - -``` -PyQt5 5.15.10 - GUI фреймворк -openai-whisper latest - AI модель -sounddevice 0.4.6 - Захват аудио -soundfile 0.12.1 - WAV файлы -pynput 1.7.6 - Глобальные hotkeys -pyperclip 1.8.2 - Буфер обмена -numpy 1.24.3 - Обработка данных -Pillow 10.0.0 - Иконки -``` - -### Производительность - -**Загрузка модели Whisper:** -- tiny: ~5 сек, 75 MB -- base: ~10 сек, 150 MB -- small: ~20 сек, 500 MB -- medium: ~40 сек, 1.5 GB - -**Скорость распознавания (модель base):** -- 5 сек аудио → ~3-5 сек обработки -- 10 сек аудио → ~5-10 сек обработки -- 30 сек аудио → ~15-30 сек обработки - -**Потребление ресурсов:** -- RAM: 1-2 GB (base), 4-5 GB (medium) -- CPU: активное использование во время распознавания -- Диск: ~200 MB (code + модель base) - ---- - -## ✅ Реализованные функции - -### Основной функционал -- ✅ Запись аудио с микрофона -- ✅ AI распознавание речи (Whisper) -- ✅ Глобальные горячие клавиши -- ✅ Системный трей -- ✅ Уведомления -- ✅ Копирование в буфер обмена - -### Настройки -- ✅ Выбор горячей клавиши (F1-F12, буквы, цифры) -- ✅ Выбор языка (ru, en, auto) -- ✅ Выбор модели Whisper (5 вариантов) -- ✅ Сохранение настроек - -### UI/UX -- ✅ Иконка в трее (синяя/красная) -- ✅ Контекстное меню -- ✅ Окно настроек с GUI -- ✅ Статус индикатор -- ✅ Информационное окно "О программе" - -### Безопасность -- ✅ Локальная обработка (без отправки в облако) -- ✅ Автоматическое удаление временных файлов -- ✅ Безопасное хранение настроек - ---- - -## 📊 Статистика проекта - -### Файлы -- Python модули: 7 -- Утилиты: 4 -- Документация: 6 -- Ресурсы: 5 -- **Всего: 22 файла** - -### Строки кода -- Исходный код: ~1200 строк -- Документация: ~2500 строк -- Комментарии: ~200 строк -- **Всего: ~3900 строк** - -### Документация -- README: подробный с badges -- Руководств: 3 (Quick/Install/Usage) -- Технических документов: 2 -- **Покрытие: 100% функций** - ---- - -## 🎯 Возможности использования - -### Для кого это приложение? - -**Писатели и журналисты:** -- Быстрая диктовка текста -- Конспекты интервью -- Черновики статей - -**Программисты:** -- Диктовка комментариев -- Описание функций -- Commit messages - -**Студенты:** -- Конспекты лекций -- Заметки -- Переводы - -**Офисные работники:** -- Email диктовка -- Быстрые заметки -- Протоколы встреч - -**Все пользователи:** -- Диктовка вместо набора текста -- Работа без рук (hands-free) -- Ускорение ввода текста - ---- - -## 🚀 Как начать использовать - -### Быстрый старт (5 минут) - -```bash -# 1. Установка -git clone -cd Votobu -install.bat - -# 2. Запуск -run.bat - -# 3. Использование -# Зажмите F9, говорите, отпустите F9, нажмите Ctrl+V -``` - -### Первые шаги - -1. **Тестовая запись:** - ``` - F9 → "Привет, мир!" → Отпустить F9 → Ctrl+V - ``` - -2. **Настройка под себя:** - ``` - ПКМ на иконке → Настройки → Изменить язык/модель - ``` - -3. **Ежедневное использование:** - ``` - Автозапуск: Win+R → shell:startup → Ярлык на run.bat - ``` - ---- - -## 🔮 Будущие улучшения - -### Версия 1.1 (Планируется) -- [ ] GPU ускорение для Whisper -- [ ] История распознанных текстов -- [ ] Экспорт в форматы (TXT, DOCX) -- [ ] Темная тема -- [ ] Комбинации клавиш (Ctrl+Shift+F9) - -### Версия 1.2 (В планах) -- [ ] Streaming распознавание -- [ ] Кастомные словари -- [ ] Постобработка текста -- [ ] Полная поддержка macOS/Linux -- [ ] API для интеграций - -### Версия 2.0 (Идеи) -- [ ] Мобильная версия -- [ ] Облачная синхронизация -- [ ] Плагины и расширения -- [ ] Голосовые команды - ---- - -## 📚 Документация (6 файлов) - -| Файл | Назначение | Размер | -|------|-----------|--------| -| README.md | Главная страница | ~250 строк | -| QUICKSTART.md | Быстрый старт | ~200 строк | -| INSTALL.md | Установка и troubleshooting | ~250 строк | -| USAGE.md | Полное руководство | ~500 строк | -| PROJECT_STRUCTURE.md | Архитектура | ~600 строк | -| CHANGELOG.md | История версий | ~200 строк | - -**Общая документация: ~2000 строк** - ---- - -## 🧪 Тестирование - -### Автоматическая проверка - -```bash -python test_components.py -``` - -Проверяет: -- ✓ Версию Python -- ✓ Установку зависимостей -- ✓ Структуру проекта -- ✓ Импорт модулей -- ✓ Инициализацию компонентов - -### Ручное тестирование - -1. **Запись:** Зажать F9 → иконка красная → говорить → отпустить -2. **Распознавание:** Статус "Распознавание" → уведомление -3. **Буфер:** Ctrl+V → текст вставлен -4. **Настройки:** ПКМ → Настройки → изменения работают - ---- - -## 🎓 Что можно изучить из этого проекта - -### Python разработка -- Модульная архитектура -- Работа с потоками -- Обработка событий -- Работа с файлами и конфигурацией - -### GUI программирование -- PyQt5 системный трей -- Окна и формы -- События и сигналы -- Иконки и уведомления - -### Аудио обработка -- Захват с микрофона -- Работа с WAV форматом -- Буферизация данных -- Временные файлы - -### AI интеграция -- Локальные AI модели -- Whisper API -- Асинхронная обработка -- Оптимизация производительности - -### Системное программирование -- Глобальные hotkeys -- Работа с системным треем -- Автозапуск приложений -- Кроссплатформенность - ---- - -## 🏆 Достижения проекта - -✅ **Полностью функциональное приложение** -✅ **Модульная архитектура** -✅ **Подробная документация** -✅ **Удобная установка** -✅ **Интуитивный интерфейс** -✅ **Высокое качество кода** -✅ **Тестовое покрытие** -✅ **MIT лицензия** - ---- - -## 💡 Ключевые преимущества - -1. **Приватность** - все локально, без облака -2. **Простота** - установка за 5 минут -3. **Удобство** - работает во всех приложениях -4. **Гибкость** - настраиваемые параметры -5. **Качество** - OpenAI Whisper AI -6. **Бесплатность** - открытый исходный код -7. **Документированность** - полное руководство -8. **Расширяемость** - модульная архитектура - ---- - -## 🎯 Целевая аудитория - -- **Новички:** простота использования -- **Профессионалы:** гибкие настройки -- **Разработчики:** открытый код -- **Исследователи:** AI интеграция -- **Студенты:** обучающий проект - ---- - -## 📈 Потенциал проекта - -### Применение -- Личное использование -- Офисная работа -- Образование -- Разработка ПО -- Контент-создание - -### Расширения -- Коммерческая версия -- Корпоративные решения -- Образовательная платформа -- API сервис -- Мобильные приложения - ---- - -## 🎊 Заключение - -Проект **Votobu** - это полнофункциональное, хорошо документированное приложение для преобразования голоса в текст с использованием современных технологий AI, готовое к использованию и дальнейшему развитию. - -**Статус:** ✅ Готово к использованию -**Версия:** 1.0.0 -**Дата:** 2025-11-09 -**Лицензия:** MIT - ---- - -
- -**Спасибо за внимание! 🎉** - -**Используйте, модифицируйте, делитесь!** - -
- diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index be2b60f..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,200 +0,0 @@ -# Быстрый старт Votobu - -## За 3 шага к работающему приложению - -### Шаг 1: Установка (5 минут) - -```bash -# Запустите автоматическую установку -install.bat - -# ИЛИ вручную: -pip install -r requirements.txt -python create_icons.py -``` - -### Шаг 2: Запуск (1 секунда) - -```bash -# Двойной клик на: -run.bat - -# ИЛИ через командную строку: -python src/main.py -``` - -### Шаг 3: Использование (просто!) - -1. **Найдите иконку** в системном трее (справа внизу) -2. **Зажмите F9** и говорите в микрофон -3. **Отпустите F9** - подождите пару секунд -4. **Нажмите Ctrl+V** - текст вставлен! - ---- - -## Первое использование - -### Что произойдет при первом запуске? - -1. Появится иконка микрофона в трее -2. Whisper загрузит модель (~150 MB, требует интернет) -3. Появится уведомление "Votobu запущен" -4. Готово к работе! - -### Первая запись - -``` -Пример: Зажмите F9 → "Привет, мир!" → Отпустите F9 → Ctrl+V -``` - -**Ожидаемый результат:** -- Иконка станет красной -- Через 2-5 секунд уведомление "Текст распознан" -- В буфере: "Привет, мир!" - ---- - -## Настройка под себя - -### Открыть настройки - -``` -ПКМ на иконке → Настройки -``` - -### Изменить горячую клавишу - -1. Кнопка "Изменить клавишу" -2. Нажмите желаемую клавишу (например, F8) -3. Сохранить - -### Выбрать язык - -- **Русский** - если говорите только по-русски (быстрее) -- **Английский** - если говорите только по-английски (быстрее) -- **Автоопределение** - если переключаетесь между языками - -### Выбрать модель - -| Модель | Когда использовать | -|--------|-------------------| -| tiny | Очень слабый ПК, нужна максимальная скорость | -| **base** | **По умолчанию - лучший баланс** | -| small | Хороший ПК, нужно лучше качество | -| medium | Мощный ПК, важна точность | -| large | Очень мощный ПК, нужна максимальная точность | - ---- - -## Частые вопросы - -### Ничего не происходит при нажатии F9 - -1. Проверьте, запущено ли приложение (иконка в трее) -2. Попробуйте другую клавишу (может быть занята) -3. Проверьте, работает ли микрофон - -### Плохо распознает текст - -1. Говорите медленнее и четче -2. Уменьшите фоновый шум -3. Попробуйте модель `small` или `medium` -4. Укажите конкретный язык (не "авто") - -### Долго обрабатывает - -1. Это нормально для первого раза (загрузка модели) -2. Попробуйте модель `tiny` или `base` -3. Записывайте короче (5-15 секунд) - -### Как закрыть приложение - -``` -ПКМ на иконке → Выход -``` - ---- - -## Советы для лучшего результата - -### ✅ Делайте - -- Говорите четко, в нормальном темпе -- Держите микрофон на расстоянии 15-30 см -- Записывайте в тихом месте -- Делайте паузы между предложениями - -### ❌ Избегайте - -- Очень быстрой речи -- Шумной обстановки (вентиляторы, музыка) -- Очень длинных записей (>60 секунд) -- Слишком тихого или громкого голоса - ---- - -## Примеры использования - -### Диктовка письма - -``` -[F9] "Здравствуйте, Иван Иванович. Хотел бы обсудить проект." [Отпустить] -→ Ctrl+V в почту -``` - -### Быстрые заметки - -``` -[F9] "Купить молоко, хлеб, сыр" [Отпустить] -→ Ctrl+V в блокнот -``` - -### Программирование - -``` -[F9] "функция для валидации email адреса" [Отпустить] -→ Ctrl+V в комментарий кода -``` - ---- - -## Что дальше? - -### Полная документация - -- **INSTALL.md** - подробная установка и решение проблем -- **USAGE.md** - полное руководство пользователя -- **README.md** - общая информация о проекте - -### Проверка системы - -```bash -python test_components.py -``` - -Покажет, все ли компоненты установлены правильно. - -### Помощь - -Если что-то не работает: -1. Прочитайте раздел "Решение проблем" в INSTALL.md -2. Запустите test_components.py для диагностики -3. Проверьте консольный вывод при запуске через `python src/main.py` - ---- - -## Удаление - -Если приложение не понравилось: - -```bash -# 1. Закрыть приложение (ПКМ → Выход) -# 2. Удалить папку проекта -# 3. Удалить настройки: -del %APPDATA%\Votobu /s /q -``` - ---- - -**Приятного использования! 🎤** - diff --git a/QUICK_HOTKEY_GUIDE.txt b/QUICK_HOTKEY_GUIDE.txt deleted file mode 100644 index b08450e..0000000 --- a/QUICK_HOTKEY_GUIDE.txt +++ /dev/null @@ -1,111 +0,0 @@ -════════════════════════════════════════════════════════════════ - 🎯 БЫСТРЫЙ ГАЙД: Настройка горячих клавиш в Votobu -════════════════════════════════════════════════════════════════ - -📌 КАК ИЗМЕНИТЬ ГОРЯЧУЮ КЛАВИШУ: - -1. ПКМ на иконку в трее → "Настройки" -2. Нажмите кнопку "Изменить клавишу" -3. Нажмите желаемую клавишу или кнопку мыши -4. Нажмите "Сохранить" -5. 💡 Рекомендуется перезапустить программу! - (ПКМ → Выход → Запустить заново) -6. Готово! ✅ - -════════════════════════════════════════════════════════════════ - -⌨️ ПОДДЕРЖИВАЕМЫЕ КЛАВИШИ КЛАВИАТУРЫ: - -✅ F1-F12 - Функциональные клавиши -✅ A-Z - Все буквы -✅ 0-9 - Все цифры -✅ Space, Enter, Esc - Специальные клавиши -✅ Home, End, Page Up/Down - Навигация -✅ Delete, Insert - Редактирование -✅ Стрелки (↑↓←→) - Навигационные стрелки - -════════════════════════════════════════════════════════════════ - -🖱️ ПОДДЕРЖИВАЕМЫЕ КНОПКИ МЫШИ: - -✅ Боковая кнопка назад (X1) ⭐ РЕКОМЕНДУЕТСЯ! -✅ Боковая кнопка вперед (X2) ⭐ РЕКОМЕНДУЕТСЯ! -✅ Средняя кнопка (колесико) -✅ Левая кнопка -✅ Правая кнопка - -════════════════════════════════════════════════════════════════ - -💡 РЕКОМЕНДАЦИИ: - -🥇 ЛУЧШИЕ ВАРИАНТЫ: - → Mouse X1/X2 (боковые кнопки) - не мешают работе! - → F9, F10, F11, F12 - классический выбор - → R, V, T (буквы) - легко запомнить - -❌ НЕ РЕКОМЕНДУЕТСЯ: - → Space - используется для пробелов - → Enter - используется для подтверждения - → Mouse Left/Right - постоянно используются - -════════════════════════════════════════════════════════════════ - -🎮 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ: - -Для программистов: - Горячая клавиша: Mouse X1 (боковая) - Почему: Рука на мыши, легко нажать большим пальцем - -Для писателей: - Горячая клавиша: F10 - Почему: Руки на клавиатуре, не конфликтует с редактором - -Для геймеров: - Горячая клавиша: Mouse X2 - Почему: Не мешает WASD и мышке - -════════════════════════════════════════════════════════════════ - -❓ FAQ: - -Q: Нужно ли перезапускать программу после изменения клавиши? -A: Рекомендуется! Хотя программа пытается применить изменения - автоматически, перезапуск гарантирует корректную работу. - Вы получите уведомление с инструкцией. - -Q: Почему не работает боковая кнопка мыши? -A: Проверьте что: - 1. Ваша мышь имеет боковые кнопки - 2. Кнопки не переназначены в драйвере мыши - 3. Попробуйте другую боковую кнопку (X1 или X2) - -Q: Можно ли использовать комбинации (Ctrl+R)? -A: Пока нет, планируется в будущих версиях - -Q: Горячая клавиша не работает в игре? -A: Некоторые игры блокируют hotkeys (античит). - Попробуйте запустить Votobu от имени администратора - или используйте кнопку мыши. - -════════════════════════════════════════════════════════════════ - -🧪 ТЕСТИРОВАНИЕ: - -Чтобы протестировать клавиши/кнопки: - python test_hotkeys.py - -════════════════════════════════════════════════════════════════ - -📖 ПОДРОБНАЯ ДОКУМЕНТАЦИЯ: - -→ HOTKEYS.md - полное руководство по горячим клавишам -→ README.md - основная документация -→ TROUBLESHOOTING.md - решение проблем - -════════════════════════════════════════════════════════════════ - -Версия: 1.0.3 -Дата: 2025-11-09 - -════════════════════════════════════════════════════════════════ - diff --git a/README.md b/README.md deleted file mode 100644 index d6009c9..0000000 --- a/README.md +++ /dev/null @@ -1,294 +0,0 @@ -# Votobu - Voice-to-Text Hotkey Application - -> 🎤 Преобразование голоса в текст по нажатию клавиши. Локально. Быстро. Просто. - -[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/) -[![Version](https://img.shields.io/badge/Version-1.0.3-brightgreen.svg)](CHANGELOG.md) -[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) -[![Platform](https://img.shields.io/badge/Platform-Windows-lightgrey.svg)](https://www.microsoft.com/windows) - -Приложение для преобразования голоса в текст с использованием глобальных горячих клавиш и OpenAI Whisper. Работает полностью локально - ваши данные не покидают компьютер. - ---- - -## ✨ Возможности - -- 🎤 **Запись аудио** по нажатию горячей клавиши -- 🤖 **AI распознавание** через OpenAI Whisper (работает локально) -- 📋 **Автокопирование** текста в буфер обмена -- ⌨️ **Глобальные hotkeys** - клавиши И кнопки мыши, работают везде -- 🔔 **Системный трей** с уведомлениями -- ⚙️ **Гибкие настройки** - клавиши, языки, модели -- 💾 **Сохранение настроек** между запусками -- 🔒 **Приватность** - все работает локально, без интернета (после установки) -- 🌍 **Многоязычность** - русский, английский и другие языки - ---- - -## 🚀 Быстрый старт - -### За 3 простых шага: - -#### 1️⃣ Установка -```bash -# Автоматическая установка (Windows) -install.bat - -# ИЛИ вручную -pip install -r requirements.txt -python create_icons.py -``` - -#### 2️⃣ Запуск -```bash -# С консолью (для отладки) -run.bat - -# БЕЗ консоли (рекомендуется) 👈 -Votobu_HideConsole.vbs # Просто двойной клик! - -# ИЛИ создать ярлык -create_shortcut.bat -``` - -#### 3️⃣ Использование -``` -Зажать F9 → Говорить → Отпустить F9 → Ctrl+V → Готово! -``` - -📖 **Подробнее:** [QUICKSTART.md](QUICKSTART.md) - ---- - -## 📋 Требования - -- **OS:** Windows 10/11 (Linux/Mac - частичная поддержка) -- **Python:** 3.8 или выше -- **RAM:** 2+ GB (4+ GB для больших моделей) -- **Диск:** 500 MB+ свободного места -- **Микрофон:** любой подключенный микрофон -- **Интернет:** только для первой загрузки модели Whisper - ---- - -## 🎯 Использование - -### Базовый сценарий - -1. **Запустите** приложение (появится иконка в трее) -2. **Зажмите** горячую клавишу (F9) -3. **Говорите** в микрофон четко и ясно -4. **Отпустите** клавишу -5. **Подождите** 2-10 секунд (зависит от длины записи) -6. **Вставьте** текст через Ctrl+V - -### Примеры использования - -**Диктовка письма:** -``` -[F9] "Здравствуйте! Хотел бы обсудить проект..." [Отпустить F9] -→ Вставить в email через Ctrl+V -``` - -**Быстрые заметки:** -``` -[F9] "Купить молоко, хлеб и яйца" [Отпустить F9] -→ Вставить в заметки -``` - -**Программирование:** -``` -[F9] "функция для валидации пользовательского ввода" [Отпустить F9] -→ Вставить в комментарий кода -``` - ---- - -## ⚙️ Настройки - -### Открытие настроек -``` -ПКМ на иконке в трее → Настройки -``` - -### Доступные опции - -**Горячая клавиша:** -- По умолчанию: F9 -- **⌨️ Клавиатура**: F1-F12, A-Z, 0-9, Space, Enter, Esc, Delete и др. -- **🖱️ Мышь**: Левая, Правая, Средняя, Боковые кнопки (X1/X2) ⭐ - -**Язык распознавания:** -- 🇷🇺 Русский (оптимизация для русского) -- 🇬🇧 Английский (оптимизация для английского) -- 🌍 Автоопределение (поддержка всех языков Whisper) - -**Модель Whisper:** -| Модель | Размер | Скорость | Качество | -|--------|--------|----------|----------| -| tiny | ~75 MB | ⚡⚡⚡⚡⚡ | ⭐⭐ | -| **base** | ~150 MB | ⚡⚡⚡⚡ | ⭐⭐⭐ (рекомендуется) | -| small | ~500 MB | ⚡⚡⚡ | ⭐⭐⭐⭐ | -| medium | ~1.5 GB | ⚡⚡ | ⭐⭐⭐⭐⭐ | -| large | ~3 GB | ⚡ | ⭐⭐⭐⭐⭐⭐ | - ---- - -## 📚 Документация - -### Для пользователей: -- **[QUICKSTART.md](QUICKSTART.md)** - быстрый старт за 5 минут ⚡ -- **[INSTALL.md](INSTALL.md)** - подробная установка 📥 -- **[HOTKEYS.md](HOTKEYS.md)** - ⌨️🖱️ настройка горячих клавиш (новое!) -- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - 🔥 решение проблем (важно!) -- **[USAGE.md](USAGE.md)** - полное руководство пользователя 📖 -- **[RUN_WITHOUT_CONSOLE.md](RUN_WITHOUT_CONSOLE.md)** - запуск без консоли 👻 - -### Для разработчиков: -- **[CONTRIBUTING.md](CONTRIBUTING.md)** - как помочь проекту 🤝 -- **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** - архитектура проекта 🏗️ -- **[PACKAGING.md](PACKAGING.md)** - 📦 упаковка и распространение -- **[GITHUB_GUIDE.md](GITHUB_GUIDE.md)** - публикация на GitHub 🚀 -- **[CHANGELOG.md](CHANGELOG.md)** - история изменений 📝 - ---- - -## 🏗️ Структура проекта - -``` -Votobu/ -├── src/ # 📁 Исходный код -│ ├── main.py # 🚀 Точка входа -│ ├── config_manager.py # ⚙️ Управление настройками -│ ├── audio_recorder.py # 🎤 Запись аудио -│ ├── speech_recognizer.py # 🤖 AI распознавание -│ ├── hotkey_manager.py # ⌨️ Глобальные hotkeys -│ ├── settings_window.py # 🪟 Окно настроек -│ └── tray_app.py # 📍 Системный трей -├── assets/ # 🎨 Ресурсы -│ ├── icon.png # Иконка (обычная) -│ └── icon_recording.png # Иконка (запись) -├── config/ # 📝 Конфигурация -│ └── default_config.json -├── docs/ # 📖 Документация -│ ├── README.md -│ ├── INSTALL.md -│ ├── USAGE.md -│ └── ... -├── requirements.txt # 📦 Зависимости -├── install.bat # 🔧 Автоустановка -└── run.bat # ▶️ Быстрый запуск -``` - ---- - -## 🛠️ Технологии - -| Технология | Назначение | -|------------|------------| -| **PyQt5** | GUI и системный трей | -| **OpenAI Whisper** | AI распознавание речи (локально) | -| **sounddevice** | Захват аудио с микрофона | -| **soundfile** | Работа с аудио файлами | -| **pynput** | Глобальные горячие клавиши | -| **pyperclip** | Буфер обмена | -| **numpy** | Обработка аудио данных | -| **Pillow** | Создание иконок | - ---- - -## 📦 Упаковка и распространение - -### Вариант 1: Автоматическая установка (для пользователей) - -```bash -install.bat # Устанавливает все зависимости автоматически -``` - -### Вариант 2: Standalone .exe (не требует Python) - -```bash -build.bat # Создает Votobu.exe со всеми зависимостями -``` - -Результат: один .exe файл, который работает на любом Windows компьютере без установки Python! - -### Вариант 3: Offline Installer (без интернета) - -```bash -portable_installer.bat # Создает пакет для установки без интернета -``` - -**Подробнее:** см. [PACKAGING.md](PACKAGING.md) - ---- - -## 🧪 Тестирование - -Проверьте работоспособность компонентов: - -```bash -python test_components.py -``` - ---- - -## 🤝 Вклад в проект - -Приветствуются contributions! Любая помощь ценна - от исправления опечаток до добавления новых функций. - -### Как помочь: - -- 🐛 **Нашли баг?** [Создайте Issue](../../issues/new?template=bug_report.md) -- 💡 **Есть идея?** [Предложите улучшение](../../issues/new?template=feature_request.md) -- 💻 **Хотите кодить?** Прочитайте [CONTRIBUTING.md](CONTRIBUTING.md) -- 📝 **Улучшите документацию** - отправьте Pull Request -- ⭐ **Поставьте звезду** если проект понравился! - -### Области для улучшения: -- GPU ускорение для Whisper -- Streaming распознавание в реальном времени -- Поддержка macOS и Linux -- История распознанных текстов -- Кастомные словари - -**Подробнее:** [CONTRIBUTING.md](CONTRIBUTING.md) - ---- - -## 📝 Лицензия - -[MIT License](LICENSE) - свободное использование, модификация и распространение. - ---- - -## 🙏 Благодарности - -- [OpenAI Whisper](https://github.com/openai/whisper) - за отличную модель распознавания речи -- [PyQt5](https://www.riverbankcomputing.com/software/pyqt/) - за мощный GUI фреймворк -- Всем контрибьюторам open-source библиотек - ---- - -## 📞 Поддержка - -**Возникли проблемы?** -1. Прочитайте [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - полное руководство по решению проблем -2. Запустите `python test_components.py` для диагностики -3. Проверьте [INSTALL.md](INSTALL.md) - раздел "Решение проблем" -4. Создайте [Issue](https://github.com/username/votobu/issues) с описанием проблемы - -**Есть идеи?** -- Открывайте [Discussions](https://github.com/username/votobu/discussions) -- Делитесь в Issues - ---- - -
- -**Сделано с ❤️ для удобства работы с текстом** - -[⬆ Наверх](#votobu---voice-to-text-hotkey-application) - -
- diff --git a/RUN_WITHOUT_CONSOLE.md b/RUN_WITHOUT_CONSOLE.md deleted file mode 100644 index e1f0df3..0000000 --- a/RUN_WITHOUT_CONSOLE.md +++ /dev/null @@ -1,321 +0,0 @@ -# Запуск Votobu без консольного окна - -## 🎯 7 способов скрыть консоль - ---- - -### ⭐ Способ 1: VBS с программным скрытием консоли (Рекомендуется!) - -**Самый надежный способ - работает с PyQt окнами!** - -```bash -# Просто двойной клик: -Votobu_HideConsole.vbs -``` - -**Как работает:** -- Запускает `python.exe` (не pythonw!) -- Python программно скрывает консоль через Windows API -- Все PyQt окна (включая настройки) работают нормально - -**Преимущества:** -- ✅ Полностью невидимый запуск -- ✅ Окно настроек открывается -- ✅ Все функции работают -- ✅ Лучшая совместимость - ---- - -### 🚀 Способ 2: Обновленный VBS скрипт - -```bash -# Двойной клик: -Votobu.vbs -``` - -**Обновлено:** Теперь использует `python.exe` вместо `pythonw.exe` - -**Преимущества:** -- ✅ Полностью невидимый запуск -- ✅ Никаких мерцающих окон -- ✅ Работает из коробки -- ✅ Не требует дополнительных настроек - -**Как работает:** -VBS скрипт запускает `pythonw.exe` с флагом скрытого окна (0). - ---- - -### 🚀 Способ 2: Ярлык на рабочем столе - -**Создать удобный ярлык:** - -```bash -# Запустите один раз: -create_shortcut.bat -``` - -**Результат:** -- Ярлык "Votobu" появится на рабочем столе -- Двойной клик = запуск без консоли -- Красивая иконка микрофона - ---- - -### 🔧 Способ 3: run_silent.bat - -**Batch файл без консоли:** - -```bash -run_silent.bat -``` - -**Как работает:** -```batch -start "" pythonw.exe src\main.py -``` - -`pythonw.exe` = Python без консольного окна - ---- - -### 📝 Способ 4: .pyw файл - -**Запуск через .pyw расширение:** - -```bash -pythonw.exe src\main.pyw -``` - -**Или просто двойной клик на:** -``` -src\main.pyw -``` - -**Что такое .pyw?** -- Специальное расширение Python для GUI приложений -- Windows автоматически запускает через `pythonw.exe` -- Не показывает консоль - ---- - -### 💎 Способ 5: Собрать .exe (Лучший для распространения) - -**Один раз собрать - всегда без консоли:** - -```bash -# Установить PyInstaller -pip install pyinstaller - -# Собрать .exe -build.bat - -# Запустить -dist\Votobu.exe -``` - -**Преимущества:** -- ✅ Не требует Python на целевом ПК -- ✅ Всегда без консоли (флаг `--windowed`) -- ✅ Один файл для распространения -- ✅ Профессиональный вид - ---- - -## 📋 Сравнение способов - -| Способ | Простота | Скорость | Портативность | Рекомендация | -|--------|----------|----------|---------------|--------------| -| **Votobu.vbs** | ⭐⭐⭐⭐⭐ | ⚡⚡⚡⚡⚡ | 🔒 Требует Python | ✅ Для себя | -| **Ярлык** | ⭐⭐⭐⭐⭐ | ⚡⚡⚡⚡⚡ | 🔒 Требует Python | ✅ Удобство | -| **run_silent.bat** | ⭐⭐⭐⭐ | ⚡⚡⚡⚡⚡ | 🔒 Требует Python | ✅ Простота | -| **.pyw файл** | ⭐⭐⭐ | ⚡⚡⚡⚡⚡ | 🔒 Требует Python | ⚠️ Для знающих | -| **.exe файл** | ⭐⭐⭐ | ⚡⚡⚡⚡ | ✅ Не требует | ⭐ Для всех | - ---- - -## 🎯 Какой способ выбрать? - -### Для личного использования: -```bash -✅ Используйте: Votobu.vbs -``` -- Просто и работает из коробки -- Никаких лишних окон - -### Для удобства: -```bash -✅ Создайте ярлык: create_shortcut.bat -``` -- Запуск с рабочего стола -- Красивая иконка - -### Для распространения друзьям: -```bash -✅ Соберите .exe: build.bat -``` -- Не нужен Python -- Профессионально выглядит - ---- - -## ⚙️ Автозапуск при старте Windows - -### Вариант 1: Через папку автозагрузки - -```bash -# 1. Откройте папку автозагрузки -Win+R → shell:startup - -# 2. Создайте ярлык на Votobu.vbs -# (перетащите Votobu.vbs туда) -``` - -### Вариант 2: Через Task Scheduler - -```powershell -# PowerShell команда для автозапуска -$action = New-ScheduledTaskAction -Execute "pythonw.exe" -Argument "$PWD\src\main.py" -WorkingDirectory "$PWD" -$trigger = New-ScheduledTaskTrigger -AtLogOn -Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Votobu" -Description "Voice to Text" -``` - ---- - -## 🐛 Проблемы и решения - -### Консоль все равно мерцает на секунду - -**Причина:** Используется `python.exe` вместо `pythonw.exe` - -**Решение:** -```bash -# Используйте: -pythonw.exe src\main.py - -# Вместо: -python.exe src\main.py -``` - -### .vbs скрипт не запускается - -**Причина:** Windows блокирует .vbs файлы - -**Решение:** -1. ПКМ на Votobu.vbs → Свойства -2. Внизу: "Разблокировать" → ОК -3. Попробуйте снова - -### Ярлык не работает - -**Причина:** Неправильный путь - -**Решение:** -Пересоздайте ярлык: -```bash -create_shortcut.bat -``` - -### Хочу видеть логи, но без консоли - -**Решение:** Логи в файл - -Добавьте в `src/main.py`: -```python -import logging - -logging.basicConfig( - filename='votobu.log', - level=logging.DEBUG, - format='%(asctime)s - %(levelname)s - %(message)s' -) -``` - -Теперь логи будут в файле `votobu.log` - ---- - -## 📝 Быстрая справка - -### Я хочу... - -**...запустить без консоли прямо сейчас:** -```bash -Двойной клик: Votobu.vbs -``` - -**...ярлык на рабочем столе:** -```bash -create_shortcut.bat -``` - -**...автозапуск при входе в Windows:** -```bash -Win+R → shell:startup → перетащить Votobu.vbs -``` - -**...поделиться с другом:** -```bash -build.bat → отправить dist\Votobu.exe -``` - -**...видеть что происходит (отладка):** -```bash -run.bat (с консолью для отладки) -``` - ---- - -## ✨ Рекомендуемая настройка - -**Для ежедневного использования:** - -1. **Первый запуск:** - ```bash - install.bat # Установить всё - ``` - -2. **Создать ярлык:** - ```bash - create_shortcut.bat - ``` - -3. **Добавить в автозагрузку:** - - Win+R → `shell:startup` - - Скопировать туда созданный ярлык - -4. **Готово!** - - Votobu запускается при входе в Windows - - Никаких консолей - - Работает в фоне - - Иконка в трее - ---- - -## 🎊 Итог - -**Для быстрого старта без консоли:** - -```bash -# Вариант А: Простой -Двойной клик: Votobu.vbs - -# Вариант Б: Удобный -create_shortcut.bat → Ярлык на рабочем столе - -# Вариант В: Профессиональный -build.bat → Votobu.exe -``` - -**Все эти файлы уже созданы и готовы к использованию!** 🚀 - ---- - -
- -**Теперь Votobu работает полностью невидимо!** 👻 - -[⬅ Назад](README.md) | [📦 Упаковка](PACKAGING.md) | [🆘 Помощь](TROUBLESHOOTING.md) - -
- diff --git a/START_HERE.txt b/START_HERE.txt deleted file mode 100644 index fe814ce..0000000 --- a/START_HERE.txt +++ /dev/null @@ -1,209 +0,0 @@ -╔══════════════════════════════════════════════════════════════════╗ -║ ║ -║ 🎤 VOTOBU - VOICE TO TEXT 🎤 ║ -║ ║ -║ Добро пожаловать в Votobu v1.0.0! ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - -┌──────────────────────────────────────────────────────────────────┐ -│ ШАГ 1: УСТАНОВКА ЗАВИСИМОСТЕЙ │ -└──────────────────────────────────────────────────────────────────┘ - - Дважды кликните на файл: - - ▶ install.bat - - Или выполните вручную в командной строке: - - pip install -r requirements.txt - python create_icons.py - - -┌──────────────────────────────────────────────────────────────────┐ -│ ШАГ 2: ЗАПУСК ПРИЛОЖЕНИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - 🔹 С консолью (для отладки): - - ▶ run.bat - - 🔹 БЕЗ консоли (рекомендуется): - - ▶ Votobu.vbs 👈 Двойной клик! - - Или создайте ярлык на рабочем столе: - - ▶ create_shortcut.bat - - -┌──────────────────────────────────────────────────────────────────┐ -│ ШАГ 3: ИСПОЛЬЗОВАНИЕ │ -└──────────────────────────────────────────────────────────────────┘ - - 1. Найдите иконку микрофона в системном трее (справа внизу) - - 2. Зажмите клавишу F9 и говорите в микрофон - - 3. Отпустите F9 когда закончите - - 4. Подождите несколько секунд - - 5. Нажмите Ctrl+V чтобы вставить распознанный текст - - -┌──────────────────────────────────────────────────────────────────┐ -│ ПЕРВЫЙ ЗАПУСК │ -└──────────────────────────────────────────────────────────────────┘ - - При первом запуске: - - ✓ Появится иконка в трее - ✓ Загрузится модель Whisper (~150 MB, требует интернет) - ✓ Появится уведомление "Votobu запущен" - - Это займет 1-2 минуты. Последующие запуски мгновенны. - - -┌──────────────────────────────────────────────────────────────────┐ -│ НАСТРОЙКИ │ -└──────────────────────────────────────────────────────────────────┘ - - Кликните ПРАВОЙ кнопкой мыши на иконке в трее - → Выберите "Настройки" - - Можно изменить: - - Горячую клавишу (F9 → F8, F10, и т.д.) - - Язык (Русский / Английский / Авто) - - Модель AI (base рекомендуется) - - -┌──────────────────────────────────────────────────────────────────┐ -│ ДОКУМЕНТАЦИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - 📄 README.md - Обзор проекта - 📄 QUICKSTART.md - Быстрый старт - 📄 INSTALL.md - Подробная установка - 📄 TROUBLESHOOTING.md - 🔥 Решение проблем (ВАЖНО!) - 📄 USAGE.md - Полное руководство - 📄 PROJECT_STRUCTURE.md - Архитектура - 📄 FILES_LIST.txt - Список файлов - - -┌──────────────────────────────────────────────────────────────────┐ -│ ТЕСТИРОВАНИЕ │ -└──────────────────────────────────────────────────────────────────┘ - - Проверьте что все работает: - - python test_components.py - - Покажет какие компоненты установлены и работают. - - -┌──────────────────────────────────────────────────────────────────┐ -│ ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - 🔹 Диктовка письма: - [F9] "Здравствуйте, хотел обсудить проект" [Отпустить] - → Вставить в email через Ctrl+V - - 🔹 Быстрые заметки: - [F9] "Купить молоко и хлеб" [Отпустить] - → Вставить в блокнот - - 🔹 Комментарий в коде: - [F9] "функция для валидации email" [Отпустить] - → Вставить в редактор кода - - -┌──────────────────────────────────────────────────────────────────┐ -│ РЕШЕНИЕ ПРОБЛЕМ │ -└──────────────────────────────────────────────────────────────────┘ - - ❌ Qt platform plugin error? - → См. TROUBLESHOOTING.md - Решение №1 - - ❌ Не работает микрофон? - → Проверьте настройки Windows (Конфиденциальность → Микрофон) - - ❌ Плохо распознает? - → Говорите четче, уменьшите шум, попробуйте модель "small" - - ❌ Долго обрабатывает? - → Это нормально для первого раза. Попробуйте модель "tiny" - - ❌ Ошибка при запуске? - → Выполните: python test_components.py - → Читайте: TROUBLESHOOTING.md (полное руководство) - → Проверьте: INSTALL.md раздел "Решение проблем" - - -┌──────────────────────────────────────────────────────────────────┐ -│ СИСТЕМНЫЕ ТРЕБОВАНИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - ✓ Windows 10/11 - ✓ Python 3.8+ - ✓ 2+ GB RAM (4+ для больших моделей) - ✓ 500 MB свободного места - ✓ Микрофон - ✓ Интернет (только для первой загрузки модели) - - -┌──────────────────────────────────────────────────────────────────┐ -│ ГОРЯЧИЕ КЛАВИШИ │ -└──────────────────────────────────────────────────────────────────┘ - - F9 - Запись/остановка (по умолчанию) - Ctrl+V - Вставить распознанный текст - ПКМ на трее - Открыть меню - - -┌──────────────────────────────────────────────────────────────────┐ -│ ВЫХОД ИЗ ПРИЛОЖЕНИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - Кликните ПРАВОЙ кнопкой на иконке в трее - → Выберите "Выход" - - -┌──────────────────────────────────────────────────────────────────┐ -│ АВТОЗАПУСК ПРИ СТАРТЕ WINDOWS │ -└──────────────────────────────────────────────────────────────────┘ - - 1. Нажмите Win+R - 2. Введите: shell:startup - 3. Создайте ярлык на run.bat в открывшейся папке - - -┌──────────────────────────────────────────────────────────────────┐ -│ ЛИЦЕНЗИЯ │ -└──────────────────────────────────────────────────────────────────┘ - - MIT License - свободное использование и модификация - См. файл LICENSE для подробностей - - -┌──────────────────────────────────────────────────────────────────┐ -│ ПОДДЕРЖКА │ -└──────────────────────────────────────────────────────────────────┘ - - 📧 GitHub Issues: github.com/username/votobu/issues - 📖 Документация: README.md и другие .md файлы - 🧪 Тестирование: python test_components.py - - -╔══════════════════════════════════════════════════════════════════╗ -║ ║ -║ Приятного использования! 🎉 ║ -║ ║ -║ Votobu - голос в текст одной клавишей ║ -║ ║ -╚══════════════════════════════════════════════════════════════════╝ - - -P.S. Не забудьте прочитать QUICKSTART.md для быстрого старта! - diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md deleted file mode 100644 index cc037a6..0000000 --- a/TROUBLESHOOTING.md +++ /dev/null @@ -1,540 +0,0 @@ -# Решение проблем Votobu - -Руководство по устранению типичных проблем при установке и использовании. - ---- - -## 🔴 Ошибка: "Could not find the Qt platform plugin 'windows'" - -### Описание -``` -qt.qpa.plugin: Could not find the Qt platform plugin "windows" in "" -This application failed to start because no Qt platform plugin could be initialized. -``` - -### Причина -Некорректная установка PyQt5 или конфликт версий. - -### ✅ Решение - -**✅ ИСПРАВЛЕНО В КОДЕ!** - -Начиная с версии 1.0.1, это исправление уже включено в `src/main.py`. Просто переустановите PyQt5: - -```bash -# Полностью удалить PyQt5 -pip uninstall PyQt5 PyQt5-Qt5 PyQt5-sip -y - -# Установить стабильную версию -pip install PyQt5==5.15.9 PyQt5-sip PyQt5-Qt5 -``` - -Затем просто запустите приложение: -```bash -python src/main.py -``` - -**Что было исправлено:** - -В `src/main.py` добавлен автоматический поиск Qt плагинов: - -```python -# Исправление проблемы с Qt platform plugin на Windows -if sys.platform == 'win32': - import site - for site_dir in site.getsitepackages(): - qt_plugin_path = Path(site_dir) / 'PyQt5' / 'Qt5' / 'plugins' - if qt_plugin_path.exists(): - os.environ['QT_PLUGIN_PATH'] = str(qt_plugin_path) - break -``` - -**Альтернативные решения:** - -**Вариант 2: Установка через conda (если используете Anaconda)** - -```bash -conda install pyqt -``` - -**Вариант 3: Ручная установка плагинов** - -Скачайте PyQt5 заново через pip с --force-reinstall: -```bash -pip install --force-reinstall --no-cache-dir PyQt5==5.15.9 -``` - ---- - -## 🔴 Ошибка: ModuleNotFoundError - -### Описание -``` -ModuleNotFoundError: No module named 'PyQt5' -ModuleNotFoundError: No module named 'whisper' -``` - -### ✅ Решение - -```bash -# Убедитесь что используете правильную версию Python -python --version # Должна быть 3.8+ - -# Установите зависимости -pip install -r requirements.txt - -# Если не помогло, попробуйте: -python -m pip install -r requirements.txt -``` - ---- - -## 🔴 Микрофон не работает - -### Симптомы -- Нет записи при нажатии F9 -- Ошибка доступа к аудио устройству -- Пустой результат распознавания - -### ✅ Решение - -**Windows 10/11:** - -1. **Проверьте разрешения микрофона:** - - Настройки → Конфиденциальность → Микрофон - - Включите "Разрешить приложениям доступ к микрофону" - - Включите "Разрешить классическим приложениям доступ к микрофону" - -2. **Проверьте устройство по умолчанию:** - - ПКМ на иконке звука → Звуки → Запись - - Убедитесь что ваш микрофон установлен по умолчанию - -3. **Проверьте драйверы:** - - Диспетчер устройств → Аудиовходы и аудиовыходы - - Обновите драйверы микрофона - -4. **Тест микрофона в Python:** - ```python - import sounddevice as sd - print(sd.query_devices()) # Покажет доступные устройства - ``` - ---- - -## 🔴 Ошибка: "Не удается найти указанный файл" при распознавании - -### Описание -``` -Ошибка распознавания: [WinError 2] Не удается найти указанный файл -``` - -### Причина -Whisper требует **ffmpeg** для обработки аудио файлов. - -### ✅ Решение - -**✅ ИСПРАВЛЕНО В КОДЕ!** - -Начиная с версии 1.0.2, ffmpeg автоматически устанавливается и настраивается. Просто переустановите зависимости: - -```bash -pip install -r requirements.txt -``` - -**Если проблема сохраняется:** - -```bash -# Установить ffmpeg вручную -pip install imageio-ffmpeg ffmpeg-python - -# Проверить установку -python -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" -``` - -**Альтернатива - установка ffmpeg глобально:** - -1. Скачайте ffmpeg: https://www.gyan.dev/ffmpeg/builds/ -2. Распакуйте в `C:\ffmpeg` -3. Добавьте в PATH: `C:\ffmpeg\bin` -4. Перезапустите терминал - ---- - -## 🔴 Модель Whisper не загружается - -### Симптомы -- Ошибка при первом запуске -- "Failed to load model" -- Долгая загрузка без результата - -### ✅ Решение - -**1. Проверьте интернет-соединение** - -Первая загрузка требует интернет для скачивания модели (~150-3000 MB). - -**2. Проверьте свободное место** - -```bash -# Модели хранятся в: -# Windows: C:\Users\\.cache\whisper -# Linux/Mac: ~/.cache/whisper - -# Требуется места: -# tiny: ~75 MB -# base: ~150 MB -# small: ~500 MB -# medium: ~1.5 GB -# large: ~3 GB -``` - -**3. Ручная загрузка модели** - -```python -import whisper -model = whisper.load_model("base") # Загрузит модель вручную -``` - -**4. Попробуйте меньшую модель** - -В настройках выберите `tiny` вместо `base`. - ---- - -## 🔴 Плохое качество распознавания - -### Симптомы -- Неправильный текст -- Пропущенные слова -- Странные фразы - -### ✅ Решение - -**1. Улучшите качество записи:** -- Говорите медленнее и четче -- Уменьшите фоновый шум -- Подвиньте микрофон ближе (15-30 см) -- Избегайте эха (закройте окна, используйте мягкую мебель) - -**2. Настройте приложение:** -- Выберите конкретный язык (не "Авто") -- Используйте модель `small` или `medium` -- Записывайте короткими фразами (5-15 секунд) - -**3. Проверьте микрофон:** -- Используйте качественный USB-микрофон -- Избегайте дешевых встроенных микрофонов -- Проверьте уровень записи (не слишком тихо/громко) - ---- - -## 🔴 Долгая обработка - -### Симптомы -- Распознавание занимает >1 минуты -- Приложение зависает -- Высокая загрузка CPU - -### ✅ Решение - -**1. Используйте меньшую модель:** - -| Модель | Скорость | Качество | -|--------|----------|----------| -| tiny | ⚡⚡⚡⚡⚡ | ⭐⭐ | -| base | ⚡⚡⚡⚡ | ⭐⭐⭐ | -| small | ⚡⚡⚡ | ⭐⭐⭐⭐ | - -**2. Сократите длину записи:** -- Идеально: 5-15 секунд -- Максимум: 30 секунд -- Длинные записи разбивайте на части - -**3. GPU ускорение (для продвинутых):** - -```bash -pip install openai-whisper-cpp # Более быстрая версия -``` - ---- - -## 🔴 Окно настроек не открывается - -### Симптомы -- Клик на "Настройки" в трее ничего не делает -- Окно не появляется - -### ✅ Решение - -**1. Проверьте логи в консоли:** - -Запустите через `run.bat` (с консолью) и кликните "Настройки": -```bash -run.bat -# Кликните ПКМ на иконке → Настройки -# Смотрите что выводится в консоли -``` - -**2. Тест окна настроек отдельно:** - -```bash -python test_settings.py -``` - -Если окно открывается - проблема в интеграции с main.py - -**3. Окно за пределами экрана:** - -Исправлено в v1.0.2+ - окно принудительно позиционируется в (100, 100) - -**4. Перезапустите приложение:** - -```bash -# Закрыть -ПКМ на иконке → Выход - -# Запустить снова -run.bat -``` - -**5. Переустановите PyQt5:** - -```bash -pip uninstall PyQt5 PyQt5-Qt5 PyQt5-sip -y -pip install PyQt5==5.15.9 -``` - ---- - -## 🔴 Горячая клавиша не работает - -### Симптомы -- F9 не реагирует -- Запись не начинается - -### ✅ Решение - -**1. Проверьте права администратора:** - -Некоторые приложения требуют прав администратора для глобальных hotkeys: -- ПКМ на run.bat → Запуск от имени администратора - -**2. Смените клавишу:** -- ПКМ на иконке → Настройки → Изменить клавишу -- Попробуйте F8, F10, F11, F12 - -**3. Проверьте конфликты:** - -F9 может использоваться другими приложениями: -- Закройте игры, IDE, другие утилиты -- Выберите редко используемую клавишу - -**4. Проверьте работу pynput:** - -```python -from pynput import keyboard - -def on_press(key): - print(f"Нажата: {key}") - -listener = keyboard.Listener(on_press=on_press) -listener.start() -listener.join() -``` - ---- - -## 🔴 Ошибка: "Access denied" или "Permission denied" - -### ✅ Решение - -**1. Закройте другие приложения:** -- Закройте другие программы, использующие микрофон (Skype, Discord, Zoom) - -**2. Запустите от администратора:** -```bash -# ПКМ на run.bat → Запуск от имени администратора -``` - -**3. Проверьте антивирус:** -- Добавьте Votobu в исключения антивируса -- Временно отключите антивирус для теста - ---- - -## 🔴 Буфер обмена не работает - -### Симптомы -- Текст не копируется -- Ctrl+V вставляет старый текст - -### ✅ Решение - -**1. Проверьте работу pyperclip:** - -```python -import pyperclip -pyperclip.copy("Тест") -print(pyperclip.paste()) # Должно вывести "Тест" -``` - -**2. Установите дополнительные зависимости (Linux):** - -```bash -sudo apt-get install xclip xsel # Для Linux -``` - -**3. Проверьте менеджеры буфера обмена:** -- Отключите сторонние менеджеры буфера обмена -- Они могут конфликтовать с pyperclip - ---- - -## 🔴 Приложение не закрывается - -### ✅ Решение - -**1. Используйте меню трея:** -- ПКМ на иконке → Выход - -**2. Через диспетчер задач:** -- Ctrl+Shift+Esc -- Найдите "python.exe" → Снять задачу - -**3. Через командную строку:** -```bash -taskkill /F /IM python.exe -``` - ---- - -## 🔴 Ошибка кодировки в консоли - -### Симптомы -``` -UnicodeEncodeError: 'charmap' codec can't encode character -``` - -### ✅ Решение - -Уже исправлено в `test_components.py`. Для других скриптов добавьте: - -```python -import sys -import io - -if sys.platform == 'win32': - sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') -``` - ---- - -## 🛠️ Диагностика - -### Проверьте установку - -```bash -python test_components.py -``` - -Покажет какие компоненты работают, а какие требуют внимания. - -### Проверьте версии - -```bash -python --version # >= 3.8 -pip show PyQt5 # 5.15.9 -pip show openai-whisper # latest -``` - -### Проверьте логи - -Запустите приложение через командную строку: -```bash -python src/main.py -``` - -Все ошибки будут выведены в консоль. - ---- - -## 📞 Получить помощь - -Если проблема не решена: - -1. **Запустите диагностику:** - ```bash - python test_components.py - ``` - -2. **Соберите информацию:** - - Версия Python: `python --version` - - Версия Windows: `winver` - - Текст ошибки из консоли - - Установленные версии: `pip list` - -3. **Создайте Issue:** - - GitHub Issues: добавьте всю информацию выше - - Опишите шаги для воспроизведения - ---- - -## 💡 Полезные команды - -```bash -# Проверка зависимостей -pip list - -# Обновление всех зависимостей -pip install -r requirements.txt --upgrade - -# Очистка кэша pip -pip cache purge - -# Переустановка с нуля -pip uninstall -r requirements.txt -y -pip install -r requirements.txt - -# Проверка микрофона -python -c "import sounddevice as sd; print(sd.query_devices())" - -# Тест Whisper -python -c "import whisper; m = whisper.load_model('base'); print('OK')" -``` - ---- - -## 🔄 Переустановка с нуля - -Если ничего не помогает: - -```bash -# 1. Удалить все зависимости -pip uninstall -r requirements.txt -y - -# 2. Очистить кэш -pip cache purge - -# 3. Удалить модели Whisper -# Windows: del C:\Users\\.cache\whisper /s /q -# Linux/Mac: rm -rf ~/.cache/whisper - -# 4. Установить заново -pip install -r requirements.txt - -# 5. Проверить -python test_components.py - -# 6. Запустить -python src/main.py -``` - ---- - -
- -**Не нашли решение?** -Создайте Issue на GitHub с подробным описанием проблемы - -
- diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index a160e59..0000000 --- a/USAGE.md +++ /dev/null @@ -1,294 +0,0 @@ -# Руководство по использованию Votobu - -## Оглавление -- [Быстрый старт](#быстрый-старт) -- [Подробное описание](#подробное-описание) -- [Настройки](#настройки) -- [Советы по использованию](#советы-по-использованию) -- [Примеры использования](#примеры-использования) - -## Быстрый старт - -1. Запустите `run.bat` или `python src/main.py` -2. Зажмите F9 и говорите в микрофон -3. Отпустите F9 -4. Вставьте текст через Ctrl+V - -## Подробное описание - -### Жизненный цикл записи - -``` -[Зажать F9] → [Говорите] → [Отпустить F9] → [Распознавание] → [Текст в буфере] → [Ctrl+V] -``` - -### Индикация состояния - -**Иконка в трее показывает текущее состояние:** - -- 🔵 **Обычная иконка** - Готов к записи -- 🔴 **Красная иконка** - Идет запись -- 🤖 **Текст "Распознавание..."** - Обработка аудио - -**Уведомления:** - -- "Votobu запущен" - При старте приложения -- "Текст распознан" - Текст скопирован в буфер -- "Ошибка" - Не удалось распознать речь - -## Настройки - -### Как открыть настройки - -1. Найдите иконку Votobu в трее (справа внизу) -2. Кликните правой кнопкой мыши -3. Выберите "Настройки" - -### Изменение горячей клавиши - -**По умолчанию:** F9 - -**Как изменить:** -1. Откройте настройки -2. Нажмите "Изменить клавишу" -3. Нажмите желаемую клавишу -4. Нажмите "Сохранить" - -**Поддерживаемые клавиши:** -- Функциональные: F1-F12 -- Буквы: A-Z -- Цифры: 0-9 -- Специальные: Space, Enter, Tab, Esc - -### Выбор языка - -**Опции:** -- **Русский** - Оптимизация для русского языка -- **Английский** - Оптимизация для английского языка -- **Автоопределение** - Автоматическое определение языка - -**Рекомендация:** Выбирайте конкретный язык для лучшего качества и скорости - -### Выбор модели Whisper - -| Модель | Размер | Скорость | Качество | Память | -|--------|--------|----------|----------|--------| -| tiny | ~75 MB | Очень быстро | Базовое | ~1 GB | -| base | ~150 MB | Быстро | Хорошее | ~1 GB | -| small | ~500 MB | Средне | Отличное | ~2 GB | -| medium | ~1.5 GB | Медленно | Очень хорошее | ~5 GB | -| large | ~3 GB | Очень медленно | Лучшее | ~10 GB | - -**По умолчанию:** base (рекомендуется) - -## Советы по использованию - -### Для лучшего качества распознавания - -1. **Говорите четко и не спеша** - - Делайте паузы между предложениями - - Избегайте очень быстрой речи - -2. **Используйте качественный микрофон** - - Расположите микрофон на расстоянии 15-30 см от рта - - Избегайте дешевых встроенных микрофонов - -3. **Минимизируйте шум** - - Закройте окна, двери - - Выключите вентиляторы, кондиционеры - - Избегайте эха (мягкая мебель поглощает звук) - -4. **Оптимальная длина записи** - - Короткие фразы: 5-10 секунд - - Длинные тексты: до 30 секунд - - Очень длинные записи (>1 минуты) могут распознаваться медленнее - -5. **Выбор правильной модели** - - Для заметок и черновиков: base - - Для важных документов: small или medium - - Для технического текста: medium или large - -### Горячие клавиши - -**Рекомендуемые клавиши:** -- F9 (по умолчанию) - удобна, редко используется -- F8 - альтернатива -- F10 - может конфликтовать с меню в некоторых программах - -**Не рекомендуется:** -- F1 - часто открывает справку -- F5 - обновление страницы в браузерах -- Буквы/цифры - могут конфликтовать при наборе текста - -## Примеры использования - -### Диктовка текста в Word/Google Docs - -1. Откройте документ -2. Установите курсор в нужное место -3. Зажмите F9: "Здравствуйте! Меня зовут Иван. Я хотел бы обсудить..." -4. Отпустите F9 -5. Дождитесь уведомления -6. Нажмите Ctrl+V - -### Быстрые заметки - -``` -[Зажать F9] → "Купить молоко, хлеб и яйца" → [Отпустить F9] → [Ctrl+V в заметки] -``` - -### Перевод устной речи в email - -1. Откройте почтовый клиент -2. Создайте новое письмо -3. Зажмите F9 и продиктуйте текст письма -4. Отпустите F9 -5. Вставьте текст через Ctrl+V -6. Отредактируйте при необходимости - -### Транскрипция встреч - -1. Зажимайте F9 когда кто-то говорит -2. Отпускайте при паузах -3. Вставляйте текст в документ -4. Повторяйте для следующих фраз - -### Командная строка - -``` -[Зажать F9] → "git commit minus m add new feature" → [Отпустить F9] → [Ctrl+V] -# Результат: git commit -m add new feature -``` - -### Многоязычная диктовка - -**Режим автоопределения:** -``` -[Зажать F9] → "Hello, this is a test" → [Отпустить F9] -[Зажать F9] → "Привет, это тест" → [Отпустить F9] -``` - -## Рабочий процесс - -### Для писателей - -1. Набросайте структуру текста вручную -2. Продиктуйте содержание каждого раздела -3. Отредактируйте текст вручную -4. Повторяйте для следующих разделов - -### Для программистов - -1. Комментарии к коду: - ``` - [F9] → "функция для обработки пользовательского ввода" → [Ctrl+V] - ``` - -2. Документация: - ``` - [F9] → "Этот метод принимает строку и возвращает массив" → [Ctrl+V] - ``` - -3. Commit messages: - ``` - [F9] → "исправлена ошибка с обработкой пустых значений" → [Ctrl+V] - ``` - -### Для студентов - -1. Конспекты лекций: - - Записывайте основные моменты голосом - - Редактируйте позже - -2. Эссе и рефераты: - - Продиктуйте черновик - - Отшлифуйте формулировки вручную - -3. Переводы: - - Слушайте аудио на иностранном языке - - Диктуйте перевод на русском - -## Производительность - -### Время распознавания (примерно) - -**Модель base на среднем ПК:** -- 5 секунд аудио → ~3-5 секунд распознавания -- 10 секунд аудио → ~5-10 секунд распознавания -- 30 секунд аудио → ~15-30 секунд распознавания - -**Факторы, влияющие на скорость:** -- Мощность процессора (CPU) -- Наличие GPU (значительно ускоряет) -- Выбранная модель -- Качество аудио - -### Оптимизация - -**Для максимальной скорости:** -- Модель: tiny или base -- Язык: конкретный (не авто) -- Длина: 5-15 секунд - -**Для максимального качества:** -- Модель: medium или large -- Язык: конкретный -- Качественный микрофон -- Тихая обстановка - -## Дополнительные возможности - -### Работа в фоне - -Votobu всегда работает в фоне. Минимизируйте все окна - приложение останется в трее и будет реагировать на горячие клавиши. - -### Автозапуск (Windows) - -1. Нажмите Win+R -2. Введите: `shell:startup` -3. Создайте ярлык на `run.bat` в этой папке - -### Использование с другими программами - -**Совместимость:** -- ✅ Microsoft Word, Excel, PowerPoint -- ✅ Google Docs, Sheets, Slides -- ✅ Notepad, Notepad++, VS Code -- ✅ Telegram, WhatsApp, Discord -- ✅ Email клиенты (Outlook, Thunderbird) -- ✅ Любые приложения с текстовыми полями - -## Ограничения - -1. **Whisper не обучен на:** - - Очень специфической терминологии (может ошибаться) - - Редких именах и названиях - - Сильных акцентах и диалектах - -2. **Технические ограничения:** - - Требуется подключенный микрофон - - Распознавание происходит локально (нужен CPU) - - Первая загрузка модели требует интернета - -3. **Не заменяет:** - - Профессиональную транскрибацию - - Стенографирование в реальном времени - - Перевод между языками - -## FAQ - -**Q: Можно ли использовать без интернета?** -A: Да, после первой загрузки модели интернет не нужен. - -**Q: Сохраняются ли мои аудиозаписи?** -A: Нет, временные файлы автоматически удаляются. - -**Q: Можно ли использовать несколько языков одновременно?** -A: Да, в режиме "Автоопределение", но это медленнее. - -**Q: Работает ли на Mac/Linux?** -A: Частично. Требуется адаптация путей и возможны проблемы с pynput. - -**Q: Как часто можно использовать?** -A: Без ограничений. Все работает локально. - diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index 5348568..0000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Development dependencies for building Votobu - -# Include all runtime dependencies --r requirements.txt - -# Build tools -pyinstaller==6.3.0 - -# Testing -pytest==7.4.3 -pytest-cov==4.1.0 - -# Code quality -black==23.12.1 -flake8==7.0.0 -mypy==1.8.0 - -# Documentation -sphinx==7.2.6 - diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 7d81b65..0000000 --- a/requirements.txt +++ /dev/null @@ -1,11 +0,0 @@ -PyQt5==5.15.9 -openai-whisper==20230918 -sounddevice==0.4.6 -soundfile==0.12.1 -pynput==1.7.6 -pyperclip==1.8.2 -numpy==1.24.3 -Pillow==10.0.0 -imageio-ffmpeg==0.6.0 -ffmpeg-python==0.2.0 -