soco 0.1.4

Control Sonos speakers programmatically. Discover devices, manage playback, groups, alarms, and more. Port of Python SoCo library.

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.1.4 - 2025-12-06

Added - 100% API Completeness

All missing API methods have been implemented, achieving 100% feature parity with Python SoCo.

Queue Management

• addToQueue(): Add DidlObject instances directly to the queue (previously only addUriToQueue() was available)
• addMultipleToQueue(): Batch queue addition for multiple items (up to 16 items per request, more efficient than individual calls)

Convenience Wrappers (API Compatibility)

• dialogLevel / setDialogLevel(): Convenience wrapper for dialogMode to match raw Sonos API
• musicSurroundLevel / setMusicSurroundLevel(): Convenience wrapper for surroundVolumeMusic
• surroundLevel / setSurroundLevel(): Convenience wrapper for surroundVolumeTv
• surroundMode / setSurroundMode(): Convenience wrapper for surroundFullVolumeEnabled

Soundbar Audio Input

• soundbarAudioInputFormatCode: Get audio input format code as integer (e.g., 18 for Dolby 5.1)
• soundbarAudioInputFormat: Get human-readable audio input format string (e.g., "Dolby 5.1", "No input")

Speech Enhancement

• speechEnhanceEnabled / setSpeechEnhanceEnabled(): Speech enhancement mode for Arc Ultra soundbars

Changed

• API Completeness: Dart port now has 100% API compatibility with Python SoCo
• Test Suite: 954+ passing unit tests (up from 867)
• Documentation: Added comprehensive API comparison document (API_COMPARISON.md)

Documentation

• Added API_COMPARISON.md documenting full API compatibility status
• Updated README.md to reflect 100% API completeness
• Updated TODO.md with completion status

0.1.0 - 2025-11-30

Initial Release

First public release of the SoCo Dart port. This is a complete port of the Python SoCo library, providing programmatic control of Sonos speakers from Dart applications.

Added

Core Features

• SoCo class with 120+ methods for comprehensive speaker control
• Device discovery via SSDP multicast and network scanning
• Playback control: play, pause, stop, next, previous, seek, play from queue
• Volume & audio: volume, mute, bass, treble, loudness, balance
• Queue management: get, add, remove, clear, reorder queue items
• Group management: join, unjoin, party mode, zone groups
• Music library: browse and search local music library
• Alarms: full CRUD operations for Sonos alarms
• Snapshot/restore: save and restore speaker state
• Events: UPnP subscriptions with Dart Streams
• Sleep timer and battery info support

Advanced Features

• Home theater: night mode, dialog mode, audio delay
• Surround speakers: enable/disable, volume control
• Subwoofer: enable/disable, gain, crossover settings
• Stereo pairs: create and separate stereo pairs
• Trueplay and fixed volume support
• Line-in and TV input switching

Music Services

• Music service accounts management
• Token store for service authentication
• Service-specific data structures
• Music service browsing and playback

Plugins

• Plugin system base infrastructure
• ShareLink plugin: Share music links across services
• Plex plugin: Plex media server integration
• Example plugin template

Data Structures

• DIDL-Lite metadata classes (tracks, albums, artists, playlists)
• Search results with pagination
• Zone group and zone member structures
• Alarm and snapshot data models

Project Statistics

• 18 core modules fully ported
• 5 music service modules
• 4 plugin modules
• 21 test modules with 567+ unit tests
• 80% code coverage (1843/2304 lines)
• 7 comprehensive examples
• Zero analyzer warnings

Differences from Python SoCo

• All I/O operations are async (Future-based)
• Events use Dart Streams instead of callbacks
• Full null-safety support
• Dart naming conventions (camelCase)
• Immutable data structures where appropriate

0.1.1 - 2025-11-30

Fixed

• UPnP Service Control URLs: Fixed incorrect control URLs that caused HTTP 405 errors when communicating with real Sonos hardware. Services now use correct paths:

  • RenderingControl: /MediaRenderer/RenderingControl/Control
  • AVTransport: /MediaRenderer/AVTransport/Control
  • ContentDirectory: /MediaServer/ContentDirectory/Control
  • And other services with appropriate prefixes

• getSpeakerInfo Caching: Fixed issue where getSpeakerInfo() would return incomplete data after device discovery. The method now correctly fetches speaker info even when ZoneGroupState data is already present.

Added

• Integration Test Suite: Added comprehensive integration test (test_integration.dart) that validates all core functionality against real Sonos hardware:
  • Discovery (11 devices found)
  • Volume and mute controls
  • Transport state and track info
  • Speaker info (zone name, model, versions)
  • Group operations (coordinator, members, all groups)
  • Play mode (shuffle, repeat)
  • Audio settings (bass, treble, loudness)
  • Sleep timer and available actions
  • TV/Line-in/Radio detection
  • Music library browsing
  • Zone enumeration (all zones, visible zones)

Changed

• Updated services.dart with proper eventSubscriptionUrl and defaultArgs for all UPnP services to match Python SoCo implementation

0.1.3 - 2025-12-01

Test Coverage Improvements

• Increased overall test coverage to 80.9% (2727/3370 lines)
• Improved coverage for key modules:
  • discovery.dart: 64.4% → 81.4% (+17.0%)
  • data_structures_entry.dart: 74.1% → 92.6% (+18.5%)
• Added comprehensive tests for:
  • Discovery module: factory usage, error handling, logging paths, includeInvisible, multiHousehold parameters
  • Data structures: error recovery, caching, subclass stripping, dynamic class creation
  • Core module: getSpeakerInfo, isSoundbar, and other getter methods
• Test suite: 867 passing unit tests

Changed

• Tests requiring complex ZoneGroupState integration documented for future integration testing
• Improved test organization and error handling coverage

0.1.2 - 2025-12-01

Performance Improvements

• XML Serialization Optimizations: Significant performance improvements for DIDL-Lite XML operations:

  • Direct XML builder usage (toElementInBuilder) avoids intermediate object creation
  • Pre-computed namespace tags for common DIDL elements (dc:title, upnp:class, etc.)
  • Optimized child element lookup using pre-built maps instead of repeated tree traversal
  • Pre-computed translation lookup keys for faster metadata extraction
  • Conditional logging to eliminate overhead when logging is disabled
  • Cache key optimization using hash codes instead of full strings

• Performance Benchmarks: Added comprehensive benchmark suite (benchmark/benchmark.dart) comparing Dart vs Python SoCo:

  • DIDL to String: 50% faster (~30K ops/sec vs ~20K ops/sec baseline)
  • Round-trip (parse → serialize): 84% faster (~83K ops/sec vs ~45K ops/sec baseline)
  • fromElement: Maintained high performance (~151K ops/sec)
  • Round-trip operations now 2x faster than Python SoCo

Added

• Performance Benchmark Suite: Added benchmark/benchmark.dart and benchmark/benchmark_python.py for performance comparison
• Performance Documentation: Added benchmark/PERFORMANCE_COMPARISON.md and benchmark/OPTIMIZATION_NOTES.md documenting optimizations

Changed

• DidlResource.toElementInBuilder(): New optimized method for direct XML building
• DidlObject.toElement(): Now uses optimized boolean string conversion
• fromDidlString(): Improved error recovery using pre-compiled RegExp
• Metadata extraction: Uses pre-computed lookup keys for faster access

Technical Details

• XML serialization now uses direct builder methods instead of parse/serialize cycles
• Child element collection optimized to single pass with map-based lookups
• Namespace tag generation uses pre-computed constants for common cases
• Translation lookup keys pre-computed at class initialization