Open Tool Speex

Мощное консольное приложение для эхоподавления и шумоподавления с использованием библиотеки SpeexDSP.

🎯 Готовые бинарники для всех платформ | 🔧 5 режимов обработки | ⚡ Обработка в реальном времени | 🎛️ Тонкая настройка параметров

Возможности

• 🔊 Эхоподавление (Echo Cancellation) - устранение эха от динамиков
• 🔇 Подавление шума (Noise Suppression) - удаление фонового шума
• 🎙️ Обнаружение речи (Voice Activity Detection) - детектор голосовой активности
• 🔉 Автоматическая регулировка усиления (AGC) - нормализация громкости
• ⚙️ 5 режимов обработки: AEC+NS, NS→AEC, NS-only, AEC-only, bypass
• 🕐 Компенсация задержки - использование предыдущего фрейма speaker
• 🎛️ Настраиваемые параметры - точная настройка всех алгоритмов
• 📁 Поддержка A-law PCM 16 кГц моно
• ⚡ Обработка в реальном времени — по умолчанию 320 сэмплов (20 мс), настраивается

Требования

Для разработки

• Linux: Ubuntu 20.04+ / Debian 11+ / другие современные дистрибутивы
• macOS: macOS 11+ с Homebrew
• Windows: Windows 10+ с MinGW-w64/MSYS2 или используйте GitHub Actions
• Go: 1.22+ (рекомендуется последняя версия)
• SpeexDSP: автоматически устанавливается

Для пользователей

• Готовые бинарники доступны в Releases для всех платформ
• Никаких дополнительных зависимостей не требуется (статическая сборка)

Быстрый старт

📦 Скачать готовый бинарник (рекомендуется)

1. Идите в Releases
2. Скачайте версию для вашей платформы:
   • Linux: open_tool_speex-linux
   • macOS: open_tool_speex-macos
   • Windows: open_tool_speex.exe
3. Готово! Никаких зависимостей устанавливать не нужно

🛠 Сборка из исходников

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install libspeexdsp-dev pkg-config golang-go
go build -o open_tool_speex

macOS

brew install speexdsp pkg-config go
go build -o open_tool_speex

🤖 Автоматическая сборка через GitHub Actions

• Fork этот репозиторий
• Push изменения → автоматическая сборка для всех платформ
• Создайте тег v1.0.0 → автоматический релиз с бинарниками

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

# Базовый запуск (16 кГц, 20 мс кадр, хвост 200 мс)
./open_tool_speex -mic microphone.alaw -speaker speaker.alaw -output clean_output.alaw

# Кадр 10 мс (160 сэмплов), хвост 150 мс, 16 кГц
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output out.alaw \
  -sample-rate 16000 -frame-size 160 -echo-tail 150

# Явная длина фильтра 4096 сэмплов (перекрывает echo-tail)
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output out.alaw \
  -filter-len 4096

Основные параметры

Параметр	Описание
-mic	🎤 Входной файл с микрофона (raw A-law, 16 кГц моно)
-speaker	🔊 Референсный файл с динамика (raw A-law, 16 кГц моно)
-output	💾 Выходной файл (по умолчанию: output.alaw)
-prev-speaker	⏱️ Компенсация задержки (предыдущий фрейм speaker)
-ns-first	🔄 NS → AEC (по умолчанию: AEC → NS)
-ns-only	🔇 Только подавление шума (speaker не нужен)
-aec-only	🔊 Только эхоподавление
-bypass	⚡ Обход обработки (для тестирования)
-help	❓ Показать справку

Параметры обработки сигналов

Параметр	Описание
-sample-rate	Частота дискретизации в Гц (по умолчанию: 16000)
-frame-size	Размер кадра в сэмплах (по умолчанию: 320)
-echo-tail	Длина хвоста эха в мс (по умолчанию: 200)
-filter-len	Длина фильтра эха в сэмплах (если >0, перекрывает -echo-tail)

Тонкая настройка шумодава

Параметр	Описание	По умолчанию
-noise-suppress	🎚️ Уровень подавления шума в дБ (больше отрицательное = больше подавления)	-15.0
-vad	🎙️ Включить детектор голосовой активности	выключен
-vad-prob-start	🟢 Порог начала речи для VAD (0-100)	80
-vad-prob-continue	▶️ Порог продолжения речи для VAD (0-100)	65
-agc	🔉 Включить автоматическую регулировку усиления	выключен
-agc-level	📊 Целевой RMS уровень для AGC	30000.0

