Ambience Options

Set the current ambience by writing its name into session/ambience.md. The TUI polls this file and crossfades to the matching track.

Music files go in session/audio/. Supported formats: .mp3, .ogg, .wav. When multiple files are listed, one is chosen at random each time the ambience activates.

Requirements

pip install miniaudio yt-dlp

ffmpeg must also be installed on your system.

Fetching New Tracks

Use the music-fetch tool to search YouTube and download tracks:

# Auto-search for a tavern track
python3 tools/music-fetch.py tavern

# Custom query
python3 tools/music-fetch.py "deep fen" "swamp ambience D&D"

# Specific video
python3 tools/music-fetch.py tavern --url "https://youtu.be/..."

# Replace all tracks for an ambience
python3 tools/music-fetch.py tavern --replace

# Preview without downloading
python3 tools/music-fetch.py tavern --dry-run

# Allow tracks longer than 10 minutes
python3 tools/music-fetch.py tavern --allow-long-songs

Sources are recorded in session/ambience_sources.md so tracks can be re-downloaded without keeping audio files in git.

Available Ambiences

Ambience	Files
silence	(stops all music)
calm	calm_01.ogg
combat	combat_01.ogg
dungeon	dungeon_01.ogg, dungeon_02.ogg
forest	forest_01.ogg
tavern	tavern_01.ogg
tension	tension_01.ogg
town	town_01.ogg
wilds	wilds_01.ogg

Usage (DM)

# Switch to forest ambience
echo "forest" > session/ambience.md

# Stop music
echo "silence" > session/ambience.md

Or use the companion CLI shortcut:

python3 tools/ambience.py forest
python3 tools/ambience.py silence

Status Display

The TUI status bar shows the current ambience:

Dillion  ❤ 10  │  42 entries  │  3 todo  │  2026-06-24  │  ♫ tavern

If miniaudio is not installed, the status bar shows a hint and no audio plays.

1.9 KiB Raw Blame History