brisebois/soundtouch-service repository overview

⁠Wisp

A second life for your Bose SoundTouch home.

Wisp is a self-hosted automation service for Bose SoundTouch speakers. It is built for households that want calm, reliable listening routines without cloud lock-in.
You define schedules once, and Wisp handles the rest: start times, stop times, gentle volume fades, and speaker-aware behavior that fits into everyday life.

⁠Project Links

• GitHub: https://github.com/AlexandreBrisebois/soundtouch-service⁠
• Issues: https://github.com/AlexandreBrisebois/soundtouch-service/issues⁠
• README: https://github.com/AlexandreBrisebois/soundtouch-service#readme⁠

⁠Why Wisp

• Gentle wake and wind-down audio with configurable fade-in and fade-out
• Reliable daily automation across one or many SoundTouch speakers
• Local-first architecture that keeps control and data inside your home network
• Fast PWA web interface for mobile-friendly control
• REST API for integrations and advanced automation workflows

⁠Core Features

• Scheduled auto-on and auto-off routines
• Per-routine settings for days, times, source or preset, and volume
• Manual Run Now triggers for immediate playback
• Pause and resume controls for vacations and schedule changes
• Real-time speaker status with responsive caching
• Built-in API documentation through Swagger UI

⁠Quick Start (Docker)

1. Create a local config.json from the provided template.

2. Run the container with host networking enabled.

   docker run -d
   --name wisp
   --network host
   -v $(pwd)/config.json:/workspace/config.json
   -p 9001:9001
   brisebois/soundtouch-service:latest

3. Open the UI at:

   http://YOUR-HOST-IP:9001⁠

⁠Docker Compose Example

services:
  wisp:
    image: brisebois/soundtouch-service:latest
    container_name: wisp
    network_mode: host
    volumes:
      - ./config.json:/workspace/config.json
    environment:
      - TZ=America/New_York
    restart: unless-stopped

⁠Important Deployment Notes

• Host networking is required for mDNS speaker discovery
• Mount config.json to /workspace/config.json
• Set TZ to your local timezone so schedules run at expected local times
• This service is especially well suited for Synology NAS and home-lab deployments

⁠API and Interface

• Web app: /
• API base: /api
• API docs: /apidocs

Wisp includes a clean control surface for day-to-day use and a practical API for deeper integration with automations, scripts, and dashboards.

⁠Who It Is For

Wisp is for people who want their home audio to feel automatic, quiet, and dependable.
If you already own Bose SoundTouch speakers and prefer self-hosted tools, Wisp gives you a polished way to automate your listening routines with confidence.