SoundHub

SoundHub is a local-network control application for smart audio devices, starting with Bose SoundTouch speakers. Built with a modern tech stack featuring Angular frontend, .NET 8 backend, and Docker deployment.

🎯 Features

Device Configuration: Add, edit, remove, and discover devices from the web UI
Device Discovery: Automatic network scanning to find compatible devices
Ping Verification: Audible connectivity test for devices
Device Control: Power, volume, presets, and Bluetooth pairing
Volume Control: Adjustable volume slider with mute toggle on device details page
Now Playing Display: LCD-style now playing text with auto-scrolling and customizable theme/speed
Web Interface: Modern landing page with device list, settings, and device control
Internationalization: Runtime language switching (English and Polish)
Vendor Abstraction: Extensible device adapter pattern for supporting multiple vendors
Local Station Storage: Self-hosted station JSON files for LOCAL_INTERNET_RADIO presets, served via the API or a reverse proxy (e.g. Caddy)
Secure Secrets: AES-256-CBC encrypted secrets storage
File-Based Configuration: Simple devices.json for device metadata
REST API: Well-documented OpenAPI/Swagger endpoints
Containerized: Docker-ready for easy deployment

📚 Documentation

Architecture Overview - System design and diagrams
API Reference - REST API documentation
Device Configuration Guide - User guide for managing devices
Testing Guide - Unit testing, E2E testing, and mocking patterns
devices.json Schema - Configuration file format

🌐 Web UI Routes

Route	Description
`/`	Landing page – displays list of configured devices
`/settings`	Settings page – language selection and LCD display settings
`/settings/devices`	Device configuration page – manage configured devices
`/devices/:id`	Device details page – view and control a specific device (now playing, power, volume, presets)

🏗️ Architecture

For a detailed architecture overview including layered diagrams, monorepo structure, device adapter pattern, and data flow, see docs/architecture.md.

Tech Stack

Frontend:

Angular (standalone components)
Nx monorepo for code organization
TypeScript, SCSS
Jest for testing

Backend:

.NET 8 Web API
Clean Architecture (Domain, Application, Infrastructure, Presentation)
Structured logging (JSON format)
Health checks for Docker
Swashbuckle/OpenAPI documentation

Deployment:

Docker & Docker Compose
Multi-stage builds for optimized images
Volume mounts for persistent data
Health checks and auto-restart

Project Structure

soundHub/
├── frontend/                          # Nx Angular workspace
│   ├── src/                           # Main Angular application
│   ├── e2e/                           # Playwright E2E tests
│   └── libs/frontend/                 # Shared libraries
│       ├── feature/                   # Feature modules
│       ├── data-access/               # Services & state management
│       ├── ui/                        # UI components
│       └── shared/                    # Utilities & types
├── services/                          # .NET backend solution
│   ├── SoundHub.Api/                  # Web API controllers & startup
│   ├── SoundHub.Application/          # Business logic & services
│   ├── SoundHub.Domain/               # Entities & interfaces
│   ├── SoundHub.Infrastructure/       # Adapters & persistence
│   └── tests/SoundHub.Tests/          # xUnit test project
├── data/                              # Volume mount for config & secrets
├── docs/                              # Documentation & diagrams
│   └── architecture.md                # Architecture overview with Mermaid diagrams
├── openspec/                          # OpenSpec change proposals
├── docker-compose.yml                 # Local development environment
├── Dockerfile.api                     # API container
└── Dockerfile.web                     # Web container

Device Adapter Pattern

The core abstraction for vendor-specific device control:

public interface IDeviceAdapter
{
    string VendorId { get; }
    Task<IReadOnlySet<string>> GetCapabilitiesAsync(string deviceId);
    Task<DeviceStatus> GetStatusAsync(string deviceId);
    Task SetPowerAsync(string deviceId, bool on);
    // ... other control methods
}

Each vendor (e.g., Bose SoundTouch) implements this interface. The adapter registry resolves the correct implementation at runtime.

🚀 Quick Start

Prerequisites

Docker & Docker Compose
(Optional) .NET 8 SDK for local API development
(Optional) Node.js 20+ for local frontend development

Run with Docker Compose

Clone the repository

git clone https://github.com/yourusername/soundHub.git
cd soundHub

Set PUBLIC_HOST_URL in docker-compose.yml

