Configuration#
Load Order#
The service loads configuration in this order:
config.yamlEnvironment 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 restartis only reliable if the host edit rewritesconfig.yamlin place (same inode). Most editors,sed -i, andmv-based saves replace the file with a new inode, and Docker’s single-file bind mount keeps pointing at the old (now-detached) inode — sorestartcan silently keep serving the stale config. Usedocker compose up -d --force-recreateafter editingconfig.yamlto guarantee the container picks up the change;restartis 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.envfile to preload before config parsingAUDIO_ANALYZER_SERVER_HOST: host used bypython main.pyAUDIO_ANALYZER_SERVER_PORT: port used bypython 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 settingsaudio_preprocessing: chunk size, silence detection, denoise and loudness-normalization filters, chunk directoryaudio_util: max file size, allowed extensions, upload read chunk sizeminio: external MinIO endpoint/credentials, used only byPOST /transcriptionswhen a MinIO source is supplied instead of a direct file uploadpipeline.delete_chunks_after_use: whether temporary chunks are removed after processingsentiment: enablement, provider, model, device, aggregation settings
Common Values#
models.asr.provider:openai|openvino|whispercpp|funasrmodels.asr.device:CPU|GPU|NPUmodels.asr.weight_format: OpenVINO export precision such asint8,fp16, ornull; forwhispercpp, quantization such asq5,q5_0,q5_1,q8,q8_0,int5,int8, ornullsentiment.enabled:trueorfalsesentiment.provider:openvinoorpytorchsentiment.weight_format: optional OpenVINO export precision such asint8,fp16, ornull
ASR Provider Notes#
openai: usesopenai-whisperto 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 undermodels/openvino/...and supportsCPU,GPU, andNPU(when available and correctly configured).whispercpp: downloads the matching whisper.cppggmlmodel undermodels/whispercpp/...and runs onCPUonly.funasr: loads Paraformer, VAD, and punctuation snapshots from ModelScope; requires the optionalINSTALL_CJK=trueimage 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:CPUonlywhispercpp:CPUonlyfunasr:CPUonlyopenvino: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:trueorfalse(per-chunk loudness normalization)audio_preprocessing.normalize_filter: ffmpeg filter name, defaultdynaudnorm
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_PATHpoints to the host NPU node (host path is machine-specific; for example/dev/accel/accel0on many Meteor Lake systems)ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.soremains 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_PATHis set, Compose maps that host device into/dev/accel/accel0.If
ACCEL_MOUNT_PATHis not set, Compose maps/dev/nullto/dev/accel/accel0so 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:
Requested provider/device from config is valid.
Requested OpenVINO device is visible in
ov.Core().available_devicesinside the running environment.OpenVINO can compile a probe model on the requested device.
For
NPU, initialization of the NPU compiler/runtime stack succeeds.
Provider-specific models.asr fields:
weight_format: used byopenvinofor IR export precision and bywhispercppfor model quantization.beam_size,best_of,threads,word_timestamps: used only bywhispercpp.
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__ENDPOINTAUDIO_ANALYZER__MINIO__ACCESS_KEYAUDIO_ANALYZER__MINIO__SECRET_KEYAUDIO_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.