Error and Issue Summary

1. Could not find Opus library. Make sure it is installed.

Error Description

(.venv) C:\Users\Junsen\Desktop\learning\xiaozhi-python>python xiaozhi-python.py
Traceback (most recent call last):
  File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\xiaozhi-python.py", line 5, in <module>
    import opuslib
  File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\__init__.py", line 19, in <module>
    from .exceptions import OpusError  # NOQA
  File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\exceptions.py", line 10, in <module>
    import opuslib.api.info
  File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\api\__init__.py", line 20, in <module>
    raise Exception(
Exception: Could not find Opus library. Make sure it is installed.

Solution

1. Windows

   • Download and install the Opus library.
   • Ensure the opuslib related packages are correctly installed.

2. Linux/macOS

   • Run the following commands to install libopus:

     sudo apt-get install libopus-dev  # Ubuntu/Debian
     brew install opus                 # macOS

3. Python package installation

   pip install opuslib

---

2. externally-managed-environment (macOS)

Error Description

(.venv) huangjunsen@huangjunsendeMac-mini py-xiaozhi % pip install -r requirements_mac.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

error: externally-managed-environment

x This environment is externally managed
+-> To install Python packages system-wide, try brew install
    xyz, where xyz is the package you are trying to
    install.

    If you wish to install a Python library that isn't in Homebrew,
    use a virtual environment:

    python3 -m venv path/to/venv
    source path/to/venv/bin/activate
    python3 -m pip install xyz

    If you wish to install a Python application that isn't in Homebrew,
    it may be easiest to use 'pipx install xyz', which will manage a
    virtual environment for you. You can install pipx with

    brew install pipx

    You may restore the old behavior of pip by passing
    the '--break-system-packages' flag to pip, or by adding
    'break-system-packages = true' to your pip.conf file. The latter
    will permanently disable this error.

    If you disable this error, we STRONGLY recommend that you additionally
    pass the '--user' flag to pip, or set 'user = true' in your pip.conf
    file. Failure to do this can result in a broken Homebrew installation.

    Read more about this behavior here: <https://peps.python.org/pep-0668/>

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Solution

1. Install using a virtual environment

   python3 -m venv my_env
   source my_env/bin/activate
   pip install -r requirements.txt

2. Use pipx for global installation

   brew install pipx
   pipx install package_name

3. Force install (not recommended)

   pip install package_name --break-system-packages

---

3. WebSocket connection failed: BaseEventLoop.create_connection() got an unexpected keyword argument 'extra_headers'

Error Description

# Establish WebSocket connection
self.websocket = await websockets.connect(
    self.WEBSOCKET_URL,
    extra_headers=headers # In newer versions, change this to additional_headers=headers
)

Solution

• Newer versions of websockets: change extra_headers to additional_headers.
• Older versions of websockets: change additional_headers to extra_headers.

---

4. No default input/output audio device found

Error Description

AudioCodec - ERROR - Failed to initialize audio device: [Errno -9996] Invalid input device (no default output device)
AudioCodec - WARNING - Unable to initialize audio device: [Errno -9996] Invalid input device (no default output device)

Solution

1. Windows:

   • Enable the microphone and speakers in Sound Settings.

2. Linux/macOS:

   pactl list sources | grep "Name"

3. List available audio devices:

   import pyaudio
   p = pyaudio.PyAudio()
   for i in range(p.get_device_count()):
       print(f"Device {i}: {p.get_device_info_by_index(i)['name']}")

4. Manually specify the audio device:

   stream = p.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, input_device_index=0)

---

5. ModuleNotFoundError: No module named '_tkinter' (common on Mac M4 and below)

Error Description

(.venv) apple@appledeMac-mini py-xiaozhi % python main.py

Traceback (most recent call last):
  File "/Users/apple/Desktop/py-xiaozhi/main.py", line 5, in <module>
    from src.application import Application
  File "/Users/apple/Desktop/py-xiaozhi/src/application.py", line 23, in <module>
    from src.display import gui_display, cli_display
  File "/Users/apple/Desktop/py-xiaozhi/src/display/gui_display.py", line 2, in <module>
    import tkinter as tk
  File "/opt/homebrew/Cellar/python@3.12/3.12.9/Frameworks/Python.framework/Versions/3.12/lib/python3.12/tkinter/__init__.py", line 38, in <module>
    import _tkinter  # If this fails your Python may not be configured for Tk
    ^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named '_tkinter'