The API needs to know the public base URL so it can generate correct URLs for locally-stored station files (used by SoundTouch devices to fetch internet radio definitions). Set it to the Caddy address that clients will use — either the hostname or the IP:
```
environment:
  - PUBLIC_HOST_URL=http://<your-host>.local/soundhub   # or http://192.168.1.x/soundhub
```
If this is not set, the API falls back to http://localhost:5001, which only works for local access.
Start all services
```
docker-compose up --build
```
Access the application
- Web UI: http://localhost:5002
- API: http://localhost:5001
- Swagger UI: http://localhost:5001/swagger
Stop services
```
docker-compose down
```

Reverse Proxy with Caddy (macOS / hostname.local)

Use Caddy to expose the app at http://<your-host>.local/soundhub/ instead of a bare port. This supports multiple apps running on the same host — each under its own path.

Replace <your-host> with your Mac's hostname (find it in System Settings → General → Sharing, or run hostname -s in the terminal).

Install Caddy
```
brew install caddy
```

Configure /opt/homebrew/etc/Caddyfile

http://<your-host>.local, http://<your-ip> {
    # SoundHub frontend — redirect bare path to trailing-slash version
    redir /soundhub /soundhub/ permanent

    # SoundHub local preset station files (served from disk)
    handle /soundhub/presets/* {
        uri strip_prefix /soundhub/presets
        root * /path/to/soundHub/data/presets
        file_server
    }

    handle /soundhub/* {
        uri strip_prefix /soundhub
        reverse_proxy localhost:5002
    }

    # SoundHub API
    handle /soundhub/api/* {
        uri strip_prefix /soundhub
        reverse_proxy localhost:5001
    }

    # Add more apps here:
    # redir /otherapp /otherapp/ permanent
    # handle /otherapp/* {
    #     uri strip_prefix /otherapp
    #     reverse_proxy localhost:XXXX
    # }
}

Start Caddy as a background service
```
brew services start caddy
```
To reload after config changes:
```
brew services restart caddy
```
Access the application (via hostname or IP)
- Web UI: http://.local/soundhub/ or http:///soundhub/
- API: http://.local/soundhub/api/
- Swagger UI: http://.local/soundhub/api/swagger

<your-host>.local resolves automatically via mDNS/Bonjour on any macOS, iOS, or Linux client on the local network — no /etc/hosts changes needed on client machines. Using the IP address directly works on all platforms including Windows.

Local Development (Without Docker)

Backend (.NET API):

cd soundHub
dotnet build
dotnet run --project src/SoundHub.Api

Frontend (Angular):

cd frontend
npm install
npx nx serve web

📝 Configuration

Environment Variables

Variable	Default	Description
`ASPNETCORE_ENVIRONMENT`	`Production`	ASP.NET Core environment
`DevicesFilePath`	`/data/devices.json`	Path to device configuration
`SecretsFilePath`	`/data/secrets.json`	Path to encrypted secrets
`MasterPasswordFile`	`/run/secrets/master_password`	Path to Docker secret file containing master password
`MasterPassword`	`default-dev-password`	Fallback master password (used when file not available)

Docker Secrets (Recommended for Production)

The master password for encrypting secrets is managed via Docker secrets:

Development Setup:

Create a secrets directory and password file:

mkdir -p secrets
echo "your-secure-password" > secrets/master_password.txt

The docker-compose.yml is pre-configured to use this file as a Docker secret.

Production Setup (Docker Swarm):

# Create a Docker secret
echo "your-production-password" | docker secret create master_password -

# Reference in docker-compose.yml:
secrets:
  master_password:
    external: true

How it works:

Docker mounts the secret file at /run/secrets/master_password inside the container
The API reads the password from this file (via MasterPasswordFile configuration)
If the file doesn't exist, it falls back to the MasterPassword environment variable

Configuration Files

data/devices.json - Device metadata (vendor-grouped):

{
  "NetworkMask": "192.168.1.0/24",
  "SoundTouch": {
    "Devices": [
      {
        "Id": "...",
        "Vendor": "bose-soundtouch",
        "Name": "Living Room Speaker",
        "IpAddress": "192.168.1.131",
        "Capabilities": ["power", "volume", "presets", "ping"],
        "DateTimeAdded": "2025-12-31T12:00:00.000Z"
      }
    ]
  }
}

For detailed schema documentation, see docs/devices-schema.md.

data/secrets.json - Encrypted secrets (AES-256-CBC):

[
  {
    "SecretName": "SpotifyAccountPassword",
    "SecretValue": "<encrypted-base64>"
  }
]

🧪 Testing

Backend:

cd services
dotnet test

Frontend:

cd frontend
npx nx test

Testing with Real SoundTouch Devices

For integration testing against real Bose SoundTouch devices:

Ensure device is on the network - The device should be reachable via its IP address on port 8090.

Add the device via API:

curl -X POST http://localhost:5001/api/devices \
  -H "Content-Type: application/json" \
  -d '{"name": "Living Room", "ipAddress": "192.168.1.100", "vendor": "bose-soundtouch", "port": 8090}'

Test device endpoints:

# Get device info
curl http://localhost:5001/api/devices/{id}/info

# Get now playing
curl http://localhost:5001/api/devices/{id}/nowPlaying

# Get volume
curl http://localhost:5001/api/devices/{id}/volume

# Set volume to 30%
curl -X POST http://localhost:5001/api/devices/{id}/volume \
  -H "Content-Type: application/json" \
  -d '{"level": 30}'

# Play preset 1
curl -X POST http://localhost:5001/api/devices/{id}/presets/1/play

Device discovery - Scan your local network for SoundTouch devices:

curl http://localhost:5001/api/devices/discover?vendor=bose-soundtouch

Note: Integration tests require a real SoundTouch device on the network. Unit tests use mocked HTTP responses and don't require hardware.

Run all tests in CI:

# See .github/workflows/ci.yml

📖 API Documentation

Once the API is running, access interactive documentation:

Swagger UI: http://localhost:5001/swagger
OpenAPI JSON: http://localhost:5001/swagger/v1/swagger.json

For detailed API documentation, see docs/api-reference.md.

Key Endpoints

Device Configuration

GET /api/devices - List all devices
POST /api/devices - Add a device
GET /api/devices/{id} - Get device by ID
PUT /api/devices/{id} - Update a device
DELETE /api/devices/{id} - Remove a device
POST /api/devices/discover - Discover devices on LAN
GET /api/devices/{id}/ping - Ping device for connectivity

Configuration

GET /api/config/network-mask - Get discovery network mask
PUT /api/config/network-mask - Set discovery network mask
GET /api/vendors - List supported vendors

Device Status & Info

GET /api/devices/{id}/status - Get device status (power, volume, source)
GET /api/devices/{id}/info - Get detailed device info (name, type, MAC, software version)
GET /api/devices/{id}/nowPlaying - Get current playback info (track, artist, album, source)

Device Control

POST /api/devices/{id}/power - Set power state ({ "on": true|false })
GET /api/devices/{id}/volume - Get volume info (target, actual, mute state)
POST /api/devices/{id}/volume - Set volume ({ "level": 0-100 })
POST /api/devices/{id}/bluetooth/pairing - Enter Bluetooth pairing mode

Presets

GET /api/devices/{id}/presets - List device presets (1-6)
POST /api/devices/{id}/presets/{presetNumber}/play - Play a preset (1-6)

Health

GET /health - Health check

🔒 Security

Secrets Encryption: AES-256-CBC with PBKDF2 key derivation
Master Password: Retrieved from Docker secret file (/run/secrets/master_password) with fallback to environment variable
Key Storage: SQLite-based NSS-style key4.db for encrypted key storage
CORS: Configured for frontend origin only
HTTPS: Enabled in production (configure certificates in appsettings)

� Testing

Run Tests

Frontend Unit Tests:

cd frontend
npx nx run-many --target=test --all    # Run all unit tests
npx nx affected --target=test          # Run tests for affected projects
npx nx test feature                    # Run specific library tests
npx nx test feature --watch            # Watch mode

Frontend E2E Tests:

cd frontend
npx nx e2e e2e                         # Run Playwright tests
npx nx e2e e2e --headed                # Run with visible browser

Backend Tests:

cd services
dotnet test                            # Run all .NET tests
dotnet test --coverage                 # With coverage

Testing Best Practices

Router Mocking: When testing components with RouterLink, ensure your Router mock includes: navigate(), createUrlTree(), serializeUrl(), and events observable
Service Mocking: Mock external dependencies using Jest for Angular and Moq for .NET
Signal Testing: Verify both signal state changes and computed value updates
E2E Testing: Use semantic selectors and test complete user journeys

For detailed testing patterns and troubleshooting, see docs/testing-guide.md.

�🤝 Contributing

See CONTRIBUTING.md for development guidelines, commit conventions, and testing practices.

📄 License

[Your License Here]

🙏 Acknowledgments

SoundTouch WebServices API
Nx for monorepo tooling
.NET community for clean architecture patterns

Questions or issues? Open an issue on GitHub!

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
frontend		frontend
openspec		openspec
services		services
test-results		test-results
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.api		Dockerfile.api
Dockerfile.web		Dockerfile.web
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation