Playback engine state machine

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : play(source)
    Loading --> Playing : stream resolved
    Loading --> Error : plugin error / fetch failure
    Loading --> Idle : stop()

    Playing --> Paused : pause()
    Playing --> Seeking : seek(pos)
    Playing --> Loading : track end / advance()
    Playing --> Idle : stop()
    Playing --> Error : decode failure / device lost

    Paused --> Playing : resume()
    Paused --> Idle : stop()
    Paused --> Seeking : seek(pos)

    Seeking --> Playing : seek complete
    Seeking --> Error : seek failure

    Error --> Loading : advance() (next track)
    Error --> Idle : stop()
    Error --> Idle : queue empty

    note right of Seeking
        Seeking is async on some backends
        (byte-range request must complete).
        Suppress duplicate seek commands
        during a pending seek.
    end note

Transitions

From	To	Trigger	Notes
Idle	Loading	`play(source)`	Engine resolving stream URL, beginning fetch
Loading	Playing	Stream resolved	Audio buffer ready, phonic started
Loading	Error	Plugin error / HTTP failure	`stream()` fails or URL fetch returns 404/DNS/timeout
Loading	Idle	`stop()`	User cancels before playback starts
Playing	Paused	`pause()`	phonic pauses output
Playing	Seeking	`seek(pos)`	phonic seeks to position
Playing	Loading	Track end / `advance()`	Auto-advance to next queue item
Playing	Idle	`stop()`	User stops playback
Playing	Error	Decode failure / device lost	phonic error, audio device disconnected
Paused	Playing	`resume()`	phonic resumes from pause position
Paused	Idle	`stop()`	User stops from paused
Paused	Seeking	`seek(pos)`	Seek while paused
Seeking	Playing	Seek complete	phonic reports seek done
Seeking	Error	Seek failure	Seek position out of range, device error
Error	Loading	`advance()`	Auto-advance to next track
Error	Idle	`stop()`	User dismisses error
Error	Idle	Queue empty	No more items to try

References

ADR-004 (phonic audio backend)
FR-CORE-1 (source-agnostic playback)