Configuration#

Load Order#

The service loads configuration in this order:

  1. config.yaml

  2. Environment variables with the AUDIO_ANALYZER__... prefix

The same config.yaml is used for both Docker and standalone runs. In Docker, config.yaml is bind-mounted into the container, so edits on the host take effect after the container reloads the file.

Important: docker compose restart is only reliable if the host edit rewrites config.yaml in place (same inode). Most editors, sed -i, and mv-based saves replace the file with a new inode, and Docker’s single-file bind mount keeps pointing at the old (now-detached) inode — so restart can silently keep serving the stale config. Use docker compose up -d --force-recreate after editing config.yaml to guarantee the container picks up the change; restart is not guaranteed to.

Config File#

  • config.yaml: single source of truth for both standalone and container runs.

Environment Variables#

  • AUDIO_ANALYZER_CONFIG_PATH: alternate base config file (advanced)

  • AUDIO_ANALYZER_ENV_FILE: optional .env file to preload before config parsing

  • AUDIO_ANALYZER_SERVER_HOST: host used by python main.py

  • AUDIO_ANALYZER_SERVER_PORT: port used by python main.py

Targeted config overrides use the AUDIO_ANALYZER__... prefix.

Example:

AUDIO_ANALYZER__MODELS__ASR__DEVICE=GPU python main.py

Key Sections#

  • models.asr: backend provider, model name, device, export precision, decoding settings

  • audio_preprocessing: chunk size, silence detection, denoise and loudness-normalization filters, chunk directory

  • audio_util: max file size, allowed extensions, upload read chunk size

  • minio: external MinIO endpoint/credentials, used only by POST /transcriptions when a MinIO source is supplied instead of a direct file upload

  • pipeline.delete_chunks_after_use: whether temporary chunks are removed after processing

  • sentiment: enablement, provider, model, device, aggregation settings

Common Values#

  • models.asr.provider: openai | openvino | whispercpp | funasr

  • models.asr.device: CPU | GPU | NPU

  • models.asr.weight_format: OpenVINO export precision such as int8, fp16, or null; for whispercpp, quantization such as q5, q5_0, q5_1, q8, q8_0, int5, int8, or null

  • sentiment.enabled: true or false

  • sentiment.provider: openvino or pytorch

  • sentiment.weight_format: optional OpenVINO export precision such as int8, fp16, or null

ASR Provider Notes#

  • openai: uses openai-whisper to download official PyTorch Whisper weights directly into Audio Analyzer’s model directory on first use; it does not use Model Download.

  • openvino: exports the configured Whisper model to OpenVINO IR under models/openvino/... and supports CPU, GPU, and NPU (when available and correctly configured).

  • whispercpp: downloads the matching whisper.cpp ggml model under models/whispercpp/... and runs on CPU only.

  • funasr: loads Paraformer, VAD, and punctuation snapshots from ModelScope; requires the optional INSTALL_CJK=true image build.

Audio Analyzer provisions the snapshots this configuration selects on startup: it reuses valid snapshots on the models volume, requests missing ones from a shared Model Download REST service when AUDIO_ANALYZER_MODEL_DOWNLOAD_URL is set and reachable (optionally tuned with AUDIO_ANALYZER_MODEL_DOWNLOAD_TIMEOUT_SEC), and otherwise downloads them directly from Hugging Face / ModelScope. AUDIO_ANALYZER_MODEL_DIRECT_DOWNLOAD=false forbids in-container downloads. See Where model snapshots come from. OpenVINO conversion still runs in Audio Analyzer, using the local source snapshot; native OpenAI Whisper and optional sentiment keep their direct-download behavior.

ASR Provider/Device Matrix#

  • openai: CPU only

  • whispercpp: CPU only

  • funasr: CPU only

  • openvino: CPU | GPU | NPU

If an invalid provider/device combination is configured, startup fails with a clear validation error.

Preview ASR pool (optional)#

models.asr.preview configures a second ASR model pool used only by the realtime input_audio_buffer.preview event, which returns a throwaway snapshot of the trailing audio while the speaker is still talking. Committed transcripts and POST /v1/audio/transcriptions always run on the main models.asr model, so enabling a preview pool never changes final output.

The block is absent by default; previews then reuse the main model and no second model is loaded or exported. Every key is optional and falls back to the corresponding models.asr value, so you can override only device: to run previews on an idle accelerator:

models:
  asr:
    name: whisper-base
    device: CPU
    preview:
      device: GPU        # name/provider/weight_format inherited from models.asr

A preview pool that resolves to the same model as models.asr is not exported or cached twice.

preview.provider must match models.asr.provider; the two pools share the provider’s model directory and export step, so a mismatch is rejected at startup rather than failing on the first preview request. The preview device is also validated at startup, so an unavailable accelerator is reported there.

Audio filters and the short-input fast path#

Short uploads that are already 16 kHz mono PCM WAV and fit in a single chunk skip ffmpeg entirely, which removes a subprocess launch from the request path.

