GigaAM v3 Transcriber

Приложение для транскрибации аудио и видео файлов с использованием модели GigaAM-v3 от Sber.

Важно: Данная реализация работает благодаря компании Sber (ПАО «Сбербанк») и их команде разработки модели GigaAM-v3 — современной модели распознавания русской речи. Модель доступна на HuggingFace и в официальном репозитории.

🎉 Что нового в v3.0 (3 декабря 2025)

✨ Понятные имена файлов результатов - теперь audio.txt вместо fa923831...audio.txt
📊 Batch мониторинг прогресса - новый эндпоинт /api/v1/tasks/progress/batch для отслеживания множества задач
🔧 Исправлен batch download - корректная работа с ZIP архивами
📝 Полная документация - подробные схемы, диаграммы и руководства
🎨 Обновленная Postman коллекция - с новыми эндпоинтами и визуализацией
🔐 Безопасность - все секреты теперь в .env файле, код не содержит токенов
💾 Унифицированное сохранение папок - входная и выходная папки сохраняются при закрытии программы
🎨 Улучшенный интерфейс GUI - аккуратное расположение кнопок и разделение блоков настроек

🎯 Три способа использования

GigaAM v3 Transcriber предоставляет три режима работы на выбор:

1. 🖥️ GUI (Графический интерфейс)

python app.py

Простой и понятный интерфейс
Выбор файлов через диалоги
Визуальный прогресс-бар
Для кого: локальное использование, разовые задачи

2. 💻 CLI (Командная строка)

python cli.py                          # Интерактивный режим
python cli.py -d /path/to/files        # Обработка директории
python cli.py -f audio.mp3 -f video.mp4  # Конкретные файлы

Интерактивные меню
Цветной вывод и прогресс-бары
Пакетная обработка
Работает без GUI (SSH)
Для кого: серверы, автоматизация, скрипты

3. 🌐 REST API (Веб-сервис)

curl -X POST "http://localhost:8000/api/v1/transcribe" \
  -H "X-API-Key: your_api_key" \
  -F "file=@audio.mp3"

Доступ из любой точки интернета
HTTPS + аутентификация через API ключи
Асинхронная обработка
Swagger UI документация
Для кого: интеграция в приложения, удаленный доступ

Возможности

Транскрибация аудио и видео файлов на русском языке
Поддержка множества форматов: mp3, wav, m4a, mp4, avi, mov, mkv, webm, flac, ogg, wma
Автоматическая сегментация длинных записей
Три интерфейса: GUI, CLI, REST API
Прогресс-бар с прогнозом времени завершения
Статистика обработки и самообучающийся прогноз на основе длительности файлов
Вывод в двух форматах: чистый текст и текст с таймкодами
Поддержка GPU ускорения (CUDA на Windows/Linux, MPS на macOS)
Автоматическое логирование всех операций с организацией по датам и времени
Автоматическая очистка старых логов (старше 30 дней)
REST API с доступом из интернета через HTTPS
Безопасность: все секреты хранятся в .env файле

Системные требования

Windows

Windows 10/11
Python 3.10 или выше
8 GB RAM (рекомендуется 16 GB)
10 GB свободного места на диске
NVIDIA GPU с CUDA (опционально, для ускорения)

macOS(только Apple Silicon)

macOS 11.0 или выше (Big Sur+)
Python 3.10 или выше
8 GB RAM (рекомендуется 16 GB)
10 GB свободного места на диске
Apple Silicon (M1/M2/M3) для MPS ускорения (опционально)

Linux

Ubuntu 20.04+ или другой современный дистрибутив
Python 3.10 или выше
8 GB RAM (рекомендуется 16 GB)
10 GB свободного места на диске
NVIDIA GPU с CUDA (опционально, для ускорения)

Быстрая установка

Windows

Установите Python 3.10 или выше с python.org
Установите FFmpeg:
- Скачайте с ffmpeg.org
- Добавьте в PATH
Установите зависимости:

pip install -r requirements.txt
cd GigaAM
pip install -e .

Настройте конфигурацию (см. раздел "Настройка" ниже)

