Playlists

cliamp supports local TOML playlists that you manage in the TUI or CLI. It also loads M3U/M3U8/PLS playlists from files and URLs.

M3U and PLS Playlists

Load local or remote .m3u, .m3u8, and .pls files:

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

cliamp reads titles and durations from #EXTINF lines:

#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 also work. cliamp uses the file name or URL as the title.

Relative Paths

cliamp resolves paths in a local M3U file from the M3U file directory:

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

If radio.m3u is in ~/playlists/, cliamp resolves ../Music/song.mp3 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 playlists as .toml files in ~/.config/cliamp/playlists/. The folder follows cliamp config directory resolution: CLIAMP_CONFIG_DIR, then XDG_CONFIG_HOME/cliamp, then HOME/.config/cliamp.

File Format

Each playlist has one .toml file. cliamp automatically reads every file in the playlists/ folder with a .toml extension, case-insensitively. The CLI or a user can create these files. cliamp skips files that it cannot parse. The file name without its extension is the playlist name:

~/.config/cliamp/playlists/
├── radio-stations.toml   → playlist "radio-stations"
├── music.toml            → playlist "music"
└── gym.toml              → playlist "gym"

Use one file for each collection. You can use files that you create and files that the CLI creates. cliamp keeps empty playlists on disk so they remain visible in the TUI and CLI.

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

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