That fast path is only taken when no audio filter is configured. Both audio_preprocessing.denoise and audio_preprocessing.normalize default to false for this reason; enabling either one sends every segment through ffmpeg again. Enable them when the input audio is noisy or uneven enough that the accuracy gain outweighs the added per-request latency.

  • audio_preprocessing.normalize: true or false (per-chunk loudness normalization)

  • audio_preprocessing.normalize_filter: ffmpeg filter name, default dynaudnorm

dynaudnorm is used rather than loudnorm/EBU R128 because chunks are normalized independently with no shared analysis pass.

Per-request ASR device#

POST /v1/audio/transcriptions accepts an optional multipart form field named device with CPU, GPU, or NPU. When omitted, the endpoint uses models.asr.device. When provided, the service validates the provider/model combination and OpenVINO visibility, then compiles or reuses the model cached for that device. Unsupported or unavailable devices are rejected without falling back to CPU. The VSS-compatible POST /transcriptions endpoint accepts the same per-request device and model_name override/validation (see api-reference.md); the streaming (/v1/audio/transcriptions/stream) and realtime WebSocket endpoints continue to use the configured device only. When diarization is enabled, its independently configured models.diarization.device is not changed by the ASR request override.

The first request for a device can be slower because it loads and compiles the model. Models for previously requested devices remain cached until process exit, which increases memory use when several devices are selected.

OpenVINO NPU Configuration#

Use this config structure:

models:
  asr:
    provider: openvino
    device: NPU

For Docker Compose, ensure:

  • ACCEL_MOUNT_PATH points to the host NPU node (host path is machine-specific; for example /dev/accel/accel0 on many Meteor Lake systems)

  • ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.so remains set in the container environment

Path mapping semantics:

  • Host path (configurable): ACCEL_MOUNT_PATH=<host device node>

  • Container path (fixed): /dev/accel/accel0

Compose mapping in docker-compose.yml:

devices:
  - ${ACCEL_MOUNT_PATH:-/dev/null}:/dev/accel/accel0

This keeps CPU/GPU usage independent of NPU availability:

  • If ACCEL_MOUNT_PATH is set, Compose maps that host device into /dev/accel/accel0.

  • If ACCEL_MOUNT_PATH is not set, Compose maps /dev/null to /dev/accel/accel0 so CPU/GPU workflows still run without a host NPU device.

Verify host node availability and resolved mapping:

ls -l /dev/accel/
docker compose config

Validation performed by the service at startup:

  1. Requested provider/device from config is valid.

  2. Requested OpenVINO device is visible in ov.Core().available_devices inside the running environment.

  3. OpenVINO can compile a probe model on the requested device.

  4. For NPU, initialization of the NPU compiler/runtime stack succeeds.

Provider-specific models.asr fields:

  • weight_format: used by openvino for IR export precision and by whispercpp for model quantization.

  • beam_size, best_of, threads, word_timestamps: used only by whispercpp.

MinIO (External Dependency)#

MinIO is not bundled with Audio Analyzer. It is not defined as a service in docker-compose.yml and is not started, managed, or shipped by this component. When a caller invokes POST /transcriptions with a MinIO source (minio_bucket/video_id/video_name) instead of uploading a file directly, the service downloads that single source audio/video object from the bucket, transcribes it locally, and uploads the resulting transcript back into the same bucket. Only the source object and the final transcript object move through MinIO — internal ASR chunking (audio_preprocessing.chunk_duration_sec) happens entirely on local/container storage and is never written to MinIO. See the API Reference for full request/response details.

To use that path, run MinIO as a separate, externally managed service (your own container, Compose stack, or existing deployment) and provide its endpoint/credentials to Audio Analyzer through configuration. Audio Analyzer never starts or bundles MinIO itself.

Config keys (config.yaml):

minio:
  endpoint: ""       # e.g. "minio-server:9000"; empty disables MinIO support
  access_key: ""
  secret_key: ""
  secure: false

Equivalent environment variable overrides (targeted AUDIO_ANALYZER__... overrides, per Load Order):

  • AUDIO_ANALYZER__MINIO__ENDPOINT

  • AUDIO_ANALYZER__MINIO__ACCESS_KEY

  • AUDIO_ANALYZER__MINIO__SECRET_KEY

  • AUDIO_ANALYZER__MINIO__SECURE

Example (do not commit real credentials; use a local .env file or your secret-management mechanism):

AUDIO_ANALYZER__MINIO__ENDPOINT=minio-server:9000
AUDIO_ANALYZER__MINIO__ACCESS_KEY=<your-access-key>
AUDIO_ANALYZER__MINIO__SECRET_KEY=<your-secret-key>
AUDIO_ANALYZER__MINIO__SECURE=false

This form applies directly to standalone runs (python main.py). For Docker Compose, docker-compose.yml only forwards the environment variables it explicitly lists, so setting these in .env alone does not reach the container — see MinIO (External Object Storage) for the Compose-specific options (editing config.yaml directly, or adding these variables under services.audio-analyzer.environment).

If minio.endpoint is left empty, MinIO support is disabled and a MinIO source request to POST /transcriptions returns 503.

The Audio Analyzer container must be able to reach the configured MinIO endpoint over the network (for example, the same Docker network or a routable host/port). For container-to-container setups, verify and troubleshoot connectivity as described in Run With Docker Compose.