Logging rules
The rules that decide which plays become history entries, how an entry is committed and closed, and when a session goes idle.
These rules decide which plays reach the XSPF, when an entry is committed and closed, and when a session goes idle. The thresholds are settings: see Library & settings.
What gets logged
| Source | Logged? | Notes |
|---|---|---|
| Deck play (any deck 0…N−1) | Yes | After volume + duration gates |
| Same track played again in one session | Yes | Always append; no dedup |
| Sampler pad press / hold / loop | No | Even if routed through a deck channel |
| Preview / headphone (PFL) only | No | Does not affect idle timer or logging |
| Track loaded but never played | No | Must enter qualifying play state |
The qualifying-play gate
Effective output level (per deck):
effective = deck.volume × crossfader_gain(deck)
| Input | Source |
|---|---|
deck.volume |
Deck channel fader (DeckUpdated.volume, 0.0–1.0) |
crossfader_gain(deck) |
Equal-power crossfader (EngineStatus.crossfader) scaled by the deck’s assignment: side A → cos(xf × π/2), side B → sin(xf × π/2), Thru → 1.0 |
Gain trim and master volume are not included.
Qualifying play state (per deck):
playing == true
AND track loaded
AND effective >= history_min_deck_volume
Default history_min_deck_volume is 0.05 (5% of post-crossfader level).
Entry lifecycle
- Open: the deck enters qualifying play state → record
started_at(UTC) and start the duration timer. - Commit: the deck stays qualifying for
history_min_play_seconds(default 5) → append<track>to the XSPF with a metadata snapshot. - Close: the deck leaves qualifying play state (pause, stop, unload, or
effectivebelow threshold). Setended_at(UTC) on the committed entry and rewrite the XSPF entry extension. - Discard: qualifying state ends before
history_min_play_secondselapses → no entry is written.
Per-entry fields:
| Field | When set |
|---|---|
started_at |
Qualifying state begins |
ended_at |
Qualifying state ends (or session close while still qualifying) |
played_duration_ms |
ended_at − started_at (computed) |
deck_id |
0-based deck index |
track_id |
Library id when available |
location |
File URI for XSPF <location> |
title, creator, album, duration |
Snapshot at commit time |
bpm, key, isrc |
Snapshot at commit time |
Multiple decks may have overlapping entries (simultaneous play on 2+ decks).
Open entries at session close
When a session closes (idle timeout, manual new session, or app exit):
- Any committed entry without
ended_atgetsended_at = close time. - Pending entries that never reached
history_min_play_secondsare discarded.
Active output and the idle timer
For session idle detection, a deck is actively outputting when it is in qualifying play state.
Not considered:
- Sampler activity.
- Preview / PFL bus.
- Master volume or headphone cue toggles (crossfader is included via the effective-output formula above).
When no deck is actively outputting, the idle clock runs. If idle exceeds history_session_idle_minutes, the session closes. The next qualifying play starts a new session (unless restored).
Engine hook
History listens to the engine event bus (DeckUpdated, EngineStatus for crossfader, and related), not Flutter widgets. host-flutter runs HistoryWorker (subscribes to engine events, periodic tick) and delegates persistence to library::history (HistoryRecorder, XSPF, session index, export).
Sampler commands (SamplerPadPress, AssignSamplerTrack, …) are ignored.