Troubleshooting#

Service Will Not Start#

  • Confirm port 8010 is not already in use:

    ss -ltnp | grep 8010

  • Confirm the active config file is valid YAML. The service loads config.yaml, then applies AUDIO_ANALYZER__... environment overrides. The same config.yaml is used by both standalone and container runs (bind-mounted into the container).

First Startup Is Slow#

This is expected. On first run the service may download or export model assets to models/ and the Hugging Face cache. Subsequent starts reuse the cached artifacts.

health Endpoint Fails#

  • For Docker: check docker compose ps and docker compose logs -f audio-analyzer.

  • For standalone: confirm the process is running and bound to the expected host/port (defaults 127.0.0.1:8010).

  • If you are behind a corporate proxy, pass --noproxy '*' to curl when hitting 127.0.0.1.

GPU Path Is Not Used#

  • The OpenVINO GPU device requires the Intel/OpenVINO host GPU runtime installed on the host (separate from the Python dependencies).

  • For the container, /dev/dri must be exposed to the container (default in docker-compose.yml).

Permission Errors on Mounted Folders#

The container runs as UID/GID 1000:1000 by default (set via user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}" in docker-compose.yml). If your host user has a different UID/GID, the container will write into the mounted folders (models/, chunks/, storage/, .cache/huggingface/) as 1000:1000, which can lead to errors such as:

PermissionError: [Errno 13] Permission denied: '/app/audio_analyzer/storage/...'

or, on the host side:

mkdir: cannot create directory 'models/...': Permission denied

This can also happen when a bind-mount source path does not exist on the host. Docker Compose may create the missing directory as root before the container starts. Fresh clones of this repository include placeholder files for the expected mount roots, but if you deleted models/, chunks/, storage/, or .cache/huggingface/, recreate them as your user first.

To fix this, start the container with your host user’s UID/GID so the mounted folders stay writable from both Docker and standalone runs:

LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose up -d --build

Or persist it by creating a local .env file in the audio_analyzer/ directory:

LOCAL_UID=$(id -u)
LOCAL_GID=$(id -g)

After that, plain docker compose up -d --build will pick up your IDs.

If the directories already exist as root, repair them once on the host:

mkdir -p models chunks storage .cache/huggingface
sudo chown -R "$(id -u):$(id -g)" models chunks storage .cache

Microphone / GET /devices Returns Empty#

  • Confirm ALSA capture devices exist on the host:

    arecord -l

  • For the container, uncomment the /dev/snd device mapping in docker-compose.yml.

FFmpeg or libsndfile Errors (Standalone)#

Install the required host packages:

sudo apt-get update
sudo apt-get install -y ffmpeg alsa-utils libsndfile1

Sessions / Transcripts Not Persisting#

Session files live under storage/<session_id>/. Confirm that directory is writable by the process and is on a persistent volume in container deployments.

Supporting Resources#