83 lines
1.9 KiB
Markdown
83 lines
1.9 KiB
Markdown
# 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
|
|
|
|
# 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)
|
|
|
|
```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.
|