mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-24 14:47:23 +00:00

Files

T

Tobias Gesellchen 5caad90d51 Implement /now_playing and /sources endpoints with real device integration

## New Endpoints

### GET /now_playing ✅
- Rich XML models with PlayStatus, ShuffleSetting, RepeatSetting enums
- Comprehensive playback information (track, artist, album, artwork, position)
- Device capabilities (skip, seek, favorite functionality)
- Smart display methods for different content types (music vs radio)
- Duration formatting with position/total time display

### GET /sources ✅
- Complete audio source management with SourceStatus enum
- Source categorization (Local/Remote, Streaming, Multiroom support)
- Multiple account support (multiple Spotify accounts per device)
- Availability filtering (Ready vs Unavailable sources)
- Helper methods for quick capability checks

## Real Device Integration

- Fetched actual XML responses from SoundTouch devices (192.168.178.28 & 192.168.178.35)
- Updated all test fixtures with real device data (anonymized)
- Enhanced XML models to handle all real-world fields and edge cases
- Verified compatibility across different device types and configurations

## Enhanced CLI Tool

- Added -nowplaying command with rich formatted output
- Added -sources command with categorized source listing
- Display enhancements: duration info, capabilities, source attributes
- Improved build process to use ./build/ directory consistently

## Comprehensive Testing

- 15+ unit tests for XML models with enum validation
- Client integration tests with mock HTTP responses
- Real device response validation
- Edge case handling (empty states, network errors, invalid data)

## Documentation & Guidelines

- Updated CLAUDE.md with build directory and real device testing guidelines
- Enhanced README with comprehensive usage examples
- Updated PLAN.md to reflect implementation progress
- All examples use real device data patterns

## Quality Improvements

- Type-safe XML unmarshaling with custom validation
- Consistent error handling across all endpoints
- Privacy protection (anonymized account information)
- Production-ready code structure and patterns

Features:
✅ GET /info - Device information
✅ GET /now_playing - Current playback status with full metadata
✅ GET /sources - Available audio sources with smart categorization
✅ UPnP device discovery
✅ Cross-platform CLI tool with rich output formatting
✅ Comprehensive test coverage with real device data
✅ Build automation with proper directory structure

2026-01-08 23:21:01 +01:00

3.5 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

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.5 KiB Raw Blame History