macOS

Установите Homebrew (если еще не установлен):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Установите зависимости:

brew install python@3.10 ffmpeg

Создайте окружение и установите пакеты:

conda create -n gigaam python=3.10 -y
conda activate gigaam
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
cd GigaAM
pip install -e .

Настройте конфигурацию (см. раздел "Настройка" ниже)

Linux

Установите Python и FFmpeg:

sudo apt update
sudo apt install python3.10 python3.10-venv ffmpeg

Создайте виртуальное окружение:

python3.10 -m venv venv
source venv/bin/activate

Установите зависимости:

pip install -r requirements.txt
cd GigaAM
pip install -e .

Настройте конфигурацию (см. раздел "Настройка" ниже)

⚙️ Настройка

Все настройки приложения хранятся в файле .env. Это обеспечивает безопасность и удобство управления конфигурацией.

Шаг 1: Создание файла конфигурации

Скопируйте шаблон конфигурации:

cp .env.example .env

Шаг 2: Настройка HuggingFace токена

Обязательно! Для работы приложения требуется токен HuggingFace.

Зарегистрируйтесь на huggingface.co
Создайте токен доступа: huggingface.co/settings/tokens
- Выберите тип токена: "Read" (достаточно для загрузки моделей)
Примите условия использования модели: huggingface.co/pyannote/segmentation-3.0
Откройте файл .env и замените значение:

HF_TOKEN=your_huggingface_token_here

Замените your_huggingface_token_here на ваш реальный токен (он начинается с hf_)

Шаг 3: Настройка API (опционально, только для REST API)

Если вы планируете использовать REST API, настройте параметры в .env:

# API Server
API_HOST=127.0.0.1        # Для локального доступа
# API_HOST=0.0.0.0       # Для доступа из сети
API_PORT=8000
API_WORKERS=2

# API Limits
MAX_FILE_SIZE=2147483648      # 2GB в байтах
MAX_CONCURRENT_TASKS=3        # Одновременных задач
TASK_CLEANUP_HOURS=24         # Автоочистка старых задач

# API Directories
UPLOAD_DIR=uploads
RESULTS_DIR=results

Важно: Файл .env уже добавлен в .gitignore и не будет попадать в репозиторий. Никогда не коммитьте файл .env с реальными токенами!

🚀 Быстрый запуск

GUI (Графический интерфейс)

Windows:

python app.py

macOS:

conda activate gigaam
python app.py

Linux:

source venv/bin/activate
python app.py
# или используйте скрипт
./scripts/run_gui.sh

CLI (Командная строка)

Интерактивный режим:

python cli.py
# или
./scripts/run_cli.sh

Обработка директории:

python cli.py -d /path/to/audio/files -o /path/to/output

Обработка конкретных файлов:

python cli.py -f audio1.mp3 -f audio2.wav -f video.mp4 -o /output

Неинтерактивный режим (для скриптов):

python cli.py -d /data/incoming -o /data/results -n -v

REST API (Веб-сервис)

Локальный запуск

Запуск API сервера:

python api.py

Или через uvicorn:

uvicorn api:app --host 127.0.0.1 --port 8000

Получение API ключа

При первом запуске API автоматически создаст файл .api_keys и сгенерирует первый API ключ. Ключ будет выведен в консоль:

============================================================
ПЕРВЫЙ API КЛЮЧ СОЗДАН:
  gam_abc123def4
Сохраните его в безопасном месте!
============================================================

Просмотр существующих ключей:

cat .api_keys

Тестирование API

1. Проверка здоровья сервиса (без API ключа):

curl http://localhost:8000/health

2. Получение информации о сервисе:

curl http://localhost:8000/

3. Загрузка файла для транскрибации:

curl -X POST "http://localhost:8000/api/v1/transcribe" \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@audio.mp3"

Ответ:

{
  "task_id": "abc123def456...",
  "message": "Файл успешно загружен и отправлен на обработку",
  "filename": "audio.mp3",
  "file_size": 1234567,
  "estimated_time": "Оценка будет доступна после начала обработки"
}

4. Проверка статуса задачи:

