Sessions

Fadenza has one saved document, and it is the queue you are listening to. There is no library database and no cache that matters.

What comes back

Quit and reopen, and you get:

• The queue, in order
• The current track and whatever you had selected
• The playback position, to the second
• Repeat mode
• Shuffle: whether it is on, and the exact order it generated
• Volume, and mute as its own state
• Your output device preference
• Watched folders, including the tracks you dismissed from them

Playback resumes paused. Fadenza never starts making noise because you opened it. The position is set, the track is loaded, and it waits.

The shuffle order is saved rather than regenerated, which is why a restored session continues the same sequence instead of reshuffling. It is also what makes the behaviour testable, which is the reason it works.

Where it lives

~/Library/Application Support/com.ray.Fadenza/session.json

It is written about a second after you stop changing things — a drag that fires twenty events produces one write — and flushed immediately when you quit. Writes are atomic, so a crash halfway through cannot leave you with half a queue.

What is not saved

• Anything transient: buffering state, error banners, in-flight work.
• Decoded artwork, which is cached in memory and rebuilt on demand.
• The remote API token. That lives in the Keychain and appears in neither the session file nor the logs.

File access after a restart

macOS sandboxing means an app cannot simply reopen a file by path after a restart; it has to save a token for each file or folder you granted it. Fadenza saves those tokens alongside the queue and resolves them on launch.

If one no longer resolves — you moved the file, or the permission went stale — the track is marked missing and kept in the queue, with an offer to reopen the file panel so you can grant access again. It is not removed, and you are not left guessing which track disappeared.

If the file breaks

A session file that cannot be read is moved aside, never deleted:

session-corrupt-1.json

Up to three are kept. Fadenza then launches with an empty queue and a banner telling you what happened and where the file went.

Keeping it matters twice over: the queue may be recoverable by hand, and a bug report with the file attached is worth far more than one without it.

Upgrades

The session file carries a version. Every version bump ships with a migration from the previous one and a test that runs it against a real file from that version — including versions older than the last. A migration that quietly dropped a field would turn into a queue that quietly loses tracks, which is the one thing this app is built not to do.