Компенсация задержки

Опция -prev-speaker использует предыдущий фрейм speaker с текущим фреймом microphone. Это полезно для компенсации задержки обработки в системах реального времени:

# Обычный режим: mic[n] + speaker[n] -> output[n]
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output normal.alaw

# Режим с компенсацией: mic[n] + speaker[n-1] -> output[n]  
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output delayed.alaw -prev-speaker

🎛️ Режимы обработки

Доступно 5 режимов обработки аудио:

# 1. 🔊🔇 AEC → NS (по умолчанию): эхоподавление, затем шумоподавление
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output aec_first.alaw

# 2. 🔇🔊 NS → AEC: шумоподавление, затем эхоподавление  
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output ns_first.alaw -ns-first

# 3. 🔇 Только NS: только шумоподавление (speaker файл не нужен)
./open_tool_speex -mic mic.alaw -output ns_only.alaw -ns-only

# 4. 🔊 Только AEC: только эхоподавление (speaker файл обязателен)
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output aec_only.alaw -aec-only

# 5. ⚡ Bypass: без обработки (для тестирования и диагностики)
./open_tool_speex -mic mic.alaw -output unchanged.alaw -bypass

# 🕐 Дополнительно: любой режим с компенсацией задержки (кроме NS-only и bypass)
./open_tool_speex -mic mic.alaw -speaker spk.alaw -output delayed.alaw -aec-only -prev-speaker

Когда использовать NS-first:

• Высокий уровень фонового шума в микрофоне
• Необходимость улучшить качество сигнала перед эхоподавлением
• Экспериментальные настройки для конкретных сценариев

Режим только подавления шума

Опция -ns-only применяет только подавление шума без эхоподавления. В этом режиме speaker файл не требуется:

# Только подавление шума (speaker файл не нужен)
./open_tool_speex -mic noisy_audio.alaw -output clean_audio.alaw -ns-only

Когда использовать NS-only:

• Обработка записей без эха (студийные записи, интервью)
• Удаление фонового шума из аудиофайлов
• Предобработка аудио перед другими алгоритмами
• Быстрая очистка от шума без AEC overhead'а

Режим только эхоподавления

Опция -aec-only применяет только эхоподавление без подавления шума. Speaker файл обязателен:

# Только эхоподавление (speaker файл обязателен)
./open_tool_speex -mic mic_with_echo.alaw -speaker reference.alaw -output clean.alaw -aec-only

# AEC с компенсацией задержки
./open_tool_speex -mic mic.alaw -speaker ref.alaw -output clean.alaw -aec-only -prev-speaker

Когда использовать AEC-only:

• Чистые записи с эхом (без фонового шума)
• Телефонные/VoIP звонки с эхом
• Когда нужно сохранить оригинальные характеристики звука
• Предобработка для других алгоритмов шумоподавления

Примеры настройки шумодава

# Стандартное подавление шума
./open_tool_speex -mic noisy.alaw -output clean.alaw -ns-only

# Агрессивное подавление шума (может ухудшить качество речи)
./open_tool_speex -mic noisy.alaw -output clean.alaw -ns-only -noise-suppress -25

# Мягкое подавление шума для сохранения качества речи
./open_tool_speex -mic noisy.alaw -output clean.alaw -ns-only -noise-suppress -8

# С включенным VAD (детектор речи)
./open_tool_speex -mic noisy.alaw -output clean.alaw -ns-only -vad -vad-prob-start 85

# С автоматической регулировкой громкости
./open_tool_speex -mic quiet.alaw -output loud.alaw -ns-only -agc -agc-level 35000

# Полная конфигурация: NS + VAD + AGC
./open_tool_speex -mic input.alaw -output output.alaw -ns-only \
  -noise-suppress -12 -vad -vad-prob-start 75 -vad-prob-continue 60 \
  -agc -agc-level 28000

Рекомендации по настройке

Уровень подавления шума (-noise-suppress):

• -5 до -10 - легкое подавление, хорошее качество речи
• -15 - стандартное (по умолчанию), баланс качества и очистки
• -20 до -30 - агрессивное, может исказить речь

