# 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: ```bash 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](../get-started.md#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: ```yaml 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](../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: ```yaml 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=` - Container path (fixed): `/dev/accel/accel0` Compose mapping in `docker-compose.yml`: ```yaml 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: ```bash 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](../api-reference.md) 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`): ```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](#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): ```bash AUDIO_ANALYZER__MINIO__ENDPOINT=minio-server:9000 AUDIO_ANALYZER__MINIO__ACCESS_KEY= AUDIO_ANALYZER__MINIO__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)](./run-container.md#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](./run-container.md#minio-external-object-storage).