-rpi-sendspin/third_party/sendspin-go/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.9.0] - 2025-10-25

Added

Library-First Architecture

• Complete restructure from CLI-focused to library-first design
• Three-tier architecture: high-level convenience API, component APIs, and private implementation
• Comprehensive public API in pkg/ for library consumers
• CLI tools reimplemented as thin wrappers using the public library

Public API Packages

• pkg/sendspin - High-level Player and Server APIs for most use cases

  • Player - Connect to servers and play synchronized audio with volume control, callbacks
  • Server - Serve audio to multiple clients with custom source support
  • AudioSource - Interface for custom audio sources
  • FileSource() - Read audio from FLAC, MP3, WAV files
  • TestToneSource() - Generate test tones for debugging

• pkg/audio - Core audio types and utilities

  • Format - Audio stream format descriptor (codec, sample rate, channels, bit depth)
  • Buffer - Decoded PCM audio with timestamp information
  • Sample conversion functions for 16-bit and 24-bit audio

• pkg/audio/decode - Audio decoders for multiple codecs

  • Decoder - Common interface for all decoders
  • PCM decoder - 16-bit and 24-bit support
  • Opus decoder - with int16 to int32 conversion
  • FLAC decoder - stub for future implementation
  • MP3 decoder - with int16 to int32 conversion

• pkg/audio/encode - Audio encoders

  • Encoder - Common interface for all encoders
  • PCM encoder - 16-bit and 24-bit support
  • Opus encoder - with int32 to int16 conversion

• pkg/audio/resample - Sample rate conversion

  • Linear interpolation resampler
  • Support for upsampling and downsampling
  • Multi-channel support

• pkg/audio/output - Audio playback interfaces

  • Output - Common interface for playback backends
  • PortAudio implementation for cross-platform audio

• pkg/protocol - Sendspin wire protocol

  • Message types for client/server communication
  • WebSocket client implementation
  • Protocol version negotiation

• pkg/sync - Clock synchronization

  • NTP-style clock sync with Sendspin servers
  • Round-trip time measurement
  • Quality tracking for sync accuracy

• pkg/discovery - mDNS service discovery

  • Discover Sendspin servers on local network
  • Advertise server availability
  • Service registration and browsing

Examples

• examples/basic-player - Simple audio player example
• examples/basic-server - Simple audio server example
• examples/custom-source - Custom audio source implementation

Documentation

• Comprehensive godoc comments for all public types and functions
• Package-level documentation for each public package
• Examples in README demonstrating library usage
• Complete refactoring design document

Testing

• 180+ tests covering all public APIs
• Integration tests for Player and Server
• Unit tests for audio processing components
• Codec-specific tests for encoders and decoders

Changed

Breaking Changes

• CLI tools now use public library APIs instead of internal implementations
• Internal packages moved to pkg/ for public consumption
• Audio processing now consistently uses int32 samples in 24-bit range

Architecture

• Player CLI (sendspin-player) - Thin wrapper around pkg/sendspin.Player
• Server CLI (sendspin-server) - Thin wrapper around pkg/sendspin.Server
• All audio processing moved to reusable public packages
• Clean separation between library code and CLI code

Fixed

• Consistent sample format across all audio processing components
• Proper resource cleanup in decoders and encoders
• Thread-safe clock synchronization
• Robust error handling in all public APIs

Technical Details

Audio Pipeline

• All decoders output int32 samples in 24-bit range for consistent hi-res audio
• All encoders accept int32 samples and convert as needed for codec
• Resampler uses linear interpolation for quality upsampling/downsampling
• PortAudio output converts int32 to int16 for playback

Wire Protocol

• WebSocket-based streaming with binary audio frames
• Clock sync messages for precise timing
• Metadata messages for track information
• Client state messages for monitoring

Clock Synchronization

• NTP-style round-trip time measurement
• Multiple sync samples for accuracy
• Quality tracking and bad sample rejection
• Thread-safe concurrent access

Service Discovery

• mDNS-based server discovery
• Automatic service registration
• Server name and capability advertising

Migration Guide

For users of pre-1.0.0 versions, the library API is now the recommended way to use Sendspin:

Old (Internal API):

// Not recommended - internal packages
import "github.com/Sendspin/sendspin-go/internal/player"

New (Public API):

// Recommended - public library API
import "github.com/Sendspin/sendspin-go/pkg/sendspin"

player, err := sendspin.NewPlayer(sendspin.PlayerConfig{
    ServerAddr: "localhost:8927",
    PlayerName: "Living Room",
    Volume:     80,
})

Version Information

• Go 1.23+
• Supports hi-res audio up to 192kHz/24-bit
• Cross-platform: macOS, Linux, Windows
• Architecture: x86_64, ARM64

---

[0.3.0] - 2025-10-24

Added

• Hi-res audio support up to 192kHz/24-bit
• Multi-source audio support
• Server TUI with real-time client monitoring
• Comprehensive server and player documentation

Fixed

• Audio timing and distortion issues
• Buffer management improvements
• Clock synchronization accuracy

---

[0.2.0] - 2025-10-20

Added

• Basic player and server functionality
• Clock synchronization
• mDNS discovery
• TUI for player

Changed

• Initial implementation

---

[0.1.0] - 2025-10-15

Added

• Initial project structure
• Basic audio streaming
• WebSocket protocol