Specification updates

[kahrendt]

This PR introduces significant breaking changes to the Resonate protocol, fundamentally restructuring how clients, groups, and streams are managed. Having proven the underlying technical basis for the protocol is sound, these changes establish a more consistent data model and build a flexible architecture for future improvements. It also lays the groundwork for supporting visualizer clients.

Unresolved Questions

• Server -> client volume/mute messages were removed and need replacing. How should these messages be named? (They only should be sent to clients with the player role)
• The group/get-list, group/list, group/join, and group/unjoin message details need further discussion
  • Determine if any client roles need awareness of stream or group IDs
  • If not needed, only send IDs when specifically requested via these messages
• Some server -> client message fields should be conditionally sent based on client role

Breaking Changes

New Architecture Concepts

• Client Roles System: Clients now declare capabilities through roles (player, controller, metadata, visualizer)
• Groups: Proper group definition, where clients belong to exactly one group
• Sessions: Separated from streams - sessions track media/playback state while streams handle encoding

Protocol Message Changes

Added Messages

• stream/start, stream/update, stream/end - Manage client-specific stream encoding
• session/update - Replaces metadata updates with session-scoped information
• group/update, group/command - Group state and controls
• player/update - Player state reporting
• stream/request-format - Dynamic format changes

Removed Messages

• session/start, session/end - Replaced by stream messages
• metadata/update - Replaced by session/update
• stream/command - Replaced by group/command
• player/state - Replaced by player/update
• volume/set, mute/set - Now handled through group commands in the client -> server direction. They need replacement in the server -> client direction.

Modified Messages

• client/hello - Restructured to support multiple roles and capability declarations
• Binary messages - Added timestamps for synchronization; expanded to include visualization data

Key Improvements

Synchronization

• All binary messages include synchronized timestamps

Flexibility

• Per-client encoding based on capabilities and network conditions
• Dynamic format changes during playback

Protocol Clarifications

• Continuous clock synchronization via client/time messages
• Client-side synchronization with interpolation for drift compensation
• Support for heterogeneous devices within the same group

Documentation Clarity

• Comprehensive field descriptions with optional field notation (?)
• Clearer state management descriptions for groups, sessions, and streams
• Improved mermaid sequence diagram showing interaction flow
• Consistent message structure and naming conventions