Skip to content

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

  1. Open: the deck enters qualifying play state → record started_at (UTC) and start the duration timer.
  2. Commit: the deck stays qualifying for history_min_play_seconds (default 5) → append <track> to the XSPF with a metadata snapshot.
  3. Close: the deck leaves qualifying play state (pause, stop, unload, or effective below threshold). Set ended_at (UTC) on the committed entry and rewrite the XSPF entry extension.
  4. Discard: qualifying state ends before history_min_play_seconds elapses → 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_at gets ended_at = close time.
  • Pending entries that never reached history_min_play_seconds are 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.