VAD настройки:

• vad-prob-start 70-85 - чувствительность детектора начала речи
• vad-prob-continue 60-70 - чувствительность продолжения речи
• Высокие значения = менее чувствительный детектор

AGC настройки:

• 20000-40000 - типичный диапазон RMS уровней
• Меньше значение = тише выход, больше = громче выход

Формат файлов

Входные и выходные файлы должны быть в формате:

• Raw A-law PCM (без заголовков)
• 16 кГц частота дискретизации
• Моно (1 канал)
• 8 бит на сэмпл

Создание тестовых файлов

Из WAV в A-law:

# С помощью FFmpeg
ffmpeg -i input.wav -ar 16000 -ac 1 -f alaw output.alaw

# С помощью SoX  
sox input.wav -t al -r 16000 -c 1 output.alaw

Из A-law в WAV:

# С помощью FFmpeg
ffmpeg -f alaw -ar 16000 -ac 1 -i input.alaw output.wav

# С помощью SoX
sox -t al -r 16000 -c 1 input.alaw output.wav

🏗 Архитектура

Файл	Описание
main.go	🖥️ CLI интерфейс, парсинг параметров, основной цикл обработки
alaw.go	🔧 A-law кодек (кодирование/декодирование) с оптимизированными таблицами
speex_aec.go	🔗 cgo обертка для SpeexDSP (AEC, NS, VAD, AGC)
.github/workflows/	🤖 GitHub Actions для автоматической сборки всех платформ

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

• 🚀 Обработка в реальном времени на современных системах
• 📊 Прогресс выводится каждые ~16 секунд (800 фреймов)
• 💾 Потребление памяти: ~10 МБ (включая буферы SpeexDSP)
• 🎯 Оптимизированные кодеки: таблицы A-law для быстрого преобразования
• 🔧 Статическая сборка: без внешних зависимостей в runtime

Примеры использования

Базовое эхоподавление

./open_tool_speex -mic recorded_call.alaw -speaker playback_reference.alaw

С указанием выходного файла

./open_tool_speex -mic mic.alaw -speaker spk.alaw -output cleaned.alaw

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

"Голос превращается в хаос"

• 🔧 Решение: Используйте мягкие настройки NS: -noise-suppress -8
• 🎚️ Причина: Агрессивные настройки по умолчанию (-15 дБ)
• 🧪 Тест: Используйте -bypass для проверки исходного качества

Плохое качество при -ns-only

• 🎛️ Попробуйте: -noise-suppress -5 до -10 для лучшего качества речи
• 🎙️ Включите VAD: -vad -vad-prob-start 75
• 🔉 Добавьте AGC для нормализации: -agc -agc-level 25000

Ошибки сборки на Windows

• 🐳 Рекомендуется: Используйте GitHub Actions для автоматической сборки
• ⚙️ Альтернатива: Скачайте готовый бинарник из Releases

"no such file or directory"

• 📁 Убедитесь, что входные файлы существуют
• 🔧 Создайте тестовые файлы через FFmpeg/SoX (см. раздел выше)

⚠️ Лимитации

• 📁 Синхронизация: Файлы должны быть синхронизированы по времени
• 🎵 Формат: Только моно A-law 16 кГц (без заголовков)
• ⏱️ Echo tail: Максимум 200 мс (фиксированный)
• 🔧 Зависимости: Для сборки нужен SpeexDSP (готовые бинарники его не требуют)

🤝 Поддержка

• 📋 Issues: GitHub Issues для баг-репортов
• 💡 Предложения: GitHub Discussions для идей
• 📖 Документация: Wiki с подробными гайдами (если доступно)

---

🎉 Готово к использованию!

Быстрый старт за 3 шага:

1. 📦 Скачайте готовый бинарник из Releases
2. 🎵 Подготовьте A-law файлы (16 кГц моно)
3. 🚀 Запустите: ./open_tool_speex -mic input.alaw -speaker ref.alaw

Или автоматическая сборка:

1. 🍴 Fork этот репозиторий
2. 📤 Push изменения
3. 🤖 GitHub Actions соберет для всех платформ автоматически!

Сделано с ❤️ для сообщества разработчиков аудио

💡 Tip: Начните с -bypass режима для тестирования, затем попробуйте -ns-only с мягкими настройками (-noise-suppress -8)