GUI для OpenAI Whisper на AutoHotkey

Почему это удобно

Whisper — мощный инструмент для преобразования речи в текст, но чаще всего его запускают из командной строки. Для многих пользователей это неудобно.
AutoHotkey позволяет быстро сделать простую графическую оболочку (GUI) для командных приложений: достаточно нескольких элементов интерфейса и функций.
В результате вы получаете «трёхкликовое» приложение: выбрать файл → выбрать папку → нажать OK.

В этом руководстве вы найдёте полную инструкцию, образцы кода, чек-листы для ролей (пользователь, разработчик), сценарии тестирования и раздел с типичными проблемами и решениями.

USB микрофон на столе

Что потребуется

Установленный AutoHotkey версии v1 (не v2). Скачайте с официального сайта и запустите установщик.
Установленный Whisper (локально) или доступ к исполняемому файлу/команде whisper в PATH.
Базовые навыки работы с файловой системой Windows и текстовым редактором.

Важно: этот материал предполагает локальную установку Whisper (командный интерфейс). Если вы используете облачный API (например, OpenAI Whisper API), добавьте шаги для работы с сетью, токенами и отправкой файлов на сервер — в разделе «Альтернативные подходы» ниже есть подсказки.

Краткий план действий

Создать папку проекта и новый AHK скрипт.
Определить «скрытые» переменные (исполняемый файл Whisper, формат вывода и пр.).
Построить GUI: списки (DropDown), поле Prompt, кнопки.
Реализовать функции: выбор файла, выбор папки, сбор флагов и запуск команды.
Протестировать, отладить, удалить отладочные сообщения.

Структура проекта и лучшие практики

Держите скрипт в отдельной папке. Так же удобно сохранять логи и временные файлы рядом.
Закомментируйте каждую секцию; используйте метки (Label) для функций.
В начале скрипта определите все значения, которые можно менять — это упростит последующую настройку.

Создание папки проекта

Создание нового AutoHotkey скрипта (коротко)

Откройте Проводник (Win+E). Создайте папку для приложения.
Правый клик → New → AutoHotkey Script. Назовите, например, WhisperGUI.ahk.
Shift+Right Click → Open with → ваш редактор (Notepad, VS Code и т. п.).
Оставьте автоматически добавленные строки, добавьте код ниже.

Новый скрипт AutoHotkey

Быстрый обзор флагов Whisper (для справки)

Добавьте комментарии со списком флагов в начало скрипта, чтобы быстро ориентироваться:

; Флаги Whisper:
; --initial_prompt TEXT   — начальная подсказка (guiding prompt)
; --output_format txt|srt — формат вывода (txt, srt и т.д.)
; -o OUTPUT_FOLDER        — папка вывода
; --model MODEL           — модель: tiny, base, small, medium, large
; --task transcribe|translate
; --language en|el|...    — язык входного аудио

Флаги Whisper в скрипте

Полный пример: работающий AHK (v1) скрипт

Ниже приведён полный пример скрипта, объединяющий все элементы: переменные, GUI, кнопки и функции. Скопируйте этот блок в ваш .ahk файл и подправьте пути/имена по необходимости.

#NoEnv
#SingleInstance, Force
SendMode Input
SetWorkingDir %A_ScriptDir%

; ------------------------------
; Конфиг: изменяйте здесь
; ------------------------------
OutputFormat = txt
WhisperExecutable = whisper
PromptText = Transcription of YourName's notes

; ------------------------------
; GUI: элементы
; ------------------------------
Gui, Margin, 10, 10
Gui, Add, Text, x5 y5, Язык (language):
Gui, Add, DropDownList, x120 y3 w170 vSelectedLanguage, en||el

Gui, Add, Text, x5 y36, Модель (model):
Gui, Add, DropDownList, x120 y34 w170 vSelectedModel, tiny|base|small||medium|large|

Gui, Add, Text, x5 y67, Задача (task):
Gui, Add, DropDownList, x120 y65 w170 vTaskType, transcribe||translate|

Gui, Add, Text, x5 y98, Prompt (подсказка):
Gui, Add, Edit, x5 y118 w420 h120 vPromptText, %PromptText%

Gui, Add, Button, x5 y246 w200 h30 gSelectFile, Load File
Gui, Add, Button, x215 y246 w210 h30 gSelectFolder, Choose Output Folder
Gui, Add, Button, Default x5 y286 w420 h36 gButtonSubmit, OK

