# Playlists

Cliamp supports local **TOML playlists** managed from the TUI or CLI, plus **M3U/M3U8/PLS playlists** loaded from files or URLs.

## M3U and PLS Playlists

Load any `.m3u`, `.m3u8`, or `.pls` file, local or remote:

```sh
cliamp ~/radio-stations.m3u
cliamp http://radio.example.com/streams.m3u
cliamp ~/music.m3u https://example.com/live.m3u   # mix local + remote
cliamp ~/radio.pls
```

### EXTINF Metadata

The parser extracts titles and durations from `#EXTINF` lines:

```m3u
#EXTM3U
#EXTINF:180,Radio Station 1
http://station-1.com/stream
#EXTINF:-1,Radio Station 2
http://station-2.com/stream/hd
```

Entries without `#EXTINF` still work. The filename or URL is used as the title instead.

### Relative Paths

Paths in a local M3U file are resolved relative to the M3U file's directory:

```m3u
#EXTINF:240,My Song
../Music/song.mp3
#EXTINF:-1,Live Stream
http://example.com/live
```

If `radio.m3u` is in `~/playlists/`, then `../Music/song.mp3` resolves to `~/Music/song.mp3`.

### Edge Cases Handled

- UTF-8 BOM (common in Windows-created files)
- `\r\n` line endings
- Missing `#EXTM3U` header
- Mixed local and remote entries in the same file
- Other `#` directives (silently skipped)

---

## Local TOML Playlists

Create and manage your own playlists stored as `.toml` files in `~/.config/cliamp/playlists/`.

### File Format

Each playlist is a separate `.toml` file. The filename (minus extension) becomes the playlist name. Empty playlists are kept on disk so they remain visible in the TUI and CLI.

```toml
# ~/.config/cliamp/playlists/radio-stations.toml

[[track]]
path = "http://station-1.com/stream"
title = "Radio Station 1"

[[track]]
path = "http://station-2.com/stream/hd"
title = "Radio Station 2"
artist = "Radio Network"

[[track]]
path = "/home/user/Music/song.mp3"
title = "My Song"
artist = "My Artist"
```

Each `[[track]]` section supports:

| Key | Required | Description |
|-----|----------|-------------|
| `path` | Yes | File path or HTTP URL |
| `title` | Yes | Display title |
| `artist` | No | Artist name |
| `album` | No | Album name |
| `genre` | No | Genre name |
| `year` | No | Release year |
| `track_number` | No | Track number |
| `duration_secs` | No | Duration in seconds |
| `embedded_lyrics` | No | Lyrics copied from local file tags |
| `album_art_url` | No | Cached file URL for embedded album art |
| `bookmark` | No | Bookmark flag |

HTTP/HTTPS paths are automatically treated as streams.

### Podcast / RSS Feed Playlists

You can save podcast RSS feed URLs in a playlist. Add `feed = true` to mark a track as a feed. When played, the feed is resolved into individual episodes instead of being streamed directly.

```toml
# ~/.config/cliamp/playlists/podcasts.toml

[[track]]
path = "https://feeds.simplecast.com/54nAGcIl"
title = "The Daily"
feed = true

[[track]]
path = "https://lexfridman.com/feed/podcast/"
title = "Lex Fridman Podcast"
feed = true
```

Each `[[track]]` with `feed = true` supports:

| Key | Required | Description |
|-----|----------|-------------|
| `path` | Yes | RSS/Atom feed URL |
| `title` | Yes | Display name for the feed |
| `feed` | Yes | Must be `true` to enable feed resolution |

When you select a feed entry, cliamp fetches the RSS feed, extracts all episodes with audio enclosures, and loads them into the playlist. Episode titles and durations (from `<itunes:duration>`) are preserved.

URLs with `.xml`, `.rss`, or `.atom` extensions are also auto-detected as feeds without needing `feed = true`.

### Browsing and Loading Playlists

Running `cliamp` without arguments connects to the built-in radio channel. If Navidrome is configured, it opens the provider browser instead.

To browse your local playlists, press `Esc` or `b` during playback to open the provider browser. Navigate with `Up`/`Down` (or `j`/`k`) and press `Enter` to load a playlist. Tracks replace the current playlist and playback starts immediately. Press `Tab` to jump back to the now-playing playlist without reloading.

If Navidrome is also configured, both sources appear in the same list with provider labels (e.g., `[Navidrome] Jazz`, `[Local Playlists] favorites`).

You can start with CLI files and browse playlists later:

```sh
cliamp song.mp3                    # starts playing, Esc opens browser
```

### Managing Playlists

Press `p` from any view to open the playlist manager:

