Overview
What a history session records, when it opens and closes, where it is stored, and which page covers each part.
Mixar records what was played, on which deck, when it started, and when it ended during a performance session. Each session is persisted as a live-updated XSPF file under app support storage. Re-playing the same track in one set appends a new entry. Sampler playback is never logged. All main deck channels are logged: 2 today, 4 in Phase 5.
A play is logged only after minimum effective output and minimum play duration thresholds are met (both configurable). Effective output combines deck channel fader and crossfader gain. Preview (PFL) is ignored. The logging rules give the exact conditions.
Session boundaries
- Idle split: when no deck meets the “active output” condition for longer than
history_session_idle_minutes(default 5), the session closes. - Manual: the user can start a new session, or resume the previous one while no successor session exists yet. See Manual session control.
On app restart, if the last session is still inside the idle window, the user is prompted to restore it or start fresh. Sessions covers the lifecycle, the file identity, and the restart behavior.
History is Phase 5 library/workflow polish, adjacent to collections and export. It is not a deck performance control.
Data flow and ownership
Engine ──► DeckUpdated evt ──► History recorder
│
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
history/*.xspf history_sessions HistorySessionUpdated evt
│ │
└──────────► LibraryTransport / Flutter UI ◄──────┘
| Layer | Responsibility |
|---|---|
host-flutter (HistoryWorker) |
Engine evt subscription, qualifying-play tick, FRB list/get/export/rename/manual session |
library::history |
Qualifying-play gates, idle timeout, XSPF R/W, session index, derived export |
library |
Session merge/join, save-as-playlist |
gui-flutter |
History browser, restore prompt, settings |
Use LibraryTransport (or HistoryTransport if the API grows). No raw FRB from widgets.
Where sessions are stored
Sessions live under app support storage. The storage page gives the exact path, the XSPF layout, the history_sessions index, the write sequence, and the ISRC snapshots.
Pages
- Logging rules: which plays become entries, the gates and timing, the per-entry fields, and the idle timer.
- Sessions: lifecycle, file identity, restart handling, and the manual new/resume controls.
- Storage & metadata: the XSPF format, the session index in
library.db, write durability, and ISRC. - Library & settings: the History view, the session actions, and the settings keys that drive logging.
- Live output & export: reading the active session from other tools, and the CSV, M3U8, and TXT exports.
References
Formats
| Resource | URL |
|---|---|
| XSPF specification | https://www.xspf.org/ |
This repository
| Resource | Path |
|---|---|
| Collections model | docs/tech-spec.md §5 |
| Engine events | crates/bus-api/src/payload.rs |
| Track entity | crates/library/src/entity/tracks.rs |
| App settings | crates/host-flutter/src/api/settings.rs |
| Phase 5 roadmap | docs/deck-spec.md §10 |
See also GitHub issue #52.