Gui, Show, w440 h340, Whisper GUI
Return

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

SelectFolder:
    FileSelectFolder, SelectedFolder, , 3, Выберите папку для вывода
    if SelectedFolder =
    {
        MsgBox, 48, Папка не выбрана, Вы не выбрали папку.
        Return
    }
    MsgBox, 64, Папка выбрана, %SelectedFolder%
Return

ButtonSubmit:
    Gui, Submit, NoHide
    ; собрать флаги
    WhisperFlags = --initial_prompt "%PromptText%" --task %TaskType% --model %SelectedModel% --language %SelectedLanguage% --output_format %OutputFormat% -o "%SelectedFolder%" "%SelectedFile%"

    ; Скопировать команду в буфер обмена для отладки
    Clipboard = %WhisperExecutable% %WhisperFlags%
    MsgBox, 64, Команда скопирована, Команда скопирована в буфер. Откройте CMD и вставьте для ручной проверки.

    ; Запуск через cmd.exe
    RunWait, cmd.exe /c %WhisperExecutable% %WhisperFlags%
    if ErrorLevel
    {
        MsgBox, 16, Ошибка, Whisper завершил с кодом %ErrorLevel%.
    }
    else
    {
        MsgBox, 64, Готово, Транскрипция завершена. Проверьте папку: %SelectedFolder%
    }
Return

GuiClose:
GuiEscape:
    ExitApp

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

Строки с MsgBox и записью в буфер удобны для отладки. После успешных тестов их можно закомментировать (поставить ‘;’).
Параметры FileSelectFile и FileSelectFolder здесь используют простые фильтры; при желании добавьте другие расширения.

Определение переменных скрипта

Как работает «сборка» команды

Когда пользователь нажимает OK, скрипт выполняет две вещи:

Команда собирается в одну строку: WhisperFlags = –initial_prompt “%PromptText%” –task %TaskType% … “%SelectedFile%”
Затем AHK запускает командную оболочку: RunWait, cmd.exe /c %WhisperExecutable% %WhisperFlags%

Ключевая идея: GUI только заполняет переменные; фактический запуск делегирован стандартному исполняемому файлу whisper.

Добавление флагов Whisper

Отладка: как понять, что пошло не так

Всегда копируйте итоговую команду в буфер и вставляйте в CMD — там часто видно подробные ошибки.
Если Whisper не находит файл, проверьте кавычки и пробелы в путях.
Ошибки парсинга подсказки обычно вызваны отсутствием кавычек вокруг –initial_prompt.
Проверьте, доступен ли whisper в PATH: откройте cmd и выполните whisper --help.

Копирование команды в буфер для проверки

Расширенные приёмы и улучшения (идеи для следующей версии)

Добавить логирование: записывать stdout/stderr Whisper в файл логов и показывать ссылку на лог при ошибке.
Поддержка нескольких файлов: добавить выбор папок и итерацию по всем аудио.
Автоматическое создание подпапок с метками времени.
Поддержка SRT (субтитры): изменить OutputFormat = srt.
Применять пред- и постобработку аудио (нормализация, ресэмпл) через FFmpeg перед запуском Whisper.

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

Если вы предпочитаете Python: используйте Tkinter или PySimpleGUI, чтобы создать кроссплатформенную оболочку и запускать whisper как subprocess.
PowerShell: можно собрать GUI в WinForms/PowerShell и запускать команду Whisper — удобно для администраторов Windows.
Полноценное приложение: на C# (WinForms/WPF) или Electron даст больше контроля над UX, но требует больше усилий.

Когда это не подойдёт (контрпримеры)

Если вам нужна высокая скорость и параллельная обработка десятков файлов — GUI-скрипт под AHK не оптимален.
Если Whisper работает в облаке (агент API), локальная команда не применима: нужно реализовать сетевые запросы и авторизацию.
Для коллективной работы с файлами и правами доступа лучше использовать серверную систему с очередью задач.

Безопасность и приватность

Локальная работа с Whisper не отправляет аудио в сторонние сервисы — сохраняется приватность.
Если вы используете облачный вариант Whisper/API, данные будут переданы внешнему провайдеру; проверьте политику конфиденциальности и требования GDPR.
Храните скрипт и логи в защищённой папке, особенно если аудио содержит персональные данные.

