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 on docker compose restart.

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 settings, 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

  • 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 and downloads PyTorch Whisper weights on first use.

  • 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.

ASR Provider/Device Matrix#

  • openai: CPU only

  • whispercpp: CPU only

  • openvino: CPU | GPU | NPU

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

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.