Handle stream/clear internally

[kahrendt]

Fixes a bug where stream/clear always assumed a stream/start message would follow. stream/clear messages are now handled internally by the player role. It adds a marker to the ring buffer queue, and then the sync task clears all chunks up to that marker. It does not break out of the inner loop, so the next new chunk will get synchronized using the current sync algorithm (with the hard_sync flag automatically set so it uses a stricter bound for correction).

There is one flaw with this design: it does not clear data already written out to the user provided buffer, so any pending audio will still play before starting with the new audio. This requires exposing more details to the library user, as the library itself has no control over that buffer. I have a longer-term plan to introduce this to the library. Note that in ESPHome, this is also the current behavior when stream/clear and stream/end are paired together, as the current speaker_source media player always waits until all data is played before, so this is not a regression on that platform. I'm tracking this in #55

This is a breaking change, because this PR removes the on_stream_clear function from the PlayerRoleListener class.

[Copilot]

Pull request overview

This PR changes how stream/clear is handled for the player pipeline: instead of treating it like a stream lifecycle event (and assuming a subsequent stream/start), it is now treated as an in-stream seek handled internally by the sync task using an encoded ring-buffer marker.

Changes:

• Add CHUNK_TYPE_STREAM_CLEAR_MARKER and update the sync task to discard buffered chunks up to this marker, then resume decoding with hard-sync behavior.
• Remove PlayerRoleListener::on_stream_clear() and the internal STREAM_CLEAR player callback type; update examples and docs accordingly.
• Update internal documentation to reflect the new seek-style handling of stream/clear.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/sync_task.h	Documents new seek semantics and adds helper method declarations for seek handling.
src/sync_task.cpp	Implements discard-to-marker logic and post-seek state adjustments in the sync loop.
src/player_role.cpp	On stream/clear, signals the sync task and enqueues a clear-marker chunk (no listener callback).
src/player_role_impl.h	Removes STREAM_CLEAR from the player event enum.
src/audio_types.h	Introduces CHUNK_TYPE_STREAM_CLEAR_MARKER.
include/sendspin/player_role.h	Removes on_stream_clear() from the public listener API and updates thread-safety docs.
examples/tui_client/main.cpp	Removes the on_stream_clear() override usage.
examples/basic_client/main.cpp	Removes the on_stream_clear() override usage.
docs/internals.md	Updates internal design documentation for seek-style stream/clear.
docs/integration-guide.md	Removes guidance/code for implementing on_stream_clear().

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.