feat: fade-out on skip/stop/prev, song metadata on keep

- Add fade_step parameter to stream_audio for fast volume ramps
- _fade_and_cancel helper: smooth ~0.8s fade before track switch
- !skip, !stop, !seek now fade out instead of cutting instantly
- !prev command: go back to previous track (10-track history stack)
- !keep fetches title/artist/duration via yt-dlp, stores in bot.state
- !kept displays metadata (title, artist, duration, file size)
- !kept clear also removes stored metadata
- 29 new tests for fade, prev, history, keep metadata

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/CHEATSHEET.md

@@ -549,14 +549,19 @@ HTML stripped on receive, escaped on send. IRC-only commands are no-ops.
 !play <url|playlist>     # Play audio (YouTube, SoundCloud, etc.)
 !play <playlist-url>     # Playlist tracks expanded into queue
 !play classical music    # YouTube search, random pick from top 10
-!stop                    # Stop playback, clear queue
-!skip                    # Skip current track
+!stop                    # Stop playback, clear queue (fades out)
+!skip                    # Skip current track (fades out)
+!prev                    # Go back to previous track (fades out)
+!seek 1:30               # Seek to position (also +30, -30)
 !resume                  # Resume last stopped/skipped track
 !queue                   # Show queue
 !queue <url>             # Add to queue (alias for !play)
 !np                      # Now playing
 !volume                  # Show current volume
 !volume 75               # Set volume (0-100, default 50)
+!keep                    # Keep current file + save metadata
+!kept                    # List kept files with metadata
+!kept clear              # Delete all kept files + metadata
 !duck                    # Show ducking status
 !duck on                 # Enable voice ducking
 !duck off                # Disable voice ducking
@@ -567,7 +572,9 @@ HTML stripped on receive, escaped on send. IRC-only commands are no-ops.
 
 Requires: `yt-dlp`, `ffmpeg`, `libopus` on the host.
 Max 50 tracks in queue. Playlists auto-expand; excess truncated at limit.
-Volume ramps smoothly over ~1s (no abrupt jumps mid-playback).
+Skip/stop/prev/seek fade out smoothly (~0.8s); volume ramps over ~1s.
+`!prev` pops from a 10-track history stack (populated on skip/finish).
+`!keep` fetches title/artist/duration via yt-dlp and stores in `bot.state`.
 `!resume` restores position across restarts (persisted via `bot.state`).
 Auto-resumes on reconnect if channel is silent (waits up to 60s for silence).
 Mumble-only: `!play` replies with error on other adapters, others silently no-op.

docs/USAGE.md

@@ -1618,16 +1618,17 @@ and voice transmission.
 ```
 !play <url|playlist> Play audio or add to queue (playlists expanded)
 !play <query>        Search YouTube, play a random result
-!stop                Stop playback, clear queue
-!skip                Skip current track
+!stop                Stop playback, clear queue (fade-out)
+!skip                Skip current track (fade-out)
+!prev                Go back to the previous track (fade-out)
 !seek <offset>       Seek to position (1:30, 90, +30, -30)
 !resume              Resume last stopped/skipped track from saved position
 !queue               Show queue
 !queue <url>         Add to queue (alias for !play)
 !np                  Now playing
 !volume [0-100]      Get/set volume (persisted across restarts)
-!keep                Keep current track's audio file after playback
-!kept [clear]        List kept files or clear all
+!keep                Keep current track's audio file (with metadata)
+!kept [clear]        List kept files with metadata, or clear all
 !testtone            Play 3-second 440Hz test tone
 ```
 
@@ -1636,7 +1637,8 @@ and voice transmission.
   and one is picked randomly
 - Playlists are expanded into individual tracks; excess tracks are
   truncated at the queue limit
-- Volume changes ramp smoothly over ~1s (no abrupt jumps)
+- `!skip`, `!stop`, `!prev`, and `!seek` fade out smoothly (~0.8s) before
+  switching tracks; volume changes ramp smoothly over ~1s (no abrupt jumps)
 - Default volume: 50%; persisted via `bot.state` across restarts
 - Titles resolved via `yt-dlp --flat-playlist` before playback
 - Audio is downloaded before playback (`data/music/`); files are deleted
@@ -1648,6 +1650,8 @@ and voice transmission.
   other music commands silently no-op
 - Playback runs as an asyncio background task; the bot remains responsive
   to text commands during streaming
+- `!prev` returns to the last-played track; up to 10 tracks are kept in a
+  per-session history stack (populated on skip and natural track completion)
 - `!resume` continues from where playback was interrupted (`!stop`/`!skip`);
   position is persisted via `bot.state` and survives bot restarts
 
@@ -1742,9 +1746,11 @@ file (natural dedup).
 
 - If download fails, playback falls back to streaming (`yt-dlp | ffmpeg`)
 - After a track finishes, the local file is automatically deleted
-- Use `!keep` during playback to preserve the file
-- Use `!kept` to list preserved files and their sizes
-- Use `!kept clear` to delete all preserved files
+- Use `!keep` during playback to preserve the file; metadata (title, artist,
+  duration) is fetched via yt-dlp and stored in `bot.state`
+- Use `!kept` to list preserved files with metadata (title, artist, duration,
+  file size)
+- Use `!kept clear` to delete all preserved files and their metadata
 - On cancel/error, files are not deleted (needed for `!resume`)
 
 ### Extra Mumble Bots