Dejvino a2a6b1cb26 add ambience music system: TUI crossfade, yt-dlp fetch, source tracking

- tools/run.py: pygame.mixer subsystem — polls session/ambience.md,
  crossfades tracks, shows ♫ in status bar
- tools/music-fetch.py: search/download from YouTube via yt-dlp,
  auto-increment filenames, --replace and --dry-run modes
- tools/ambience.py: companion CLI to set ambience state
- session/ambience.md: current ambience state file (DM writes here)
- session/ambience_options.md: ambience → file mapping table
- session/ambience_sources.md: file → YouTube URL tracking for re-download
- session/audio/ added to .gitignore (audio files not tracked in git)

2026-06-24 21:44:18 +02:00

1.8 KiB

Raw Blame History

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 pygame 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

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, forest_02.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 pygame is not installed, the music icon is absent and no audio plays.

1.8 KiB Raw Blame History