Media sessions and recovery

The host-neutral session model separates editable document state from runtime playback state. Use the SDK’s pointer-free snapshots and media references for persistence and handoff; do not treat an audio callback, an open file handle, or an active voice as durable session state.

Persist identity and sample-domain state

SessionGraphSnapshot is the persistence shape for graph edits. It carries a schema version, stable session identity, revision, tempo, render rate and bit depth, session range, tracks, clips, and clip assignments. Its time values are canonical sample-domain values at render_sample_rate_hz. Runtime transport, scene-trigger, marker, and playlist state are explicitly outside this transactional edit domain.

Stable IDs are serialized as raw values and are intended to survive processes and sessions. Keep the allocator watermark above every restored ID when rebuilding a document. A media reference should remain relative to a caller-supplied media root; do not persist an absolute path as the media identity.

Source: session_graph.h and identity.h.

Hash off the realtime path

A MediaReference can carry an optional SHA-256 fingerprint and an explicit optional/required verification policy. Hashing is background-thread work: sha256File() performs file I/O and cryptographic work and is not an audio-thread operation. Resolution rejects absolute paths and parent traversal, then reports a distinct result such as Verified, ResolvedUnverified, Missing, HashMismatch, InvalidReference, or ReadError.

Only Verified and ResolvedUnverified are usable by the resolver’s safe default. A hash mismatch is never silently usable; any explicit override is host policy outside the resolver. Keep fingerprint calculation, media relinking, and reader opening on a control or background thread before source preparation.

Source: media_integrity.h.

Use transactions for edit recovery

Begin a SessionGraph transaction before a multi-field document edit. The transaction snapshots the graph and records its base revision. Apply the related changes, then:

• call commit() once the complete edit is valid; inspect the returned SessionGraphChangeSet and its base/new revisions;
• call rollback() when validation or an external precondition fails; rollback restores the transaction’s pre-edit state;
• do not mix runtime transport or callback state into the transaction, because that state is deliberately excluded from the edit domain;
• use snapshot() for undo/redo, persistence, or cross-thread transfer, and restore() only with a validated snapshot.

The change set identifies the revision before the edit, the revision after it, and the categories changed. An empty change set means no graph mutation was recorded. This gives a host an observable revision boundary without requiring the SDK to choose an undo-stack or autosave policy.

Source: session_graph.h and session_graph.h.

Distinguish future schema from damaged data

A stored snapshot exposes schema_version; JSON parsing separately exposes structural expectations through object/array/type and required-field helpers. Preserve this distinction in recovery UX:

• Future schema: the payload is structurally readable but declares a schema version newer than the reader understands. Keep the original bytes, report that the installed SDK cannot interpret the version, and do not silently downgrade or partially restore it.
• Corrupt or malformed data: parsing fails, a required field has the wrong type, or a value violates the snapshot’s invariants. Keep the original bytes, report the malformed payload, and leave the live graph unchanged.
• Media resolution failure: the session document is readable, but a referenced file is missing, unreadable, or fails fingerprint verification. Preserve the graph and expose the media resolution status separately from document recovery.

The public graph API provides the schema-bearing snapshot and transactional restore primitives; it does not prescribe an autosave format, migration policy, or user-facing recovery dialog. Those decisions belong to the host. Never turn an unknown schema into an apparently valid empty session.

Source: session_graph.h, json.hpp, and errors.h.