curl -X GET "http://localhost:8000/api/v1/tasks/abc123def456..." \
  -H "X-API-Key: your_api_key_here"

5. Получение результата:

curl -X GET "http://localhost:8000/api/v1/tasks/abc123def456.../result" \
  -H "X-API-Key: your_api_key_here"

6. Скачивание результата:

# Текст без таймкодов
curl -X GET "http://localhost:8000/api/v1/tasks/abc123def456.../download?format=txt" \
  -H "X-API-Key: your_api_key_here" \
  -o result.txt

# Текст с таймкодами
curl -X GET "http://localhost:8000/api/v1/tasks/abc123def456.../download?format=timecodes" \
  -H "X-API-Key: your_api_key_here" \
  -o result_timecodes.txt

Swagger UI документация

После запуска API откройте в браузере:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Здесь вы найдете полную интерактивную документацию всех эндпоинтов.

Production развертывание

Для production развертывания используйте скрипты из папки deploy/:

# Установка и настройка
sudo ./deploy/setup_production.sh

# Или только установка API
sudo ./deploy/install_api.sh

Важно для production:

Измените API_HOST=0.0.0.0 в .env для доступа из сети
Настройте reverse proxy (nginx) для HTTPS
Используйте systemd для автозапуска
Настройте firewall для безопасности

Использование

GUI

Запустите приложение: python app.py
Нажмите "Выбрать файлы"
Выберите один или несколько аудио/видео файлов
(Опционально) Нажмите "Папка сохранения" для выбора каталога вывода
Нажмите "ЗАПУСТИТЬ ОБРАБОТКУ"
Дождитесь завершения обработки

CLI

См. раздел "CLI (Командная строка" выше.

API

См. раздел "REST API (Веб-сервис)" выше.

Результаты

Для каждого обработанного файла создается два файла:

имя_файла.txt - чистый текст транскрибации
имя_файла_timecodes.txt - текст с временными метками

По умолчанию файлы сохраняются в той же папке, где находится исходный файл (для GUI/CLI) или в директории RESULTS_DIR (для API).

Структура проекта

GigaAMv3/
├── app.py                      # Точка входа GUI приложения
├── cli.py                      # CLI интерфейс
├── api.py                      # REST API сервер
├── requirements.txt            # Зависимости для Windows/Linux
├── requirements_macos.txt      # Зависимости для macOS
├── .env.example                # Шаблон конфигурации
├── .env                        # Ваша конфигурация (не коммитится!)
├── .api_keys                   # API ключи (не коммитится!)
├── src/                        # Исходный код
│   ├── config.py              # Загрузка конфигурации из .env
│   ├── core/                  # Основная логика
│   │   ├── model_loader.py    # Загрузка модели GigaAM
│   │   └── processor.py       # Обработка транскрибации
│   ├── gui/                   # Графический интерфейс
│   │   └── app.py            # GUI приложение
│   └── utils/                 # Утилиты
│       ├── audio_converter.py # Конвертация через FFmpeg
│       ├── time_formatter.py  # Форматирование времени
│       ├── processing_stats.py # Статистика
│       └── pyannote_patch.py  # Патчи совместимости
├── GigaAM/                    # Библиотека GigaAM
├── scripts/                   # Скрипты запуска
├── deploy/                    # Скрипты развертывания
└── docs/                      # Документация

Технологии

Ядро распознавания речи

GigaAM-v3 (Sber) — современная модель автоматического распознавания русской речи

Фреймворки и библиотеки

Python 3.10+ — основной язык программирования
PyTorch 2.6.0 — фреймворк глубокого обучения
Transformers (HuggingFace) — работа с transformer-моделями
Pyannote.audio — сегментация и обработка аудио
FastAPI — современный REST API фреймворк
python-dotenv — загрузка переменных окружения

Интерфейс и медиа

CustomTkinter — современный графический интерфейс
FFmpeg — конвертация аудио и видео файлов

Производительность

Время обработки (примерные значения)

