AutoHotkey GUI для OpenAI Whisper: простое приложение для транскрипции

Введение

OpenAI Whisper — надёжный инструмент для преобразования речи в текст. Но запуск команды в терминале каждый раз раздражает. AutoHotkey позволяет быстро сделать простую графическую оболочку (GUI) для командной утилиты: кнопки, выпадающие списки и поля для подсказки вместо набора аргументов вручную.

В этой инструкции мы создадим минималистичное приложение, которое превратит Whisper в «приложение в один клик» на Windows. Понадобятся установленные AutoHotkey (v1) и Whisper (локально или в окружении, где доступна команда whisper).

Важно: использовать нужно версию AutoHotkey v1, синтаксис v2 отличается.

Что понадобится

• Windows 10/11.
• AutoHotkey v1 (скачайте с официального сайта и установите).
• Установленный whisper (pip package или другой способ установки) и рабочая команда whisper в CMD/PowerShell.
• Базовые навыки редактирования текстовых файлов и работы с проводником.

Общий план

1. Создать папку проекта и новый .ahk файл.
2. Описать переменные конфигурации и скрытые значения (исполняемый файл, формат вывода).
3. Добавить элементы GUI: выпадающие списки для языка, модели и задачи; поле для подсказки; кнопки.
4. Написать функции: выбор файла, выбор папки, сбор флагов и запуск команды.
5. Отладить, удалить вспомогательные сообщения и использовать.

Быстрое напоминание о флагах Whisper

Whisper принимает флаги, которые удобно связать с элементами GUI. Основные флаги, используемые в проекте:

• –initial_prompt PROMPT_TEXT — текст-подсказка для улучшения распознавания.
• –output_format txt — формат вывода (txt, srt и т.д.).
• -o OUTPUT_FOLDER — папка вывода.
• –model MODEL — tiny, base, small, medium, large.
• –task transcribe|translate — транскрибировать или переводить.
• –language <код> — код языка (например, en, el).

Добавьте список флагов в виде комментариев в начало скрипта для удобства.

; Whisper Flags:
; --initial_prompt PROMPT_TEXT
; --output_format txt
; -o OUTPUT_FOLDER
; --model MODEL_TO_USE
; --task TRANSCRIBE/TRANSLATE
; --language EN/EL

Полный пример AutoHotkey (v1) скрипта

Ниже — готовый рабочий пример скрипта. Скопируйте в файл с расширением .ahk и при необходимости измените переменные WhisperExecutable и OutputFormat.

; AutoHotkey v1 скрипт: GUI для OpenAI Whisper
; Сохраните файл как whisper_gui.ahk и запустите двойным кликом

; -------------------------
; Конфигурация (скрытые переменные)
; -------------------------
OutputFormat := "txt"                       ; формат вывода
WhisperExecutable := "whisper"               ; команда/исполняемый файл Whisper в PATH
; По необходимости укажите полный путь, например: C:\Python\Scripts\whisper.exe

; Пример предустановленной подсказки (можно оставить пустой)
PromptText := "Транскрипция заметок"       ; значение по умолчанию для поля подсказки

; -------------------------
; GUI: элементы интерфейса
; -------------------------
Gui, Font, s10, Segoe UI
Gui, Add, Text, x5 y3 w500 h20, Настройки Whisper
; Выпадающие списки
Gui, Add, Text, x5 y30 w150, Язык аудио
Gui, Add, DropDownList, x160 y28 w200 vSelectedLanguage, en|el
GuiControl,, SelectedLanguage, en

Gui, Add, Text, x5 y60 w150, Модель
Gui, Add, DropDownList, x160 y58 w200 vSelectedModel, tiny|base|small|medium|large
GuiControl,, SelectedModel, small

Gui, Add, Text, x5 y90 w150, Задача
Gui, Add, DropDownList, x160 y88 w200 vTaskType, transcribe|translate
GuiControl,, TaskType, transcribe

Gui, Add, Text, x5 y125 w500, Подсказка для Whisper (initial prompt)
Gui, Add, Edit, x5 y145 w460 h120 vPromptText, %PromptText%

; Кнопки действий
Gui, Add, Button, x5 y275 w230 h30 gSelectFile, Load File
Gui, Add, Button, x235 y275 w230 h30 gSelectFolder, Choose Output Folder
Gui, Add, Button, Default x5 y315 w460 h35 gButtonSubmit, OK

; Поля для отображения выбранных путей (не редактируемые)
Gui, Add, Text, x5 y360 w80, Исходный файл:
Gui, Add, Edit, x90 y356 w375 h20 vSelectedFile ReadOnly
Gui, Add, Text, x5 y385 w80, Папка вывода:
Gui, Add, Edit, x90 y381 w375 h20 vSelectedFolder ReadOnly

Gui, Show, w480 h430, Whisper GUI
Return

; -------------------------
; Функции
; -------------------------
SelectFile:
    FileSelectFile, SelectedFile, 3, , Выберите аудиофайл, Аудио файлы (*.mp3; *.wav; *.m4a; *.flac)
    if (ErrorLevel)
    {
        MsgBox, 48, Загрузка файла, Файл не выбран.
        Return
    }
    GuiControl,, SelectedFile, %SelectedFile%
    MsgBox, 64, Файл выбран, %SelectedFile%
