Команда pip install SpeechRecognition завершается ошибкой или библиотека ставится, но микрофон не распознаётся — это две самые частые проблемы при установке Speech Recognition в Python. Причина почти всегда одна из трёх: устаревшая версия pip, отсутствующий модуль PyAudio для захвата звука или неправильно выбранный интерпретатор, если на компьютере стоит несколько версий Python.
В этом руководстве разберём установку библиотеки SpeechRecognition от подготовки окружения до первого теста распознавания речи. Инструкция подходит для Windows, macOS и Linux — отличия по шагам указаны отдельно. Точные названия пакетов и команды актуальны для стабильных версий библиотеки, но перед установкой стоит свериться с официальной документацией проекта на PyPI, так как требования могут меняться.
Что потребуется перед установкой
Библиотека SpeechRecognition — это Python-пакет, поэтому базовое требование — установленный интерпретатор Python. Проверить его наличие можно командой в терминале или командной строке:
python --versionЕсли вместо версии вы видите ошибку «команда не найдена», сначала установите Python с официального сайта python.org. На Windows при установке обязательно отметьте галочку Add Python to PATH — без неё команда python не будет работать в командной строке, и это одна из самых частых причин проблем у новичков.
- 🐍 Установленный Python актуальной версии (проверяется командой
python --version) - 📦 Обновлённый менеджер пакетов
pip - 🎤 Рабочий микрофон, если планируется распознавание с микрофона, а не из файла
- 🌐 Доступ в интернет для загрузки пакетов и работы онлайн-движков распознавания
⚠️ Внимание: на Windows команда может называтьсяpyвместоpython. Еслиpython --versionне срабатывает, попробуйтеpy --version— это штатный лаунчер Python для Windows, а не признак ошибки.
Установка библиотеки SpeechRecognition через pip
Основная установка выполняется одной командой. Откройте терминал (на Windows — командную строку или PowerShell) и выполните:
pip install SpeechRecognitionЕсли система сообщает, что pip не найден, используйте вариант с явным вызовом через Python — это гарантирует, что пакет встанет именно в нужный интерпретатор:
python -m pip install SpeechRecognitionПосле завершения установки проверьте результат командой pip show SpeechRecognition — она выведет версию пакета и путь установки. Если пакет отображается, базовая часть завершена. Но для работы с микрофоном этого недостаточно — нужен дополнительный модуль, о котором ниже.
Установка PyAudio для работы с микрофоном
Модуль PyAudio отвечает за захват звука с микрофона. Без него SpeechRecognition сможет обрабатывать только готовые аудиофайлы, а попытка использовать Microphone() вызовет ошибку. Именно на этом шаге установка чаще всего «ломается», особенно на Windows.
Стандартная команда установки:
pip install PyAudioНа Windows эта команда иногда завершается ошибкой сборки, потому что PyAudio требует компиляции нативных компонентов. Возможные пути решения: обновить pip и setuptools, установить готовый wheel-пакет, соответствующий вашей версии Python, либо использовать альтернативный пакет pip install pipwin и затем pipwin install pyaudio. На macOS перед установкой PyAudio обычно требуется поставить PortAudio через Homebrew командой brew install portaudio. На Linux может понадобиться установить системные пакеты разработки — точные названия зависят от дистрибутива, сверьтесь с документацией вашей системы.
☑️ Проверка готовности к распознаванию
⚠️ Внимание: если pip install PyAudio падает с длинным текстом ошибки про компилятор, не пытайтесь устанавливать случайные сборки с непроверенных сайтов. Используйте только официальный PyPI или известные репозитории wheel-пакетов — чужие бинарники могут содержать вредоносный код.
Установка в виртуальном окружении
Устанавливать пакеты глобально — рабочий, но рискованный подход: зависимости разных проектов могут конфликтовать. Правильная практика — виртуальное окружение для каждого проекта. Создаётся оно встроенным модулем venv:
python -m venv venvЗатем окружение нужно активировать. На Windows в командной строке это venv\Scripts\activate, на macOS и Linux — source venv/bin/activate. После активации в начале строки терминала появится пометка (venv), и все последующие команды pip install будут ставить пакеты только в это окружение, не затрагивая системный Python.
Внутри активированного окружения повторите установку SpeechRecognition и PyAudio по инструкции выше. Признак правильной настройки — команда pip list показывает только пакеты вашего проекта, а не всё, что когда-либо ставилось на компьютер.
Проверка установки и первый тест
Быстрая проверка того, что библиотека импортируется корректно, выполняется прямо в терминале:
python -c "import speech_recognition as sr; print(sr.__version__)"Если команда вывела номер версии без ошибок — импорт работает. Следующий шаг — тест распознавания. Минимальный пример кода для распознавания с микрофона через онлайн-движок Google:
import speech_recognition as sr
r = sr.Recognizer()
with sr.Microphone() as source:
print("Говорите...")
audio = r.listen(source)
print(r.recognize_google(audio, language="ru-RU"))
Обратите внимание на параметр language="ru-RU" — без него движок по умолчанию ожидает английскую речь, и русские фразы будут распознаваться плохо или не распознаваться вовсе. Онлайн-движки распознавания требуют активного интернет-соединения: аудио отправляется на внешний сервер, и без сети вызов завершится ошибкой.
Сравнение движков распознавания
Библиотека поддерживает несколько движков, и от выбора зависит, что ещё придётся установить. Офлайн-движки работают без интернета, но требуют дополнительных пакетов и обычно уступают онлайн-сервисам в точности.
| Движок | Режим работы | Дополнительная установка | Особенности |
|---|---|---|---|
| Google Speech Recognition | Онлайн | Не требуется | Работает из коробки, есть ограничения по частоте запросов |
| CMU Sphinx | Офлайн | pip install pocketsphinx | Работает без сети, точность ниже онлайн-сервисов |
| OpenAI Whisper | Локально или API | Отдельная установка whisper | Высокая точность, требователен к ресурсам |
| Google Cloud Speech | Онлайн | pip install google-cloud-speech | Платный API, нужны ключи доступа |
Для первых экспериментов проще всего начать с встроенного вызова recognize_google() — он не требует ничего, кроме уже установленной библиотеки и интернета. Переходить на офлайн-движки имеет смысл, когда нужна работа без сети или конфиденциальность аудиоданных.
Почему recognize_google работает без ключа API
Библиотека использует открытый веб-интерфейс распознавания Google с ограничениями по частоте запросов. Для личных экспериментов этого достаточно, но для коммерческих проектов и высоких нагрузок следует использовать официальный Google Cloud Speech-to-Text API с собственными ключами.
Типичные ошибки и их решение
Даже при правильной установке первый запуск часто сопровождается ошибками. Разберём самые распространённые и способы их диагностики.
- 🔇
UnknownValueError— движок не смог разобрать речь: говорите чётче, уменьшите фоновый шум, проверьте микрофон - 🌐
RequestError— проблема с соединением или сервис недоступен: проверьте интернет - 🎤
OSErrorпри созданииMicrophone()— PyAudio не установлен или микрофон недоступен системе - 📛
ModuleNotFoundError: No module named 'speech_recognition'— пакет установлен в другой интерпретатор или окружение не активировано
Если микрофон в системе работает (проверьте в настройках звука ОС), а Python его не видит, выполните sr.Microphone.list_microphone_names() в интерактивном режиме — команда выведет список устройств, которые видит PyAudio. Пустой список означает проблему на уровне драйверов или разрешений ОС. На macOS, например, терминалу нужно явно выдать доступ к микрофону в настройках конфиденциальности.
Часто задаваемые вопросы
Можно ли использовать Speech Recognition без интернета?
Да, но только с офлайн-движками. Установите pip install pocketsphinx и используйте метод recognize_sphinx(). Учтите, что качество распознавания офлайн-движков обычно ниже, а поддержка русского языка зависит от загруженной языковой модели.
Ошибка при установке PyAudio на Windows — что делать?
Сначала обновите pip: python -m pip install --upgrade pip setuptools wheel, затем повторите установку. Если ошибка компиляции сохраняется, попробуйте pip install pipwin и pipwin install pyaudio — этот инструмент ставит готовые сборки без компиляции.
Поддерживается ли русский язык?
Да, большинство движков поддерживают русский. Передайте параметр языка в метод распознавания, например recognize_google(audio, language="ru-RU"). Список поддерживаемых языков зависит от конкретного движка — уточняйте в его документации.
Можно ли распознавать речь из аудиофайла без микрофона?
Да, PyAudio в этом случае не нужен. Используйте sr.AudioFile("путь_к_файлу.wav") вместо Microphone(). Библиотека напрямую работает с WAV и некоторыми другими форматами; для MP3 может потребоваться предварительная конвертация.
Какая версия Python нужна для SpeechRecognition?
Библиотека поддерживает актуальные версии Python 3. Точные требования к минимальной версии указаны на странице пакета на PyPI — сверьтесь с ними, если используете старый интерпретатор.