# Busch-Radio Spotify Bridge

Spotify-Musik auf dem Busch-Jäger Unterputz-Internetradio – ohne Bluetooth.

## Problem

Das **Busch-Jäger Unterputz-Internetradio** (z.B. 8217 U) kann nur vordefinierte oder eigene Internetradio-Streams abspielen. Es hat kein Bluetooth und keine Spotify-Integration. Spotify-Musik lässt sich damit direkt nicht wiedergeben.

## Lösung

Dieses Projekt enthält:

1. **Home Assistant Add-on** – erzeugt ein virtuelles **Spotify Connect-Gerät** im Netzwerk und stellt das Audio als HTTP-MP3-Stream bereit
2. **Custom Component** (optional) – zeigt den Stream-Status als Media-Player-Entity in HA an

```
Spotify-App
    │
    │ Spotify Connect (WiFi)
    ▼
┌─────────────────────────────────────────────┐
│          Home Assistant Add-on              │
│                                             │
│  librespot  ──(PCM)──▶  ffmpeg  ──(MP3)──▶ Icecast │
│  (Spotify Connect)       (Kodierung)  (HTTP-Server) │
└─────────────────────────────────────────────┘
    │
    │ HTTP-Stream: http://ha-ip:8000/stream.mp3
    ▼
Busch-Jäger Radio
```

---

## Voraussetzungen

| Anforderung | Details |
|---|---|
| Home Assistant | OS, Supervised oder Container (Add-on benötigt Supervisor) |
| Spotify Premium | Pflicht für Spotify Connect |
| Busch-Jäger Radio | Muss benutzerdefinierte Stream-URLs unterstützen |
| Netzwerk | HA und Smartphone im gleichen WLAN/LAN |

> **Wichtig:** Die kostenlose Version von Spotify unterstützt **kein** Spotify Connect. Ein Premium-Abo ist erforderlich.

---

## Installation

### 1. Add-on installieren

#### Option A: Repository in HA hinzufügen

1. Navigiere zu **Einstellungen → Add-ons → Add-on Store**
2. Klicke oben rechts auf **⋮ → Repositories**
3. Trage die URL dieses Repositories ein
4. Das Add-on **Busch-Radio Spotify Bridge** erscheint im Store
5. Installiere es (Kompilierung von librespot dauert ~10-15 Minuten)

#### Option B: Manuell (für Entwickler)

```bash
# Repository klonen
git clone https://gitea.example.com/retr0/busch-radio-spotify.git

# ha-addon-Verzeichnis in HA Add-on-Pfad kopieren
# (unter Home Assistant OS: /addons/busch_radio_spotify)
cp -r busch-radio-spotify/ha-addon /addons/busch_radio_spotify

# In HA: Einstellungen → Add-ons → Add-on Store → ⋮ → Lokale Add-ons prüfen
```

### 2. Add-on konfigurieren

Navigiere zu **Einstellungen → Add-ons → Busch-Radio Spotify Bridge → Konfiguration**:

```yaml
device_name: "Busch-Radio"        # Name in der Spotify-App
bitrate: 320                       # 96 / 160 / 320 kbps
stream_port: 8000                  # HTTP-Port des Streams
stream_mount: "/stream.mp3"        # URL-Pfad
icecast_password: "geheim"         # Sicherheitspasswort (bitte ändern!)
username: ""                       # Spotify-Konto (optional, s.u.)
password: ""                       # Spotify-Passwort (optional, s.u.)
```

> **Hinweis zu `username`/`password`:** Diese Felder sind optional. Ohne Zugangsdaten
> wird das Gerät über **Zeroconf/mDNS** automatisch im Netzwerk gefunden – das ist
> die empfohlene Methode. Zugangsdaten werden nur benötigt, wenn mDNS im Netzwerk
> blockiert ist.

### 3. Netzwerk-Port freigeben

Im Tab **Netzwerk** des Add-ons den Port `8000` auf `8000` mappen (oder einen anderen freien Port wählen).

### 4. Add-on starten

Im Tab **Info** auf **Starten** klicken. Die Logs zeigen:

```
[INFO] Busch-Radio Spotify Bridge v1.0.0
[INFO] Stream-URL für das Busch-Jäger Radio:
[INFO]   http://<homeassistant-ip>:8000/stream.mp3
[INFO] Wähle 'Busch-Radio' in der Spotify-App als Abspielgerät.
```

### 5. Stream im Busch-Jäger Radio eintragen

Im Radio-Menü (je nach Modell verschieden) eine neue Internetradio-Station anlegen:

```
URL: http://<homeassistant-ip>:8000/stream.mp3
```

Ersetze `<homeassistant-ip>` durch die tatsächliche IP-Adresse deines Home Assistant, z.B. `192.168.1.100`.

> **Tipp:** Die IP-Adresse findest du in HA unter **Einstellungen → System → Netzwerk**.

### 6. Optional: Custom Component installieren

Für die Status-Anzeige in HA:

```bash
# custom_components-Verzeichnis in HA config kopieren
cp -r custom_components/busch_radio_spotify \
      /config/custom_components/busch_radio_spotify

# HA neu starten
```

Dann unter **Einstellungen → Integrationen → Integration hinzufügen → Busch-Radio Spotify Bridge** einrichten.

---

## Bedienung

1. Öffne die **Spotify-App** auf Smartphone oder Computer
2. Spiele ein Lied ab
3. Tippe auf das **Gerät-Symbol** (unten in der App)
4. Wähle **"Busch-Radio"** (oder deinen konfigurierten Gerätenamen)
5. Die Musik wird automatisch über den Stream an das Radio übertragen

> Das Radio muss die Stream-URL bereits abgespielt haben oder neu eingestellt werden,
> sobald Spotify mit dem Abspielen beginnt.

---

## Einrichtung der Stream-URL im Radio (Modellabhängig)

### Busch-Jäger 8217 U / ähnliche Modelle

1. Ins Radio-Menü navigieren (meist über die Benutzeroberfläche oder App)
2. **Meine Sender → Sender hinzufügen** oder **Internetradio → Eigene URL**
3. URL eingeben: `http://192.168.1.100:8000/stream.mp3`
4. Namen vergeben: z.B. "Spotify"
5. Speichern und Stream starten

### Alternativ: Über vTuner/Frontier Silicon Portal

Einige Busch-Jäger Modelle nutzen vTuner als Radio-Backend:
1. Auf `http://www.wifiradio-frontier.com` registrieren
2. Unter "Meine Sender" → "Sender hinzufügen" die Stream-URL eintragen
3. Im Radio synchronisieren

---

## Custom Component – Media Player Entity

Nach der Installation der Custom Component erscheint ein neuer Entity in HA:

**Entity-ID:** `media_player.busch_radio_192_168_1_100`

| State | Bedeutung |
|---|---|
| `playing` | Mindestens ein Hörer verbunden |
| `idle` | Quelle aktiv, aber kein Hörer |
| `off` | Icecast nicht erreichbar |

**Attribute:**

| Attribut | Beschreibung |
|---|---|
| `stream_url` | Die URL für das Radio |
| `listeners` | Anzahl aktiver Hörer |
| `source_connected` | Ob librespot an Icecast sendet |
| `bitrate_kbps` | Aktuelle Bitrate |

**Dashboard-Karte (Beispiel):**

```yaml
type: media-control
entity: media_player.busch_radio_192_168_1_100
```

**Automatisierung – Radio starten wenn Spotify beginnt:**

```yaml
automation:
  alias: "Busch-Radio wenn Spotify spielt"
  trigger:
    platform: state
    entity_id: media_player.busch_radio_192_168_1_100
    to: "playing"
  action:
    service: notify.mobile_app
    data:
      message: "Spotify spielt auf dem Busch-Radio"
```

---

## Technische Details

### Komponenten