1. **Browse**: see all playlists with track counts
2. **Filter**: press `/` to incrementally filter the list (works on both the playlists screen and the track screen). `Esc` clears the filter.
3. **Open**: press `Enter` or `→` to view tracks inside a playlist
4. **Add now-playing**: press `a` to add the currently playing track (the footer shows the track name so you know what gets added)
5. **Delete playlist**: press `d` then `y` to confirm deletion
6. **Mark tracks**: open a playlist, press `Space` to mark a track and advance, or `a` to mark or unmark all visible tracks
7. **Move tracks**: press `[` or `]`; the saved playlist is updated immediately
8. **Sort tracks**: press `s` to cycle `track`, `title`, `artist`, `album`, `artist+album`, and `path` sorting
9. **Remove tracks**: press `d` to remove the marked tracks, or the highlighted track when nothing is marked
10. **Undo manager edits**: press `u` after delete, remove, move, or sort
11. **Write tracks elsewhere**: press `w` to copy the marked or highlighted tracks to another playlist; duplicate paths are skipped
12. **Add files**: press `o` from inside a playlist to browse files and add them to that playlist
13. **Play this**: press `Enter` on the track list to start playback at the highlighted track. The rest of the playlist follows.
14. **Play all**: press `p` to start from the top, regardless of cursor position
15. **New playlist**: select "+ New Playlist...", type a name, and press Enter. If you create a playlist while a `/` filter is active, the filter text is pre-filled as the new playlist name.

Tracks with an `album` field are grouped by album with visual separator headers in the playlist manager (album grouping is hidden while a filter is active) and the main player view.

The directory `~/.config/cliamp/playlists/` is created automatically on first use. Removing the last track leaves an empty playlist file; use `d` on the playlist list or `cliamp playlist delete` to delete the playlist itself.

### Writing to Playlists

Press `w` on a track in the main playlist to open the local playlist picker. Pick an existing playlist or choose `+ New Playlist...`. Exact duplicate paths are skipped and reported.

In the file browser, select files with `Space`, select all visible audio files with `a`, then press `w` to write the selection to a playlist instead of loading it into the current queue.

### Command Line Management

Manage local TOML playlists without opening the TUI:

```sh
cliamp playlist list
cliamp playlist create "Name"                    # create an empty playlist
cliamp playlist create "Name" file1 dir/ ...     # create from files/folders
cliamp playlist add "Name" file1 dir/ ...        # append, skipping duplicate paths
cliamp playlist rename "Old" "New"
cliamp playlist dedupe "Name"
cliamp playlist sort "Name" --by artist+album
cliamp playlist doctor                           # report missing local files in all playlists
cliamp playlist doctor "Name" --fix              # prune missing local files
cliamp playlist export "Name" --format m3u -o mix.m3u
cliamp playlist import mix.pls --name "Imported"
cliamp playlist show "Name" --json
cliamp playlist remove "Name" --index 3
cliamp playlist bookmark "Name" --index 3       # toggle bookmark flag
cliamp playlist bookmarks                        # list all bookmarked tracks
cliamp playlist enrich "Name"                    # backfill duration/album metadata
cliamp playlist delete "Name"
```

Sort keys are `track`, `title`, `artist`, `album`, `artist+album`, and `path`.

New playlist names reject path separators and non-portable filename characters. Existing playlist files with older Unix-only names remain readable and writable.

### Creating Playlists Manually

Create the directory and add a `.toml` file:

```sh
mkdir -p ~/.config/cliamp/playlists
```

```toml
# ~/.config/cliamp/playlists/favorites.toml

[[track]]
path = "/home/user/Music/song.mp3"
title = "Great Song"
artist = "Good Artist"

[[track]]
path = "https://radio.example.com/stream"
title = "My Radio"
```

### Controls

**Playlist browser (provider view):**

| Key | Action |
|-----|--------|
| `Up` `Down` / `j` `k` | Navigate playlists |
| `Enter` | Load selected playlist |
| `Tab` | Switch to now-playing playlist |
| `Esc` `b` | Open browser (from playlist view) |

**Playlist manager (`p` key):**

| Key | Action |
|-----|--------|
| `p` / `Esc` | Open/close playlist manager (Esc on tracks screen goes back) |
| `Up` `Down` / `j` `k` | Navigate |
| `/` | Filter playlists or tracks; `Esc` clears |
| `Enter` / `→` | Open playlist (list screen) / Play **highlighted** track (tracks screen) |
| `p` | Play all tracks from the top (tracks screen) |
| `a` | List: add currently playing track. Tracks: mark/unmark all visible tracks |
| `Space` | Mark/unmark track and advance (tracks screen) |
| `s` | Sort tracks, cycling supported sort keys (tracks screen) |
| `w` | Write marked/highlighted tracks, or the current queue from the list screen, to another playlist |
| `o` | Add files to the open playlist (tracks screen) |
| `[` `]` | Move track up/down and save (tracks screen) |
| `d` | Delete playlist (confirms) / Remove marked tracks, or highlighted track if none are marked |
| `u` | Undo the last playlist-manager edit |
| `←` / `Backspace` | Go back from tracks screen to list |