beetbrainz-replay - Man Page

beetbrainz-replay

beetbrainz-replay resubmits scrobbles that were previously written to disk by beetbrainz(1) when ListenBrainz was unavailable.

Scrobbles are stored as append-only JSON Lines (`.jsonl`) files in the spool directory. Each line represents a complete ListenBrainz payload exactly as it would have been submitted.

The replay command reads these files and attempts to resubmit the scrobbles to ListenBrainz using the same configuration and authentication tokens as the running beetbrainz service.

Replay has the following properties:

• Processes spool files in chronological order.
• Preserves original timestamps (`listened_at`).
• Skips `playing_now` entries.
• Deletes spool files only after successful submission.
• Safe to re-run at any time.

If ListenBrainz is unavailable during replay, files are left intact and no data is lost.

A user-level systemd service and timer are typically provided:

• `beetbrainz-replay.service`
• `beetbrainz-replay.timer`

When enabled, the timer periodically executes beetbrainz-replay (typically hourly) and automatically drains any backlog once ListenBrainz becomes reachable again.

Enable automatic replay with:

If user lingering is enabled via:

the replay timer will continue to run even when the user is logged out.

The spool directory is controlled by the environment variable:

BEETBRAINZ_SPOOL_DIR

Default: `~/.local/state/beetbrainz/spool`

If not explicitly set, the default location is used.

0

Replay completed successfully or no spool files were present.

1

An error occurred during replay (e.g., network failure or submission error).

beetbrainz(1), beets(1), systemd(1), systemctl(1)

gbcox