a2a6b1cb26
- 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)
80 lines
1.8 KiB
Markdown
80 lines
1.8 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
|
|
```
|
|
|
|
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.
|