| Komponente | Funktion | Version |
|---|---|---|
| [librespot](https://github.com/librespot-org/librespot) | Spotify Connect Client | Aktuell via cargo |
| [ffmpeg](https://ffmpeg.org) | PCM → MP3 Transkodierung | Via Alpine apk |
| [Icecast](https://icecast.org) | HTTP-Stream-Server | Via Alpine apk |

### Signalfluss im Detail

```
Spotify CDN → (verschlüsselt, OGG Vorbis)
           → librespot (dekodiert, gibt PCM aus)
           → stdout (44100 Hz, S16LE, Stereo = 176.4 KB/s)
           → ffmpeg stdin
           → MP3-Kodierung (libmp3lame, 320 kbps ≈ 40 KB/s)
           → Icecast (HTTP-Streaming-Server)
           → Busch-Jäger Radio (HTTP-Client)
```

### PCM-Format von librespot
- Sample Rate: 44100 Hz
- Bit-Tiefe: 16-bit signed, Little-Endian
- Kanäle: 2 (Stereo)
- Rohe Datenrate: ~172 KB/s

### Restart-Verhalten

Die Pipeline `librespot | ffmpeg` wird bei Absturz automatisch nach 5 Sekunden neu gestartet. Icecast bleibt davon unberührt.

---

## Fehlerbehebung

### Das Gerät erscheint nicht in der Spotify-App

**Ursachen & Lösungen:**

- **Add-on läuft nicht** → Add-on-Status in HA prüfen
- **Anderes WLAN/Subnetz** → Smartphone und HA müssen im selben Netzwerk sein
- **mDNS blockiert** → Spotify-Zugangsdaten in der Add-on-Konfig eintragen
- **Gerätename bereits vergeben** → `device_name` in der Konfig ändern
- **Firewall** → Port 5353 (mDNS/UDP) und Port 8000 (TCP) freigeben

### Kein Audio / Stream leer

```bash
# Im Browser öffnen – sollte die Icecast-Statusseite zeigen:
http://homeassistant-ip:8000

# Wenn das funktioniert, aber kein Audio:
# → In Spotify das Gerät "Busch-Radio" auswählen und abspielen
```

### Stream bricht ab beim Pausieren

Das ist das erwartete Verhalten: Wenn Spotify pausiert, sendet librespot nichts mehr an Icecast. Das Radio verliert die Verbindung.

**Lösung:** Nach dem Fortsetzen der Wiedergabe in Spotify den Stream im Radio kurz stoppen und wieder starten.

*Zukünftige Verbesserung: Stille-Generierung bei Pause geplant.*

### ffmpeg startet nicht / Kodierungsfehler

```bash
# Add-on Logs prüfen auf Zeilen wie:
[WARNING] [ffmpeg] ...

# Häufige Ursachen:
# - libmp3lame nicht installiert (ffmpeg ohne MP3-Support)
# - Icecast-Passwort stimmt nicht überein
# - Port 8000 bereits belegt
```

### Icecast antwortet mit 401 (in der Custom Component)

Das Passwort in der Custom Component-Konfiguration stimmt nicht mit `icecast_password` im Add-on überein. Integration neu einrichten.

---

## Rechtliche Hinweise

### librespot und Spotify ToS

- Dieses Projekt nutzt **librespot**, eine quelloffene Reimplementierung des Spotify-Clients
- Librespot ist ein **Spotify Connect-Client** und kein Downloader/Recorder
- Audio wird **nicht gespeichert** – nur live gestreamt
- Die Nutzung im privaten Heimbereich ist technisch weitgehend akzeptiert, kann aber gegen **Abschnitt 2.5** von Spotifys Nutzungsbedingungen verstoßen
- **Spotify Premium ist erforderlich** – kostenlose Konten funktionieren nicht
- Dieses Projekt ist ausschließlich für den **persönlichen Privatgebrauch** gedacht

### Verwendete Open-Source-Lizenzen

- **librespot** – MIT License
- **ffmpeg** – LGPL 2.1+ / GPL 2+
- **Icecast** – GPL 2

---

## Projektstruktur

```
busch-radio-spotify/
├── ha-addon/                    # Home Assistant Add-on
│   ├── Dockerfile               # Multi-Stage Build (Rust + Alpine)
│   ├── config.yaml              # Add-on Manifest & Optionen
│   ├── build.yaml               # Multi-Arch Build-Konfiguration
│   └── run.sh                   # Startup-Script (Icecast + librespot + ffmpeg)
│
├── custom_components/           # Optionale HA Integration
│   └── busch_radio_spotify/
│       ├── __init__.py          # Integration Setup
│       ├── manifest.json        # Integration Manifest
│       ├── media_player.py      # Media Player Entity (Icecast-Polling)
│       ├── config_flow.py       # Grafische Einrichtung
│       ├── strings.json         # UI-Texte
│       └── translations/
│           ├── de.json          # Deutsch
│           └── en.json          # Englisch
│
├── example-config.yaml          # Kommentierte Beispielkonfiguration
└── README.md                    # Diese Datei
```

---

## Geplante Verbesserungen

- [ ] Stille-Generierung bei Spotify-Pause (verhindert Stream-Abbruch im Radio)
- [ ] Lautstärke-Steuerung über HA (librespot unterstützt DBUS)
- [ ] Track-Metadaten (Titel, Künstler) via librespot-Event-System
- [ ] OGG-Stream Option für bessere Qualität bei gleicher Bitrate
- [ ] Automatischer Start des Radios beim Verbinden (via HA-Automation)

---

## Beitragen

Issues und Pull Requests sind willkommen auf:
`https://gitea.example.com/retr0/busch-radio-spotify`

---

## Lizenz

MIT License – siehe [LICENSE](LICENSE)