Ошибка UnknownValueError при вызове recognize_google() — самая частая проблема, с которой сталкиваются разработчики при первом запуске распознавания речи в Python: скрипт отрабатывает, микрофон пишет звук, но Google API возвращает пустой ответ. Причина почти всегда кроется не в коде, а в качестве записанного аудио, неверно выбранном языке распознавания или слишком тихом сигнале с микрофона.
В этом руководстве разберём, как работает связка Python + библиотека SpeechRecognition + Google Web Speech API: от установки пакетов до обработки ошибок и записи длинных аудиофайлов. Все примеры кода проверяемы и используют только публичные, общеизвестные возможности библиотеки.
Как работает распознавание речи через Google в Python
Библиотека SpeechRecognition (пакет на PyPI называется именно так) — это обёртка над несколькими движками распознавания речи. Метод recognize_google() отправляет аудиоданные на сервис Google Web Speech API и возвращает расшифрованный текст. Важно понимать: это не официальный платный Google Cloud Speech-to-Text, а бесплатный endpoint, который используется, в частности, в браузере Chrome.
Из этого следуют два практических ограничения. Во-первых, без интернет-соединения метод не работает — аудио уходит на серверы Google. Во-вторых, у бесплатного API есть непубличные лимиты на частоту запросов, поэтому для коммерческих проектов с большим потоком аудио стоит рассмотреть официальный Google Cloud Speech-to-Text с ключом API.
Что делает библиотека «из коробки»:
- 🎤 Захват звука с микрофона через класс
Microphone - 📁 Чтение аудиофайлов (WAV, AIFF, FLAC) через класс
AudioFile - 🌐 Отправка данных в Google, Sphinx (офлайн) и другие движки
- 🔊 Подстройка под уровень фонового шума через
adjust_for_ambient_noise()
Установка SpeechRecognition и зависимостей
Для начала работы вам нужен Python версии 3.7 или выше (актуальные версии библиотеки ориентированы на современные релизы Python — сверьтесь с документацией пакета на PyPI). Установка выполняется через pip:
pip install SpeechRecognitionЕсли планируете захватывать звук с микрофона, дополнительно потребуется PyAudio — именно через него библиотека общается с аудиоустройством:
pip install PyAudio⚠️ Внимание: на Windows установка PyAudio иногда завершается ошибкой сборки из-за отсутствия компилятора. В этом случае проще установить готовый wheel-пакет под вашу версию Python или воспользоваться командойpip install pipwinи далееpipwin install pyaudio. На Linux может потребоваться пакетportaudio19-dev.
Проверить, что всё встало корректно, можно одной строкой в интерпретаторе: импортируйте модуль speech_recognition и выведите его версию через атрибут __version__. Если импорт проходит без исключений — базовая установка завершена.
Первый скрипт: распознавание речи с микрофона
Классический минимальный пример выглядит так: создаём объект Recognizer, открываем микрофон как источник, слушаем фразу и отправляем её в Google.
import speech_recognition as sr
recognizer = sr.Recognizer()
with sr.Microphone() as source:
print("Говорите...")
recognizer.adjust_for_ambient_noise(source, duration=1)
audio = recognizer.listen(source)
try:
text = recognizer.recognize_google(audio, language="ru-RU")
print("Вы сказали:", text)
except sr.UnknownValueError:
print("Речь не распознана")
except sr.RequestError as e:
print("Ошибка сервиса:", e)
Разберём ключевые моменты. Вызов adjust_for_ambient_noise() калибрует порог чувствительности под фоновый шум помещения — без него тихая речь может просто не захватываться. Параметр language="ru-RU" явно указывает русский язык; без него Google по умолчанию ожидает английский, и русская речь распознаётся плохо или не распознаётся вовсе.
Обработка двух исключений обязательна: UnknownValueError означает, что Google не смог разобрать аудио, а RequestError — что запрос до сервиса не дошёл или был отклонён (нет сети, превышен лимит).
☑️ Перед запуском скрипта проверьте
Распознавание речи из аудиофайла
Не всегда источником служит микрофон — часто нужно расшифровать готовую запись. Для этого вместо Microphone используется класс AudioFile, а аудио читается методом record().
import speech_recognition as sr
recognizer = sr.Recognizer()
with sr.AudioFile("recording.wav") as source:
audio = recognizer.record(source)
text = recognizer.recognize_google(audio, language="ru-RU")
print(text)
Здесь есть важный нюанс с форматами. Библиотека нативно понимает WAV, AIFF и FLAC. Файлы MP3, OGG или M4A напрямую не читаются — их нужно предварительно конвертировать, например через ffmpeg или библиотеку pydub.
Метод record() принимает параметры offset (с какой секунды читать) и duration (сколько секунд взять) — это удобно для обработки файла по частям без внешней нарезки.
Сравнение доступных движков распознавания
Библиотека SpeechRecognition поддерживает несколько бэкендов. Выбор зависит от задачи: нужна ли работа офлайн, какая требуется точность и есть ли бюджет.
| Движок | Метод | Интернет | Особенности |
|---|---|---|---|
| Google Web Speech API | recognize_google() | Требуется | Бесплатный, хорошее качество, есть лимиты |
| Google Cloud Speech-to-Text | recognize_google_cloud() | Требуется | Официальный платный API, нужен ключ |
| CMU Sphinx | recognize_sphinx() | Не требуется | Офлайн, но заметно ниже точность |
| Whisper (OpenAI) | recognize_whisper() | Не требуется | Локальная модель, высокая точность, требовательна к ресурсам |
Для русскоязычных проектов без интернета разумной альтернативой является локальный Whisper — он поддерживает русский язык и работает полностью на вашей машине, хотя и требует заметных вычислительных ресурсов.
Типичные ошибки и их решение
При работе с recognize_google() разработчики чаще всего встречают три проблемы. Разберём каждую с конкретными действиями.
UnknownValueError. Сервис получил аудио, но не смог его расшифровать. Возможные причины: слишком тихий сигнал, сильный фоновый шум, неверный код языка, слишком короткий или обрезанный фрагмент. Проверьте уровень записи, увеличьте duration в adjust_for_ambient_noise() и убедитесь, что language соответствует реальной речи.
RequestError. Проблема на сетевом уровне: нет интернета, запросы блокируются файрволом или превышена частота обращений к бесплатному API. Если ошибка возникает при массовой обработке файлов — добавьте паузы между запросами или переходите на платный ключ.
Ошибки PyAudio при открытии микрофона. Обычно означают, что устройство записи занято другим приложением, не выбрано по умолчанию или к нему нет доступа. Закройте программы, использующие микрофон, и проверьте системные разрешения.
⚠️ Внимание: не зашивайте в цикл непрерывные вызовы recognize_google() без пауз и обработки RequestError. Бесплатный endpoint может временно перестать отвечать вашему IP при агрессивной частоте запросов, и скрипт начнёт падать на каждой итерации.
Настройка чувствительности и фильтрация шума
За порог срабатывания микрофона отвечает свойство energy_threshold объекта Recognizer. По умолчанию после вызова adjust_for_ambient_noise() порог подстраивается автоматически, но вы можете задать его вручную, если автоматика работает плохо — например, в очень шумном помещении или, наоборот, при тихой речи.
recognizer.energy_threshold = 300
recognizer.dynamic_energy_threshold = True
Флаг dynamic_energy_threshold включает динамическую подстройку порога во время работы. Дополнительно полезны параметры pause_threshold (сколько секунд тишины считается концом фразы) и phrase_time_limit в методе listen() — он ограничивает максимальную длину одной фразы, чтобы скрипт не зависал в ожидании.
Как подобрать energy_threshold вручную
Запустите скрипт с выводом текущего значения recognizer.energy_threshold после adjust_for_ambient_noise в вашем помещении. Затем поэкспериментируйте: если микрофон срабатывает на шум — повышайте значение, если не слышит тихую речь — понижайте. Типичный диапазон для бытовых микрофонов — от сотен до нескольких тысяч, точное значение зависит от устройства и обстановки.
Итоговые рекомендации
Связка SpeechRecognition + Google Web Speech API — самый быстрый способ добавить распознавание речи в Python-проект: установка занимает пару минут, а рабочий прототип пишется за десяток строк кода. Главное — сразу указать язык, обработать оба исключения и откалибровать микрофон под шум помещения.
Для серьёзных сценариев — массовой транскрибации, работы без сети, строгих требований к приватности — рассмотрите официальный Google Cloud Speech-to-Text или локальный Whisper. Оба варианта поддерживаются той же библиотекой, поэтому миграция не потребует переписывания архитектуры проекта.
Частые вопросы
Работает ли recognize_google() без интернета?
Нет. Метод отправляет аудио на серверы Google, поэтому соединение обязательно. Для офлайн-распознавания используйте recognize_sphinx() или recognize_whisper() — оба работают локально.
Какие языки поддерживает Google Speech Recognition в Python?
Сервис поддерживает десятки языков, включая русский. Язык задаётся параметром language в формате BCP-47, например "ru-RU" для русского или "en-US" для английского. Актуальный список кодов стоит сверять с официальной документацией Google.
Почему Google не распознаёт мой MP3-файл?
Библиотека SpeechRecognition напрямую читает только WAV, AIFF и FLAC. MP3 нужно предварительно конвертировать — например, через ffmpeg или pydub, после чего передать полученный WAV в AudioFile.
Есть ли лимиты у бесплатного Google Web Speech API?
Да, у непубличного бесплатного endpoint есть ограничения на частоту и объём запросов, точные значения официально не публикуются. При превышении вы получите RequestError. Для нагруженных проектов используйте платный Google Cloud Speech-to-Text.
Как распознать длинное аудио, например часовую запись?
Разбейте запись на фрагменты по паузам (например, через pydub.silence.split_on_silence) и отправляйте каждый фрагмент отдельным запросом с паузами между вызовами. За один вызов recognize_google() длинную запись качественно обработать не получится.