Чек-листы по ролям

Разработчик:

Разместил скрипт в отдельной папке
Установил AutoHotkey v1 и проверил версию
Проверил доступность whisper из CMD
Добавил базовую обработку ошибок (ErrorLevel)
Убрал отладочные MsgBox перед распространением

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

Поместил аудиофайл в доступную папку
Запустил скрипт двойным кликом
Выбрал язык, модель и задачу
Нажал Load File → Choose Output Folder → OK
Проверил файл вывода в папке

Критерии приёмки (Test cases / Acceptance criteria)

При выборе корректного файла и папки команда должна успешно завершиться и создать .txt в указанной папке.
Если путь к файлу содержит пробелы, команда должна корректно обрабатываться (проверить кавычки).
При отсутствии выбранного файла пользователь получает понятное уведомление.
Ошибки Whisper отображаются в виде сообщения и остаются в буфере обмена для ручной проверки.

Runbook: как исправлять ошибки после развёртывания

Запустить скрипт и воспроизвести ошиб — сразу сохранить содержимое буфера обмена (итоговая команда).
Открыть CMD, вставить команду, запустить вручную: прочитать stderr/ошибки.
Частые причины: неверный путь к whisper, отсутствие модели, неправильный формат подсказки.
Проверить exit code (ErrorLevel) и логи. Исправить и повторить.

Короткая методология (mini-methodology)

Минимапликация: реализуйте минимальную функциональность (выбор файла, запуск) и только затем добавляйте «плюшки».
Декомпозиция: каждая кнопка — отдельная функция с небольшим числом задач.
Принцип «fail fast»: уведомляйте пользователя сразу при неверных параметрах.

Небольшой глоссарий (1‑строчный)

Whisper — модель/CLI для распознавания речи; может работать локально или как облачный сервис.
AutoHotkey (AHK) — язык сценариев для автоматизации и создания простых GUI в Windows (v1 и v2 несовместимы).
Prompt — текстовая подсказка, влияющая на формат/терминологию транскрипции.

Советы по совместимости и миграции

Скрипты в AutoHotkey v1 не всегда совместимы с v2; при обновлении AHK перепишите синтаксис.
Если хотите кроссплатформенное приложение (Windows + macOS + Linux), рассмотрите Electron, Python GUI или веб-интерфейс.

Примеры конфигураций (шаблоны)

Быстрая транскрипция на английском, модель small, вывод в txt:

SelectedLanguage = en
SelectedModel = small
TaskType = transcribe
OutputFormat = txt

Перевод (translate) с греческого на английский (пример Prompt указывает контекст):

SelectedLanguage = el
SelectedModel = medium
TaskType = translate
PromptText = “Аудиозапись лекции по истории — сохраняйте даты и имена без сокращений”

Примеры тест-кейсов

Тест A: Файл с именем без пробелов. Ожидаемый результат: создан .txt.
Тест B: Файл с пробелами и кириллицей в пути. Ожидаемый результат: создан .txt (проверить кавычки).
Тест C: Не выбран файл. Ожидаемый результат: MsgBox с предупреждением.

Выбор файла в скрипте

Частые вопросы и быстрые ответы

Вопрос: Можно ли запускать несколько транскрипций параллельно? Ответ: В рамках AHK-скрипта — нет; для параллели используйте отдельные процессов/сервер.
Вопрос: Где хранятся результаты? Ответ: В папке, выбранной в диалоге “Choose Output Folder”.

Заключение и дальнейшие шаги

Вы получили рабочий шаблон для интерфейса Whisper на базе AutoHotkey. Для продакшн-решения рекомендуем:

Автоматизировать логирование и ротацию логов.
Добавить проверку версий (whisper, модели).
Реализовать обработку очереди файлов и опциональную интеграцию с внешними хранилищами (NAS, облако).

Если вы хотите, могу: предоставить перевод GUI-настроек на русский, добавить поддержку пакетной обработки, или подготовить версию на PowerShell/Python.

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

AHK упрощает работу с Whisper, скрывая командную строку.
Основные компоненты: скрытые переменные, GUI элементы, функции выбора и запуска.
Тестирование и отладка — ключ к надёжной работе; используйте буфер обмена и CMD для диагностики.

Показ GUI и возврат