Длительность аудио	CPU	GPU (CUDA/MPS)
1 минута	30-60 сек	15-25 сек
5 минут	2.5-5 мин	1-2 мин
30 минут	15-30 мин	5-10 мин
1 час	30-60 мин	10-20 мин

Время зависит от конфигурации компьютера и качества аудио.

Решение проблем

Ошибка импорта pyannote.audio

AttributeError: `np.NaN` was removed in the NumPy 2.0 release

Патч применяется автоматически при запуске.

FFmpeg не найден

Убедитесь, что FFmpeg установлен и добавлен в PATH:

ffmpeg -version

Недостаточно памяти

Обрабатывайте файлы по одному, закройте другие приложения, увеличьте swap/pagefile.

Ошибка "HuggingFace токен не настроен"

Убедитесь, что файл .env существует
Проверьте, что HF_TOKEN установлен в .env
Убедитесь, что токен начинается с hf_
Перезапустите приложение после изменения .env

API возвращает 401 Unauthorized

Проверьте, что заголовок X-API-Key присутствует в запросе
Убедитесь, что API ключ правильный (проверьте в .api_keys)
Убедитесь, что API ключ не содержит лишних пробелов

Безопасность

Хранение секретов

Все секреты хранятся в .env файле: (пример присутствует)

HuggingFace токен (HF_TOKEN)
API ключи (в файле .api_keys, путь настраивается через API_KEYS_FILE)

API безопасность

Все эндпоинты (кроме /health и /) требуют API ключ
API ключи генерируются автоматически при первом запуске
Rate limiting защищает от злоупотреблений
CORS настраивается через переменные окружения

Благодарности

Данная реализация работает благодаря:

Sber (ПАО «Сбербанк») — разработка и предоставление модели GigaAM-v3, современной модели транскрибации русской речи
Команда GigaAM — за создание высококачественной модели распознавания речи
HuggingFace — за инфраструктуру и библиотеки для работы с transformer-моделями
Pyannote.audio — за инструменты сегментации и обработки аудио

Контрибьютинг

Приветствуются pull request'ы и issue reports. Перед отправкой PR убедитесь, что:

Код следует стилю проекта
Добавлены комментарии на русском языке
Проведено тестирование на вашей платформе
Нет хардкодных секретов в коде

Поддержка

При возникновении проблем:

Проверьте настройки в .env
Создайте issue на GitHub с подробным описанием проблемы

GigaAM v3 Transcriber - простой и эффективный инструмент для транскрибации аудио на русском языке.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
GigaAM @ 0a3f103		GigaAM @ 0a3f103
deploy		deploy
docs		docs
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
README.md		README.md
api.py		api.py
app.py		app.py
cli.py		cli.py
requirements.txt		requirements.txt

wwwmplusm/GigaAMGUI_fixUI

Folders and files

Latest commit

History

Repository files navigation

GigaAM v3 Transcriber

🎉 Что нового в v3.0 (3 декабря 2025)

🎯 Три способа использования

1. 🖥️ GUI (Графический интерфейс)

2. 💻 CLI (Командная строка)

3. 🌐 REST API (Веб-сервис)

Возможности

Системные требования

Windows

macOS(только Apple Silicon)

Linux

Быстрая установка

Windows

macOS

Linux

⚙️ Настройка

Шаг 1: Создание файла конфигурации

Шаг 2: Настройка HuggingFace токена

Шаг 3: Настройка API (опционально, только для REST API)

🚀 Быстрый запуск

GUI (Графический интерфейс)

CLI (Командная строка)

REST API (Веб-сервис)

Локальный запуск

Получение API ключа

Тестирование API

Swagger UI документация

Production развертывание

Использование

GUI

CLI

API

Результаты

Структура проекта

Технологии

Ядро распознавания речи

Фреймворки и библиотеки

Интерфейс и медиа

Производительность

Время обработки (примерные значения)

Решение проблем

Ошибка импорта pyannote.audio

FFmpeg не найден

Недостаточно памяти

Ошибка "HuggingFace токен не настроен"

API возвращает 401 Unauthorized

Безопасность

Хранение секретов

API безопасность

Благодарности

Контрибьютинг

Поддержка

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages