mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-19 00:56:16 +00:00

Files

T

Tobias Gesellchen de2ff3550f Implement /name, /capabilities, and /presets informational endpoints

## New Endpoints

### GET /name ✅
- Simple device name retrieval with XML parsing
- Helper methods for name validation and display
- Real device name integration with anonymization

### GET /capabilities ✅
- Comprehensive device capabilities detection
- Complex XML structure with nested network, DSP, and system configurations
- Smart categorization: System Features, Audio Features, Network Features
- Capability-specific helper methods (HasLRStereoCapability, HasDualModeNetwork, etc.)
- Extended capabilities parsing with URLs and metadata

### GET /presets ✅
- Complete preset management with timestamps and metadata
- Spotify playlist integration with anonymized account information
- Smart filtering: by source, used/empty slots, most recent, oldest presets
- Comprehensive analysis: preset summaries with source breakdowns
- Time-based operations: creation/update timestamps with formatted display

## Device Introspection Features

### Capability Detection
- System capabilities: Light Switch, Clock Display, BCO Reset, Power Saving
- Audio capabilities: L/R Stereo support, DSP Mono/Stereo availability
- Network capabilities: Dual Mode, WSAPI Proxy, Hosted WiFi Configuration
- Extended capabilities: Custom endpoint discovery with URL mapping

### Preset Analysis
- Usage pattern analysis (used vs empty slots)
- Source distribution (Spotify, TuneIn, etc.)
- Temporal analysis (most recent, oldest presets)
- Content metadata extraction (artwork URLs, display names)

## Enhanced CLI Tool

### New Commands
- Added -name command with simple device identification
- Added -capabilities command with categorized feature display
- Added -presets command with comprehensive preset analysis
- Enhanced help system with all new command examples

### Rich Output Formatting
- Capability categorization with bullet-point display
- Preset timeline with creation/update timestamps
- Smart metadata display (artwork, source accounts, content types)
- Device-specific feature highlighting (different capabilities per device)

## Real Device Integration

### Multi-Device Testing
- Device 192.168.178.28: SoundTouch 10 with Light Switch, Clock Display, Hosted WiFi
- Device 192.168.178.35: SoundTouch 20 with L/R Stereo, Dual Mode networking
- Verified capability differences between device models
- Real preset data with anonymized Spotify account information

### Edge Case Handling
- Non-responsive endpoints (/trackInfo timeout handling)
- Empty preset configurations
- Missing capability sections
- Device-specific feature variations

## Quality & Testing

### Comprehensive Test Coverage
- 15+ unit tests for XML models with real device response patterns
- Client integration tests with mock HTTP servers
- Edge case validation (empty names, missing capabilities, no presets)
- Timestamp parsing and validation with Unix epoch conversion

### Production-Ready Features
- Type-safe XML unmarshaling with custom validation
- Robust error handling for network and parsing failures
- Privacy protection with anonymized real device data
- Documentation updates with real-world usage examples

## API Coverage Progress

✅ Complete Information Endpoints:
- GET /info - Device information
- GET /name - Device name
- GET /capabilities - Device capabilities
- GET /presets - Configured presets
- GET /now_playing - Current playback status
- GET /sources - Available audio sources

🔄 Next Phase - Control Endpoints:
- POST /key - Media controls
- GET/POST /volume - Volume management
- WebSocket / - Real-time events

Features:
✅ Comprehensive device introspection and capability detection
✅ Smart preset management with timeline analysis
✅ Multi-device support with hardware-specific feature detection
✅ Production-ready error handling and data validation
✅ Rich CLI interface with categorized output formatting
✅ Real device integration with privacy-protected test data

2026-01-08 23:32:18 +01:00

3.6 KiB

Raw Blame History

CLAUDE.md - Development Guidelines for Bose SoundTouch Project

Documentation Overview

This document contains important development guidelines for working on the Bose SoundTouch project. Please also read the following documentation:

PLAN.md - Project planning and roadmap
PROJECT-PATTERNS.md - Project structure and design patterns
API-Endpoints-Overview.md - API endpoints overview
SoundTouch Web API.pdf - Official API documentation

Development Guidelines

1. Tests are Mandatory

Implementation always with tests: Every new functionality must be developed with corresponding tests
Unit tests preferred: Where possible, unit tests should be written
Integration tests as alternative: If unit tests are not practical, implement integration tests via mock servers
Sample data from live system: Request/response data can be taken from a real SoundTouch system as examples
Respect privacy: All personal data must be anonymized before use in tests

2. Cross-Platform Compatibility

The project must work on the following platforms:

Windows
macOS
Linux
WASM (WebAssembly)

Platform-specific implementations are only allowed in justified exceptional cases.

3. KISS Principle (Keep It Simple, Stupid)

Simplicity has top priority
Complex solutions only when absolutely necessary
Code should be self-explanatory and well readable
Avoid over-engineering

4. Small Steps and Communication

Small, iterative steps: Break large features into smaller, testable units
Don't hallucinate: Don't make assumptions about unclear requirements
Ask instead of guess: Always ask when unclear instead of speculating
Transparency: Openly communicate uncertainties and limitations

5. Use Current Libraries

Use current and well-maintained libraries where possible
Regularly update outdated dependencies
Apply security updates promptly
Ensure compatibility with Go modules

6. Web-Specific Implementation

For web components:

Prefer plain HTML/JS/CSS: Avoid heavy frameworks where possible
Use modern web standards (ES6+, CSS Grid/Flexbox)
Apply progressive enhancement
Consider accessibility (a11y)
Implement responsive design

Build and Development Guidelines

7. Build Directory Structure

Use Makefile for building: Always use make build instead of direct go build commands
Build directory: All binaries must be created in the ./build/ directory
Example: Use make build to create ./build/soundtouch-cli, not ./soundtouch-cli
Cross-platform builds: Use make build-all for multi-platform binaries

8. Real Device Test Data

When creating test data for API endpoints, prefer real device responses over hypothetical examples:

Available test endpoints:
- http://192.168.1.100:8090/now_playing - Different response type 1
- http://192.168.1.35:8090/now_playing - Different response type 2
Usage: Fetch real responses to create accurate test fixtures
Privacy: Anonymize any personal data (account names, personal playlists, etc.)
Coverage: Use multiple real devices to cover different response variations
Non-responsive endpoints: Some endpoints like /trackInfo may not respond or exist on all devices

Additional Notes

Language: English for code, commits, labels, and text in code
Code comments in English
Documentation: Completely in English for international accessibility
Conduct regular code reviews
Consider performance from the beginning

3.6 KiB Raw Blame History