BEETBRAINZ-REPLAY(1)

💖 BEETBRAINZ-REPLAY 💖

okay bestie, welcome to the beetbrainz-replay(1) manual — section 1, User Commands, she's a little command-line icon and she's here to save your scrobbles ✨

---

🌸 NAME 🌸

beetbrainz-replay — replays all your queued Beetbrainz scrobbles from the local spool directory. like, it literally goes and rescues them 🫶

---

🎀 SYNOPSIS 🎀

beetbrainz-replay

no flags, no args, no drama. just vibes. 💅

---

🦋 DESCRIPTION 🦋

so here's the tea: beetbrainz-replay resubmits scrobbles that beetbrainz(1) already wrote to disk back when ListenBrainz was unavailable. she kept receipts, and now she's mailing them in.

Those scrobbles live as append-only JSON Lines (.jsonl) files inside the spool directory. every single line is a complete ListenBrainz payload, exactly as it would have been submitted. no editing, no remixing, the original thing fr fr. ✨

The replay command reads those files and tries to resubmit the scrobbles to ListenBrainz using the same configuration and authentication tokens as the running beetbrainz service. same fit, same energy. 👑

---

🔥 BEHAVIOR 🔥

Replay has the following properties, and honestly? she ate:

• Processes spool files in chronological order — oldest tea first, no skipping the line ⏳
• Preserves original timestamps (listened_at) — the moment stays the moment 💖
• Skips playing_now entries — we don't do half-finished over here, periodt 🙈
• Deletes spool files only after successful submission — no deleting before the mission is complete, that would be a crime 💀
• Safe to re-run at any time — run her again, run her ten times, she's chill like that 🧚

If ListenBrainz is unavailable during replay, files are left intact and no data is lost. she's not gonna ghost your scrobbles bestie, she's just gonna wait. 🌈

---

⭐ AUTOMATIC REPLAY ⭐

A user-level systemd service and timer are typically provided, because who has the energy to run things manually:

• 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. set it and forget it, main character energy only. 👑

Enable automatic replay with:

systemctl --user enable --now beetbrainz-replay.timer

And if user lingering is enabled via:

loginctl enable-linger <username>

then the replay timer will keep running even when the user is logged out. she does not need you watching. she simply continues. 💅

---

🍓 SPOOL DIRECTORY 🍓

The spool directory is controlled by this environment variable:

• BEETBRAINZ_SPOOL_DIR — the spot where all your spool files hang out. Default: ~/.local/state/beetbrainz/spool

If you don't explicitly set it, the default location is used. that's it, that's the whole vibe check. ✨

---

💜 EXIT STATUS 💜

• 0 — Replay completed successfully, or no spool files were present. (either way, we're thriving 🌸)
• 1 — An error occurred during replay, e.g. a network failure or a submission error. (ngl, not the moment 😭)

---

🌈 SEE ALSO 🌈

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

go read those too, the whole friend group is iconic. iykyk 💖

---

👑 AUTHORS 👑

gbcox — thank you for your service, we are obsessed 🫶

---

and that's the whole page, bestie!! this was the Beetbrainz Documentation for BEETBRAINZ-REPLAY(1), dated March 3, 2026. go drain that backlog. slay. 💅✨🎀🦋