[[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 these keys:

Key	Required	Description
`path`	Yes	File path or HTTP URL
`title`	Yes	Title to display
`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
`realtime`	No	Treat an HTTP URL as live radio. Reconnect after pause or disconnect.
`embedded_lyrics`	No	Lyrics from local file tags
`album_art_url`	No	Cached file URL for embedded album art
`bookmark`	No	Bookmark flag

cliamp treats HTTP/HTTPS paths as streams. Set realtime = true for live radio. cliamp keeps this flag when it saves the playlist.

Directory Sources (`[[dir]]`)

Instead of listing each file, reference a directory in a playlist. cliamp scans the directory for audio files each time it loads the playlist. New files appear automatically. Removed files no longer appear:

# ~/.config/cliamp/playlists/music.toml

[[dir]]
path = "~/Music"

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

Each [[dir]] section supports these keys:

Key	Required	Description
`path`	Yes	Directory path. cliamp expands `~` and environment variables.
`recursive`	No	Also scan subdirectories (default `true`)

cliamp returns directory tracks in document order and sorts each directory by path. An explicit [[track]] with the same path overrides a directory scan. Use this to save a bookmark or custom metadata for a file. When you bookmark a directory track with TUI f or cliamp playlist bookmark, cliamp writes an explicit [[track]] entry so the bookmark remains. Unreadable or missing directories add no tracks.

Use --dir to create or extend these playlists on the CLI:

cliamp playlist create "Music" --dir ~/Music
cliamp playlist add "Music" --dir ~/Downloads/live
cliamp playlist dirs "Music"               # list referenced directories

Do not combine --dir with --ssh. The CLI and TUI refuse to remove a directory track because the directory source owns it. Delete the file from the directory or edit the [[dir]] section instead.

Adding Files and Directories

A playlist file can contain any number of [[track]] and [[dir]] sections. Mix them as needed. This mix.toml has two directory sources, two absolute file paths, and a stream URL:

# ~/.config/cliamp/playlists/mix.toml

[[dir]]
path = "~/Music"

[[track]]
path = "/home/user/Downloads/live-set.mp3"
title = "Live Set"

[[dir]]
path = "~/Downloads/podcasts"
recursive = false

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

You can also use many files. Each .toml file in the playlists/ folder is a separate playlist:

# ~/.config/cliamp/playlists/gym.toml

[[dir]]
path = "~/Music/gym"

[[track]]
path = "/home/user/Documents/warmup.mp3"
title = "Warmup"

# ~/.config/cliamp/playlists/chill.toml

[[track]]
path = "/home/user/Downloads/chill-lofi.mp3"
title = "Lofi"

Build the same playlists on the command line without editing files. Positional paths become [[track]] entries. --dir stores a directory reference that cliamp scans on every load:

cliamp playlist create "mix" ~/Downloads/live-set.mp3 --dir ~/Music --dir ~/Downloads/podcasts
cliamp playlist create "gym" ~/Documents/warmup.mp3 --dir ~/Music/gym
cliamp playlist create "chill" ~/Downloads/chill-lofi.mp3

Add more files and directories to an existing playlist:

cliamp playlist add "mix" another-track.mp3 --dir ~/Downloads/live

recursive = false has no CLI flag. Set it in the playlist [[dir]] section.

Podcast / RSS Feed Playlists

Save podcast RSS feed URLs in a playlist. Set feed = true to mark a track as a feed. When you play it, cliamp resolves the feed into individual episodes. It does not stream the feed directly.

# ~/.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 these keys:

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. It extracts episodes with audio enclosures and loads them into the playlist. It keeps episode titles and durations from <itunes:duration>.

cliamp also detects URLs with .xml, .rss, or .atom extensions as feeds. You do not need feed = true for these URLs.

Browsing and Loading Playlists

Run cliamp without arguments to connect to the built-in radio channel. If you configure Navidrome, cliamp opens the provider browser instead.

To browse local playlists, press Esc or b during playback to open the provider browser. Use Up/Down or j/k to navigate. Press Enter to load a playlist. Its tracks replace the current playlist and start playback. Press Tab to return to the now-playing playlist without loading it again.

If you also configure Navidrome, both sources appear in one list with provider labels, such as [Navidrome] Jazz and [Local Playlists] favorites.

You can start with CLI files and browse playlists later:

cliamp song.mp3                    # starts playing, Esc opens browser

Managing Playlists

Press p in any view to open the playlist manager:

Browse: View all playlists and their track counts.
Filter: Press / to filter the list as you type. This works on the playlists and tracks screens. Esc clears the filter.
Open: Press Enter or → to view playlist tracks.
Create playlist: Press a, enter a name, and press Enter. The file browser opens at ~ for the new playlist. Use Space to select folders or files. Folders become live [[dir]] sources. Press Enter to confirm or Esc to finish.
Rename playlist: Press r on the list screen.
Delete playlist: Press d, then y to confirm.
Mark tracks: Open a playlist. Press Space to mark a track and advance, or a to mark or unmark all visible tracks.
Move tracks: Press [ or ]. cliamp saves the playlist immediately.
Sort tracks: Press s to cycle track, title, artist, album, artist+album, and path.
Remove tracks: Press d to remove marked tracks, or the selected track when none are marked.
Undo manager edits: Press u after delete, remove, move, or sort.
Write tracks elsewhere: Press w to copy marked or selected tracks to another playlist. cliamp skips duplicate paths.
Add files: Press o inside a playlist to browse and add files to it.
Play this: Press Enter in the track list to start at the selected track. The rest of the playlist follows.
Play all: Press p to start from the top, regardless of cursor position.
New playlist: Select "+ New Playlist...", enter a name, and press Enter. The file browser opens so you can add tracks immediately. If a / filter is active, cliamp fills the new playlist name with the filter text.

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

cliamp creates ~/.config/cliamp/playlists/ on first use. Removing the last track leaves an empty playlist file. Use d in the playlist list or cliamp playlist delete to delete the playlist.

Writing to Playlists

Press w on a track in the main playlist to open the local playlist picker. Select an existing playlist or + New Playlist.... cliamp skips and reports exact duplicate paths.

In the file browser, use Space to select files. Use a to select all visible audio files. 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:

cliamp playlist list
cliamp playlist create "Name"                    # create an empty playlist
cliamp playlist create "Name" file1 dir/ ...     # create from files/folders
cliamp playlist create "Name" --dir ~/Music      # reference a directory dynamically
cliamp playlist add "Name" file1 dir/ ...        # append, skipping duplicate paths
cliamp playlist add "Name" --dir ~/Music         # add another directory source
cliamp playlist dirs "Name"                      # list directory sources
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"

Use track, title, artist, album, artist+album, or path as sort keys.

New playlist names reject path separators and non-portable file name characters. cliamp can still read and write existing playlist files with older Unix-only names.

Creating Playlists Manually

Create the directory, then add a .toml file:

mkdir -p ~/.config/cliamp/playlists

# ~/.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 the selected playlist
`Tab`	Switch to the now-playing playlist
`Esc` `b`	Open browser (from playlist view)

Playlist manager (p key):

Key	Action
`p` / `Esc`	Open or close the playlist manager. `Esc` on the tracks screen goes back.
`Up` `Down` / `j` `k`	Navigate
`/`	Filter playlists or tracks; `Esc` clears
`Enter` / `→`	List screen: open a playlist. Tracks screen: play the selected track.
`p`	Play all tracks from the top (tracks screen)
`a`	List: create a playlist. After naming it, the file browser opens at `~`. Use `Space` to select folders or files and `Esc` to finish. Tracks: mark or unmark all visible tracks.
`r`	Rename the highlighted playlist (list screen; `Recently Played` cannot be renamed)
`Space`	Mark/unmark track and advance (tracks screen)
`s`	Cycle supported sort keys (tracks screen)
`w`	Write marked or selected tracks to another playlist. On the list screen, write the current queue.
`o`	Add files to the open playlist (tracks screen)
`D`	List: open the file browser to add `[[dir]]` sources to the selected playlist. Tracks: open the directory-sources screen for the open playlist.
`[` `]`	Move track up/down and save (tracks screen)
`d`	Delete a playlist after confirmation. `Recently Played` cannot be deleted. In tracks, remove marked tracks or the selected track if none are marked.
`u`	Undo the last playlist-manager edit
`←` / `Backspace`	Go back from tracks screen to list

The playlist list marks playlists with [[dir]] sources with a · N dir(s) indicator next to the track count.

Directory sources screen (tracks screen, D):

Key	Action
`Up` `Down` / `j` `k`	Navigate directory sources
`a`	Open the file browser to add a directory as a `[[dir]]` source
`d` then `y`	Remove the selected source. Confirm with `y`; any other key cancels.
`r`	Toggle `recursive` on the selected source. cliamp scans it again immediately.
`←` / `Backspace` / `Esc`	Back to the tracks screen

In the file browser, press D to add selected directories as live [[dir]] sources instead of expanding them into explicit tracks. If none are selected, cliamp adds the selected directory or the directory that you are browsing. This browser mode starts with a above, o from the tracks screen, or D from the list screen. cliamp skips and reports directories that are already referenced.

Favorites

Press n on a track in the track list to toggle its favorite state. cliamp collects favorited tracks in the virtual "Favorites" playlist. This playlist always appears at the top of the playlist list, even when empty and regardless of the source playlist.

Favorites apply across playlists. A track that you favorite in "gym" appears in "Favorites", and the reverse is also true. ~/.config/cliamp/favorites.toml stores the "Favorites" playlist. Like "Recently Played", it is a virtual playlist that you cannot rename, delete, or change in the playlist manager. Use n again to remove a favorite.

Favorited tracks show a small red ♥ marker in the track list. The bookmark system is separate: it uses the f key and ★ marker. Bookmarks apply to one playlist. Favorites apply to all playlists.