# 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

```bash
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:

```bash
# 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)

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

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

Or use the companion CLI shortcut:

```bash
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.