Return

SelectFolder:
    FileSelectFolder, SelectedFolder, , 3, Выберите папку для результатов
    if (ErrorLevel)
    {
        MsgBox, 48, Папка не выбрана, Операция отменена.
        Return
    }
    GuiControl,, SelectedFolder, %SelectedFolder%
    MsgBox, 64, Папка вывода, %SelectedFolder%
Return

ButtonSubmit:
    Gui, Submit, NoHide

    ; Проверки перед запуском
    if (SelectedFile = "")
    {
        MsgBox, 48, Ошибка, Пожалуйста, выберите аудиофайл.
        Return
    }
    if (SelectedFolder = "")
    {
        MsgBox, 48, Ошибка, Пожалуйста, выберите папку вывода.
        Return
    }

    ; Собираем флаги
    WhisperFlags := "--initial_prompt " . Chr(34) . PromptText . Chr(34)
    WhisperFlags .= " --task " . TaskType
    WhisperFlags .= " --model " . SelectedModel
    WhisperFlags .= " --language " . SelectedLanguage
    WhisperFlags .= " --output_format " . OutputFormat
    ; -o и путь файла с кавычками
    WhisperFlags .= " -o " . Chr(34) . SelectedFolder . Chr(34) . " " . Chr(34) . SelectedFile . Chr(34)

    ; Копируем команду в буфер для удобства отладки
    FullCmd := WhisperExecutable . " " . WhisperFlags
    Clipboard := FullCmd

    ; Показать команду для быстрого контроля (можно закомментировать после отладки)
    MsgBox, 64, Выполнение, Команда скопирована в буфер и будет выполнена сейчас.`n`n%FullCmd%

    ; Запуск в командной строке и ожидание завершения
    RunWait, %comspec% /c %FullCmd%, , Hide

    MsgBox, 64, Готово, Транскрипция завершена. Проверьте папку вывода.
Return

GuiClose:
GuiEscape:
    ExitApp

Пояснения к скрипту:

• Все переменные по умолчанию и флаги заданы в блоке конфигурации.
• FileSelectFile отображает диалог выбора файла; FileSelectFolder — диалог выбора папки.
• Gui, Submit собирает значения из элементов GUI.
• RunWait запускает команду в CMD и ждёт завершения.
• Clipboard заполняется для удобства отладки; удалите или закомментируйте после успешной проверки.

Разбор частей GUI и параметры

Выпадающие списки

DropDownList в AutoHotkey хранит выбранное значение в переменных SelectedLanguage, SelectedModel и TaskType. Мы задаём значения в формате, который удобно передавать в Whisper (коды языков, названия моделей и тип задачи).

Поле подсказки (initial prompt)

Поле PromptText позволяет дать Whisper контекст. Например, если аудио содержит имена, бренды или специфические термины, перечислите их здесь, чтобы повысить точность распознавания. Не передавайте чувствительные данные, если не уверены в локальной установке.

Кнопки

• Load File вызывает SelectFile — выбирает входной аудиофайл.
• Choose Output Folder вызывает SelectFolder — выбирает папку для результатов.
• OK (по умолчанию) запускает ButtonSubmit — собирает флаги и выполняет команду.

Отладка и полезные приёмы

• Оставьте MsgBox и копирование команды в Clipboard на этапе тестирования. Это поможет скопировать команду в окно CMD и посмотреть точные ошибки.
• Частая ошибка: не заключить –initial_prompt в кавычки. Тогда Whisper попытается разобрать её как отдельные флаги.
• Если команда не найдена, укажите полный путь к whistle-исполняемому файлу в WhisperExecutable.
• Для больших моделей (medium/large) убедитесь, что в системе достаточно оперативной памяти и, при необходимости, GPU/видеодрайверы поддерживаются.

Когда решение может терпеть неудачу

• Большие модели слишком медленные или потребляют слишком много ресурсов на слабых машинах.
• Whisper не всегда идеально работает с шумными записями, пересечённой речью или сильными акцентами.
• Файлы в нестандартных контейнерах или с кодеком, не поддерживаемым ffmpeg/whisper, не откроются.

В таких случаях:

• Предобработайте аудиофайл: нормализация громкости, удаление шума, сегментация длинных записей.
• Попробуйте более лёгкую модель (tiny/base) для быстрой проверки.
• Примените специализированные инструменты шумоподавления перед распознаванием.

Альтернативные подходы

• PowerShell GUI: если вы предпочитаете PowerShell, можно собрать окно с помощью Windows Forms или WPF.
• Electron/Node: полноценное кроссплатформенное приложение с более гибким UI и обновлениями.
• Обёртки на Python (tkinter, PySimpleGUI): удобно, если вы уже работаете с Python-окружением и хотите интегрировать доп. логику.

Руководство по тестированию и критерии приёмки

Критерии приёмки