Solution

1. Install tcl-tk

   brew upgrade tcl-tk # Usually just this first step is enough

2. Check Homebrew tcl-tk path

   brew info tcl-tk

3. Reinstall Python with tcl-tk linked

   brew install python-tk

4. Manually specify Tcl/Tk paths (if necessary)

   export PATH="/opt/homebrew/opt/tcl-tk/bin:$PATH"
   export LDFLAGS="-L/opt/homebrew/opt/tcl-tk/lib"
   export CPPFLAGS="-I/opt/homebrew/opt/tcl-tk/include"

5. Recreate the virtual environment

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

---

6. opuslib import failed: No module named 'pyaudioop' or '_cffi_backend'

Error Description

Found opus library file: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll
Added DLL search path: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows
Successfully loaded opus.dll: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll
opuslib import failed: No module named 'pyaudioop'
Ensure the opus dynamic library is correctly installed or located in the right place

or

Found opus library file: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll
Added DLL search path: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows
Successfully loaded opus.dll: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll
opuslib import failed: No module named '_cffi_backend'
Ensure the opus dynamic library is correctly installed or located in the right place

Solution

1. Python version compatibility issue

   • This error is usually related to Python version, especially Python 3.13
   • It is recommended to use Python 3.9-3.12

2. Reinstall cffi

   pip uninstall cffi
   pip install cffi

3. opus.dll placement

   • Ensure opus.dll is placed in the correct locations (project root directory and System32 directory)

   # Check if it has been copied to these locations
   C:\Windows\System32\opus.dll
   Project root directory\opus.dll
   Project root directory\libs\windows\opus.dll

4. Install pyaudioop support libraries

   • For the 'pyaudioop' error, try downgrading Python or installing related dependencies

   pip install pyaudio

---

8. error: subprocess-exited-with-error (numpy installation failed)

Error Description

Collecting numpy==2.0.2 (from -r requirements.txt (line 8))
  Using cached https://mirrors.aliyun.com/pypi/packages/a9/75/10dd1f8116a8b796cb2c737b674e02d02e80454bda953fa7e65d8c12b016/numpy-2.0.2.tar.gz (18.9 MB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error

  x Preparing metadata (pyproject.toml) did not run successfully.
  | exit code: 1
  +-> [21 lines of output]
      ...
      WARNING: Failed to activate VS environment: Could not parse vswhere.exe output
      ERROR: Unknown compiler(s): [['icl'], ['cl'], ['cc'], ['gcc'], ['clang'], ['clang-cl'], ['pgcc']]
      The following exception(s) were encountered:
      Running `icl ""` gave "[WinError 2] The system cannot find the file specified."
      Running `cl /?` gave "[WinError 2] The system cannot find the file specified."
      Running `cc --version` gave "[WinError 2] The system cannot find the file specified."
      Running `gcc --version` gave "[WinError 2] The system cannot find the file specified."
      Running `clang --version` gave "[WinError 2] The system cannot find the file specified."
      Running `clang-cl /?` gave "[WinError 2] The system cannot find the file specified."
      Running `pgcc --version` gave "[WinError 2] The system cannot find the file specified."

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

x Encountered error while generating package metadata.
+-> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

Solution

• Recommended Python version: 3.9 - 3.12

1. Ensure numpy version compatibility

   numpy==2.0.2 may have build issues. It is recommended to install a more stable version:

   pip install numpy==1.24.3

   If you don't need a specific version, you can install the latest stable version:

   pip install numpy

2. Install build tools

   Windows users may need to install Visual C++ Build Tools:

   # Install Microsoft C++ Build Tools
   # Download and install: https://visualstudio.microsoft.com/visual-cpp-build-tools/

3. Use pre-built wheels

   pip install --only-binary=numpy numpy

---

9. PaAlsaStreamComponent_BeginPolling: Assertion 'ret == self->nfds' failed (Ubuntu ALSA error)

Error Description

python: src/hostapi/alsa/pa_linux_alsa.c:3641: PaAlsaStreamComponent_BeginPolling: Assertion 'ret == self->nfds' failed.
Aborted (core dumped)

