# 🎵 AWTRIX NowPlaying – Sonos → AWTRIX Custom App (ioBroker)

Zeigt den aktuell laufenden Song von **Sonos** als eigene **AWTRIX Custom-App** an:  
`🎵 Künstler — Titel (Album)` – hält sich per Keep-Alive in der Rotation, solange ein Titel läuft.

> Getestet mit ioBroker (Javascript Adapter) + MQTT Adapter und einer AWTRIX mit MQTT-Support für Custom-Apps.

---

## 🚀 Features

- Liest **Titel / Artist / Album** aus Sonos-Datenpunkten  
- Baut automatisch die Anzeige: `🎵 Künstler — Titel (Album)`  
- **Keep-Alive**: hält die App aktiv, solange ein Titel vorhanden ist  
- Automatisches **Entfernen** der App, sobald keine Titelinfos mehr da sind  
- Optionales **FORCE_SWITCH**: bei jedem Refresh auf die App umschalten  
- **Debounce-Logik** (200 ms) gegen Flattern bei Trackwechseln  

---

## 🧩 Voraussetzungen

- **ioBroker** mit:
  - Javascript Adapter (zum Ausführen des Skripts)
  - MQTT Adapter (als Client zum MQTT-Broker; verwendet `sendMessage2Client`)
  - Sonos Adapter (liefert `current_title`, `current_artist`, `current_album`)
- **AWTRIX** (mit MQTT-Support für Custom-Apps)
- Ein erreichbarer **MQTT-Broker** (falls nicht in ioBroker integriert)

---

## ⚙️ Installation

1. In ioBroker den **Javascript-Adapter** öffnen → neues Script `NowPlaying Sonos → AWTRIX` anlegen  
2. Den Code aus `nowplaying_sonos_awtrix.js` einfügen  
3. Folgende Werte anpassen:
   - `MQTT_INSTANCE`, `AWTRIX_PREFIX`
   - Sonos-Datenpunkte unter `DP.title / artist / album`
4. Skript starten  
   → Beim ersten laufenden Titel sollte auf der AWTRIX die App **NowPlaying** erscheinen.

---

## 🔧 Konfiguration

| Variable           | Typ     | Standardwert | Beschreibung |
|--------------------|---------|---------------|--------------|
| `MQTT_INSTANCE`    | String  | `"mqtt.0"`    | ioBroker-Instanzname des MQTT-Adapters |
| `AWTRIX_PREFIX`    | String  | `"awtrix"`    | MQTT-Prefix der AWTRIX (z. B. `awtrix/custom/NowPlaying`) |
| `APP_NAME`         | String  | `"NowPlaying"`| Name der Custom-App |
| `LIFETIME_SEC`     | Number  | `600`         | Lebensdauer der App in Sekunden (wenn kein Refresh kommt) |
| `KEEPALIVE_SEC`    | Number  | `10`          | Intervall für den Refresh in Sekunden |
| `FORCE_SWITCH`     | Boolean | `false`       | Bei jedem Refresh auf die App umschalten |
| `ICON_MUSIC`       | Number  | `29944`       | AWTRIX-Icon-ID |
| `COLOR_RGB`        | Array   | `[255,255,255]` | RGB-Farbe für Text |
| `TEXT_CASE`        | Number  | `2`           | Textdarstellung (0 = normal, 1 = upper, 2 = smart) |
| `DP.title`         | String  | Beispiel      | Sonos-Datenpunkt `current_title` |
| `DP.artist`        | String  | Beispiel      | Sonos-Datenpunkt `current_artist` |
| `DP.album`         | String  | Beispiel      | Sonos-Datenpunkt `current_album` |

> ⚠️ **Hinweis:** Passe die Sonos-Datenpunkte an dein Gerät an – IP und Struktur können variieren.

---

## 🧠 Funktionsweise

1. **Trigger:**  
   ```js
   on({ id: [DP.title, DP.artist, DP.album], change: "ne" }, scheduleUpdate);
   ```
   Bei Änderung wird `updateAwtrix()` mit Debounce (200 ms) aufgerufen.

2. **Logik:**
   - Kein Titel → App entfernen, Keep-Alive stoppen  
   - Neuer Track → Text bauen, sofort publishen, Keep-Alive starten  
   - Gleicher Track → Keep-Alive aktualisiert regelmäßig selbst  

3. **Keep-Alive:**  
   Alle `KEEPALIVE_SEC` Sekunden wird `publishCustom()` aufgerufen.  
   Sobald kein Titel mehr vorhanden ist → App wird automatisch entfernt.

---

## 📡 MQTT-Themen & Payloads

### Custom-App veröffentlichen
**Topic:**  
```
<AWTRIX_PREFIX>/custom/<APP_NAME>
```

**Payload:**
```json
{
  "name": "NowPlaying",
  "text": "🎵 Artist — Title (Album)",
  "icon": 29944,
  "color": [255, 255, 255],
  "textCase": 2,
  "lifetime": 600
}
```

---

### Auf App umschalten (optional)
**Topic:**  
```
<AWTRIX_PREFIX>/switch
```

**Payload:**
```json
{ "name": "NowPlaying" }
```

---

### App entfernen
**Topic:**  
```
<AWTRIX_PREFIX>/custom/<APP_NAME>
```

**Payload:**
```json
{ "name": "NowPlaying", "lifetime": 1 }
```

---

> Das Skript sendet über:
> ```js
> sendTo("mqtt.X", "sendMessage2Client", { topic, message, retain: false, qos: 0 });
> ```

---

## 🛠️ Anpassungen & Tipps

### Mehrere Sonos-Player
- Skript **duplizieren**
- `APP_NAME` (z. B. `NowPlaying_Kueche`) und `DP.*` anpassen

### Anzeige-Dauer / Refresh
- Anzeige-Frequenz → `KEEPALIVE_SEC`
- Ablaufzeit ohne Refresh → `LIFETIME_SEC`

### Direkter Wechsel auf NowPlaying
- `FORCE_SWITCH = true` setzen, um bei jedem Refresh direkt zu wechseln

---

## 🧰 Troubleshooting

| Problem | Mögliche Ursache / Lösung |
|----------|----------------------------|
| Keine Anzeige | MQTT-Broker nicht erreichbar, falsches Prefix oder kein Song aktiv |
| App verschwindet zu schnell | `LIFETIME_SEC` erhöhen |
| Zu häufige Refreshs | `KEEPALIVE_SEC` erhöhen |
| Falsches Icon oder Textformat | `ICON_MUSIC` oder `TEXT_CASE` anpassen |
| App spammt Rotation | `FORCE_SWITCH = false` lassen |
| Keine Daten von Sonos | Sonos-Adapter prüfen (korrekte Player-IDs?) |

---

## 💾 Code

Die vollständige Version liegt in:  
`nowplaying_sonos_awtrix.js`

---

## 🔒 Sicherheit

- MQTT-Zugangsdaten werden im ioBroker-MQTT-Adapter verwaltet  
- Kein Retain (`retain:false`), QoS = 0 → kein Risiko veralteter Nachrichten  

---

## 📜 Lizenz

**MIT License** – siehe `LICENSE`

---

## 👏 Credits

- **Autor:** Mike  
- **AWTRIX-Projekt:** Community & Entwickler  
- **ioBroker Adapter:** Sonos, MQTT & Javascript  

---

## 🧾 Changelog

| Version | Datum | Änderungen |
|----------|--------|------------|
| v1.0.0 | 2025-10-27 | Erste Veröffentlichung |

---