1. GUI корректно отображается и элементы активны.
2. После выбора файла и папки поля пути показывают корректные значения.
3. При нажатии OK команда формируется корректно и копируется в буфер обмена.
4. RunWait запускает Whisper и по завершении файл с расширением .txt (или выбранным форматом) появляется в папке вывода.
5. Если команда вызывает ошибку, текст ошибки доступен в CMD при вставке из буфера.

Тестовые случаи

• Выбор файла с пробелами в имени — должен корректно обрабатываться (путь заключён в кавычки).
• Отмена выбора файла/папки — GUI не падает и корректно уведомляет.
• Неверный путь к WhisperExecutable — ожидаемая ошибка “команда не найдена” в CMD.

Шаблоны и полезные сниппеты

1. Формирование безопасной команды с кавычками:

WhisperFlags := "--initial_prompt " . Chr(34) . PromptText . Chr(34) . " ..."
FullCmd := WhisperExecutable . " " . WhisperFlags

2. Быстрая проверка доступности команды:

RunWait, %comspec% /c where %WhisperExecutable%, , Hide
if ErrorLevel
    MsgBox, 48, Предупреждение, Команда %WhisperExecutable% не найдена в PATH

3. Удаление временных сообщений после отладки: закомментируйте MsgBox и присваивание Clipboard.

Рекомендации по производительности

• Для итеративной работы используйте модель small или base: они дают хороший компромисс между скоростью и качеством.
• Для офлайн-обработки больших архивов используйте medium/large на машине с GPU.
• Разбивайте длинные записи на части:читать длинные файлы может быть медленнее и рискованнее по памяти.

Ментальные модели и эвристики

• Правило 3 кликов: минимизируйте количество действий до трёх — выбор файла, выбор папки, запуск. Это уменьшает ошибки пользователя.
• Компонентность: храните настройки (WhisperExecutable, OutputFormat) в начале скрипта — быстрая замена при миграции.
• Отдельный режим отладки: включайте подробные сообщения и копирование команды лишь на время разработки.

Роли и чек‑листы

Для пользователя (непрограммист):

• Убедиться, что whisper доступен в CMD.
• Выбрать аудиофайл.
• Нажать OK.

Для разработчика/администратора:

• Проверить PATH и права доступа к папке вывода.
• Обновить переменную WhisperExecutable при необходимости.
• Подключить логирование ошибок при массовой обработке.

Playbook для инцидента: команда не запускается

1. Скопировать команду из буфера обмена.
2. Открыть CMD вручную и вставить команду.
3. Проанализировать сообщение об ошибке: не найдено исполняемое, ошибка формата, неправильно указаны кавычки.
4. Если проблема с моделью — попробовать более лёгкую.
5. Проверить доступ к ffmpeg (если whisper использует ffmpeg для декодирования).

Матрица рисков и смягчения

• Риск: большой расход памяти на large.
  • Смягчение: использовать small/medium либо GPU-решение.
• Риск: раскрытие приватного аудио в удалённой службе.
  • Смягчение: использовать локальную установку Whisper, не загружать файлы в облако.
• Риск: неверные результаты из-за шума.
  • Смягчение: предобработка аудио, указание подсказки.

Совместимость и миграция

• AutoHotkey v1 ≠ v2: этот скрипт написан для v1. Для миграции на v2 придётся переписать синтаксис функций и GUI.
• Whisper: API/CLI могут меняться. Следите за релизами и за тем, какие флаги поддерживаются.

Приватность и соответствие требованиям (GDPR)

• Если аудио содержит персональные данные, убедитесь, что обработка происходит локально и файлы не отправляются на сторонние сервисы.
• Не храните транскрипты в публичных папках. При необходимости добавьте функционал шифрования или автоматического удаления.

Частые ошибки и их решение

• “Команда не найдена” — укажите полный путь к исполняемому WhisperExecutable.
• Неправильный формат вывода — измените OutputFormat на поддерживаемый формат (txt, srt).
• Ошибка парсинга initial_prompt — убедитесь, что подсказка заключена в кавычки.

Планы развития и идеи для улучшения

• Добавить логирование в файл с временной меткой.
• Поддержка пакетной обработки нескольких файлов и очередь задач.
• Интеграция с редактором текста: автоматическое открытие результата в блокноте.
• Поддержка горячих клавиш для быстрого запуска.

Сводка и рекомендуемые действия

• Начните с базового скрипта и отладьте команды, копируя их в буфер и выполняя вручную в CMD.
• После подтверждения контроля над командой закомментируйте MsgBox и операции с буфером обмена.
• Для частой работы настройте формат вывода и модель по умолчанию, оптимизировав под ваши задачи.

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

Краткое резюме

• AutoHotkey позволяет без усилий дать GUI командной утилите Whisper.
• Небольшой скрипт экономит время и снижает количество ошибок при вводе аргументов.
• Встроенные подсказки, копирование команды в буфер и MsgBox ускоряют отладку.

Ключевые термины

• Whisper — CLI-инструмент для распознавания речи.
• AutoHotkey (AHK) — скриптовый язык автоматизации для Windows.
• initial_prompt — флаг Whisper для передачи контекста.

Важно: помните про права на аудио и приватность данных. После успешной проверки удалите отладочные сообщения из скрипта.