Recently Played

cliamp stores local listening history in ~/.config/cliamp/history.toml. It records a play after you listen to at least 50% of a track. This is the same threshold that Last.fm and the Navidrome scrobbler use. Skipped tracks do not enter the list.

Browsing in the TUI

Open the Local Playlists provider. After cliamp records at least one play, a virtual Recently Played entry appears at the top. Open it like any other playlist. Tracks are newest first. The list is read-only. cliamp rejects bookmark, track removal, and playlist deletion requests with an error.

To clear the list, run cliamp history clear.

CLI

cliamp history                # show the 50 most recent plays
cliamp history --limit 200    # show the 200 most recent
cliamp history --limit 0      # show all (capped at 200 entries on disk)
cliamp history --json         # machine-readable output
cliamp history clear          # wipe the history file

The relative timestamp, such as 3m ago or yesterday, uses local time. The JSON output uses played_at in RFC 3339 UTC for portability.

File format

history.toml uses the same minimal TOML format as cliamp local playlists:

[[entry]]
played_at = "2026-05-06T22:09:11Z"
path = "/home/me/Music/AC-DC/Highway to Hell.flac"
title = "Highway to Hell"
artist = "AC/DC"
album = "Highway to Hell"
year = 1979
duration_secs = 208

The default limit is 200 entries. cliamp removes older plays in FIFO order. Consecutive plays of the same track within 5 minutes update the top entry time instead of adding another entry.

What is not recorded

• Tracks skipped before the 50% threshold.
• Live streams without a known duration, such as radio stations and ICY streams. cliamp cannot detect their 50% point.
• Tracks with empty paths. This is a defensive check.