Audio Engine

The AudioEngine is the single writer to Mumble’s audio stream. It owns a track queue, volume controller, DNI lock, and an ffmpeg-based feeder. All audio playback — media, soundboard clips, TTS — flows through this pipeline.

Architecture

TrackQueue

A bounded FIFO deque (maxlen configured in config.toml). Supports push, pop, remove, move, shuffle, and clear operations. When the queue is full, the oldest entry is discarded on push.

VolumeController

Handles volume scaling and ducking. Ducking uses linear interpolation (lerp) driven by the scheduler at a 25ms interval, smoothly lowering volume when users speak and restoring it when they stop.

DniLock (Do-Not-Interrupt)

An ownership token that prevents other plugins from interrupting active playback. The lock is reentrant for the same owner — a plugin that already holds DNI can re-acquire it without blocking. Only one owner can hold the lock at a time.

Feeder

An ffmpeg subprocess reads the audio source, outputs raw PCM chunks, and the feeder converts them to Opus frames for Mumble. On Python 3.13+, the audioop module (removed from stdlib) is imported lazily so the module loads even before the audioop-lts backport is installed.

Events

The engine publishes three events on the event bus:

Event	When
TrackStarted	A new track begins playback.
TrackFinished	The current track ends naturally.
QueueEmpty	The queue has no more tracks (or playback stopped/skipped to empty).

Events are published outside the lock to prevent reentrancy issues.

Do-Not-Interrupt (DNI)

The media and ai_assistant plugins acquire DNI before playing audio to prevent other plugins from cutting in. The engine emits QueueEmpty on stop or when skipping empties the queue, signaling DNI owners to release the lock.

Ducking

When users speak in Mumble, the engine automatically lowers playback volume. This is configurable via the following settings:

Setting	Description
ducking_volume	Target volume while ducking (0.0–1.0).
ducking_threshold	Audio level that triggers ducking.
ducking_start_delay	Delay before ducking activates (seconds).
ducking_end_delay	Delay before volume restores after speech (seconds).

Queue Operations

The following operations are available through audio commands:

play, stop, skip, pause, resume, seek, loop, shuffle, move, remove, clear_queue.