This is a PortAudio/ALSA initialization failure error, manifesting as a crash when starting the audio stream.

Cause Analysis

1. ALSA configuration issue or insufficient audio device permissions
2. PulseAudio/PipeWire conflict with ALSA
3. System audio device not properly configured
4. Incompatible PortAudio library version

Solution

Option 1: Check and fix ALSA configuration

1. Check if audio devices are working

   # List all audio devices
   arecord -l  # Recording devices
   aplay -l    # Playback devices

   If the command outputs "no soundcards found", it means the system did not recognize any audio device.

2. Test audio devices

   # Test recording (press Ctrl+C to stop)
   arecord -f S16_LE -r 16000 -c 1 test.wav
   
   # Test playback
   aplay test.wav

3. Check if ALSA utilities are installed

   sudo apt-get update
   sudo apt-get install -y alsa-utils alsa-base

Option 2: Use PulseAudio (recommended)

Direct ALSA hardware access may have compatibility issues. It is recommended to use PulseAudio as the audio server:

# Install PulseAudio
sudo apt-get install -y pulseaudio pulseaudio-utils

# Start PulseAudio
pulseaudio --start

# Check if PulseAudio is running
pactl info

# List audio devices
pactl list sources | grep "Name"    # Input devices
pactl list sinks | grep "Name"      # Output devices

If PulseAudio is working correctly, Python sounddevice will automatically use PulseAudio instead of directly accessing ALSA.

Option 3: Configure ALSA to use PulseAudio

Create or edit the ~/.asoundrc file:

nano ~/.asoundrc

Add the following content:

pcm.!default {
    type pulse
}

ctl.!default {
    type pulse
}

Then restart the audio service:

pulseaudio --kill
pulseaudio --start

Option 4: Add user to the audio group

# Add current user to audio group
sudo usermod -a -G audio $USER

# Log out and back in for it to take effect, or use this command for temporary effect
newgrp audio

# Check user groups
groups

Option 5: Reinstall PortAudio and sounddevice

# Uninstall Python audio libraries
pip uninstall sounddevice pyaudio -y

# Reinstall system dependencies
sudo apt-get remove --purge portaudio19-dev libportaudio2
sudo apt-get update
sudo apt-get install -y portaudio19-dev libportaudio2 libasound2-dev

# Reinstall Python libraries
pip install sounddevice

Option 6: Check and disable conflicting audio services

In some cases, multiple audio services may conflict:

# Check running audio services
ps aux | grep -E "pulse|pipewire|jack"

# If both PipeWire and PulseAudio are running, it's recommended to keep only one
# Ubuntu 22.04+ uses PipeWire by default, but provides PulseAudio compatibility via pipewire-pulse

# Check PipeWire status
systemctl --user status pipewire pipewire-pulse

Option 7: Use virtual audio device (for testing only)

If hardware devices are problematic, create virtual audio devices for testing:

# Load virtual audio modules
pactl load-module module-null-sink sink_name=virtual_speaker
pactl load-module module-virtual-source source_name=virtual_mic

# View virtual devices
pactl list sources short
pactl list sinks short

Verification

Run the following Python code to test if audio devices are working:

import sounddevice as sd

# List all devices
print(sd.query_devices())

# Test recording and playback
import numpy as np

# Record 2 seconds of audio
print("Recording...")
audio = sd.rec(int(2 * 16000), samplerate=16000, channels=1, dtype=np.int16)
sd.wait()
print("Recording finished")

# Play the recorded audio
print("Playing...")
sd.play(audio, samplerate=16000)
sd.wait()
print("Playing finished")

If the above code runs successfully, the audio device configuration is correct.

Notes

1. Ubuntu 20.04/22.04 use different audio systems by default:

   • Ubuntu 20.04: primarily uses PulseAudio
   • Ubuntu 22.04+: uses PipeWire (PulseAudio-compatible)

2. Headless/remote servers: For display-less server environments, ensure the audio service starts properly:

   # Check audio service
   systemctl --user status pulseaudio

3. Docker/container environments: Containers need the host's audio device mapped:

   docker run --device /dev/snd ...

4. Permission issues: Ensure the /dev/snd/ directory has correct permissions:

   ls -l /dev/snd/