Una console Spotify su Home Assistant: Backend e Frontend

Si lo so, la rete è piena zeppa di articoli su come integrare Spotify in Home Assistant, ma non è mia intenzione ripetere solo cose già dette, vorrei invece descrivere il mio progetto dalla A alla Z.

Una soluzione integrata tra Backend e Frontend con le seguenti caratteristiche:

• Categorizzazione delle playlist preferite per genere musicale.
• Gestione multi-room.
• Configurazione dinamica con un file JSON di facile comprensione.
• Riproduzione di una playlist specifica o RANDOM in base al genere musicale di appartenenza.
• UI personalizzata con funzioni di avvio/gestione riproduzione e sensori informativi vari.
• Script di backend parametrico da usare nelle automazioni.

In questo articolo vi racconto come è strutturato il progetto, dalle componenti di backend fino alla realizzazione dell’interfaccia grafica su Lovelace, con il download di tutto il materiale per una installazione da zero.

Attenzione! Due cose importanti.

1. Per l’implementazione di questo progetto è necessario essere in possesso di un abbonamento Spotify Premium.
2. Questo progetto necessita di dispositivi che siano sempre disponibili su Spotify per la riproduzione. Gli Amazon Echo ad esempio lo sono. I Google Home (con l’integrazione Google Cast) no purtroppo, hanno bisogno di essere prima attivati dall’app di Spotify. Per risolvere il problema si può usare il custom component Spotcast, ma non è oggetto di questo articolo.

ELENCO DEGLI ARGOMENTI

• Premessa
• Requisiti
  • Spotify Application
  • Gestione dei Packages
  • Broker MQTT
  • Node-RED
• Backend
  • File di configurazione
  • Installazione
    • Package di Integrazione
    • Configurazione Node-RED
  • Come usare gli script
• Frontend
  • Modalità YAML
  • Modalità STORAGE
• Conclusione

Premessa

Premessa necessaria: il motore del progetto è sviluppato con Node-RED e usa un broker MQTT come protocollo di comunicazione tra Home Assistant e Node-RED.

Sono un gran sostenitore di Node-RED, ma non un fanatico a prescindere. Lo ritengo un ottimo strumento, ma credo che, come un qualsiasi altro strumento, è bene utilizzarlo solo quando necessario e non come strumento di automazione principale, almeno in ambito Home Assistant dove gran parte delle esigenze sono già coperte da script e automazioni in YAML.

Detto questo, perchè Node-RED in questo progetto?

Perchè volevo a tutti i costi governare, e rendere completamente dinamica, la configurazione principale tramite file JSON esterno. Un archivio con tutte le informazioni necessarie per dare vita alle idee di riproduzione che avevo. Probabilmente avrei potuto usare anche uno script AppDaemon, ma la via Node-RED mi è sembrata la più adatta in questo caso. Del file JSON ne parleremo in dettaglio più avanti.

Per poter utilizzare il materiale di questo articolo non è necessario che tu sappia utilizzare Node-RED. Più avanti ti dirò esattamente cosa fare per importare il flow e configurare i nodi principali.

Se proprio non vuoi usare Node-RED, dai un’occhiata a questa vecchia versione del progetto su GitHub realizzata con integrazione python_script. E’ sempre valida ma con qualche funzionalità in meno.

Requisiti

Per un corretto utilizzo è necessario che la tua configurazione soddisfi alcuni semplici requisiti.

Spotify Application (API)

Per consentire ad Home Assistant di utilizzare le API di Spotify è necessario creare una Spotify Application utilizzando il proprio account della piattaforma. Se hai già integrato Spotify nella tua configurazione questo passo non è necessario.

• Fai un login con il tuo account Spotify in questa pagina.
• Clicca su CREATE AN APP.
• Nella schermata seguente assegna un nome e una descrizione a piacere e clicca su CREATE.

• Ora prendi nota del Client ID e Client Secret (ci serviranno più avanti) e poi clicca su EDIT SETTINGS.

• Nella parte Redirect URIs devi inserire questa URL e cliccare su ADD.
  • Se non usi SSL: http://<IP LOCALE DI HA>:<PORTA>/auth/external/callback
  • Se usi SSL: https://<IP LOCALE DI HA>:<PORTA>/auth/external/callback

Va bene inserire l’indirizzo IP locale della tua istanza di HA seguito dalla porta, tipicamente 8123. Fai attenzione ad inserire il protocollo giusto: http o https in base alla tua configurazione.

• Infine clicca su SAVE in fondo alla schermata.

Gestione dei Packages

I Packages di Home Assistant sono un ottimo strumento per organizzare al meglio la configurazione.
Per attivare la gestione dei packages è sufficiente creare la directory packages dentro quella principale di configurazione (/config) e aggiungere al file configuration.yaml la seguente voce:

homeassistant:
  packages: !include_dir_named packages

In seguito, riavviare Home Assistant.

Broker MQTT

In questo progetto viene utilizzato MQTT come protocollo di comunicazione tra Home Assistant e Node-RED.
Per un corretto funzionamento è necessaria la presenza di un broker MQTT nella propria rete LAN e la relativa integrazione su Home Assistant.

Per l’installazione e la configurazione puoi seguire questa guida di inDomus.

Node-RED

Come detto nella premessa tutta la logica del progetto è sviluppata con Node-RED, di conseguenza è necessario dotarsi di questo componente. In ambiente Home Assistant OS oppure Home Assistant Supervised è possibile soddisfare facilmente questo requisito utilizzando il relativo Addon del Supervisor.

Per l’installazione e la configurazione di base puoi seguire questa guida di HassioHelp.

Backend

Bene, una volta soddisfatti tutti i requisiti possiamo procedere con il download e l’installazione del materiale necessario per la configurazione del Backend.

DOWNLOAD

Vediamo quali sono nel dettaglio gli elementi che compongono il progetto (lato backend).

• Un Package Home Assistant
  Un package da installare denominato spotify.yaml contenente integrazione ed entità necessarie al progetto.
• Un file JSON di configurazione
  Un file in formato JSON denominato spotify.json contenente la configurazione di Speaker, generi musicali e playlist di Spotify.
• Un Flow Node-RED
  Un flow Node-RED da importare e configurare nel proprio ambiente. Qui c’è tutta la logica del progetto.

File di configurazione

Prima di iniziare il processo di installazione vediamo come è strutturato e a cosa serve il file di configurazione spotify.json.

Se non ne hai mai sentito parlare, JSON è sostanzialmente un formato, semplice da leggere, utilizzato per lo scambio dei dati tra applicazioni. Ha una struttura ben precisa e una sintassi da rispettare, se vuoi approfondire l’argomento puoi consultare questa pagina.

Nell’ambito di questo progetto è utilizzato come archivio di configurazioni (Speaker in possesso) e preferenze personali (generi musicali e playlist preferite). Viene letto dal flusso Node-RED per popolare gli array di base con tutto il necessario per avviare le riproduzioni.

Nel materiale che hai scaricato trovi questo file con alcune voci preimpostate, a titolo di esempio ovviamente.

E’ qui che dovrai mettere le mani per gestire la tua configurazione.

{
  "playlists":
    [    
            {"genere":"Focus", "playlist":"Massima Concentrazione", "uri":"https://open.spotify.com/playlist/37i9dQZF1DXbA4Uw2yEsP9?si=66dba4ffe2dd4744"},    
            {"genere":"Focus", "playlist":"Lavorare con la musica", "uri":"https://open.spotify.com/playlist/37i9dQZF1DXcb7YJnr6Ck4?si=3efff1e7b0504157"},
            {"genere":"Relax", "playlist":"A Fine Giornata", "uri":"https://open.spotify.com/playlist/37i9dQZF1DWUeDwH47meQn?si=c37a0c5905114f61"},
            {"genere":"Relax", "playlist":"No Stress", "uri":"https://open.spotify.com/playlist/37i9dQZF1DXc0aozDLZsk7?si=7143e3405e1d41e3"},
            {"genere":"Country", "playlist":"Forever Country", "uri":"https://open.spotify.com/playlist/37i9dQZF1DX9hWdQ46pHPo?si=a3b12736d7b44b66"},
            {"genere":"Country", "playlist":"Country Rocks", "uri":"https://open.spotify.com/playlist/37i9dQZF1DWWH0izG4erma?si=cbf0bebcc3b44f32"},
            {"genere":"Rock", "playlist":"Rock Classics", "uri":"https://open.spotify.com/playlist/37i9dQZF1DWXRqgorJj26U?si=d4310b60ec344efe"},
            {"genere":"Rock", "playlist":"Soft Rock", "uri":"https://open.spotify.com/playlist/37i9dQZF1DX6xOPeSOGone?si=e71777868bbb4536"}
        ],
  "sources":
    [
      {"room":"Sala", "device":"Echo Sala", "entity_id" : "media_player.echo_sala"},
      {"room":"Studio", "device":"Echo Studio", "entity_id" : "media_player.echo_studio"},
      {"room":"Bagno", "device":"Echo Bagno", "entity_id" : "media_player.echo_bagno"},
      {"room":"Camera", "device":"Echo Camera", "entity_id" : "media_player.echo_camera"}
    ]
}

SOURCES

Nella sezione sources devi configurare tutti i tuoi media_player, nel mio caso sono utilizzati quattro device Amazon Echo, ognuno in stanze diverse naturalmente.

room
Stanza di riproduzione. Attenzione, il valore impostato qui sarà quello usato dagli script per avviare la riproduzione (lo vedremo più avanti).

device
Questo valore deve corrispondere esattamente a quello visualizzato da Spotify nell’elenco dei dispositivi disponibili, attenzione anche a maiuscole/minuscole.

entity_id
Qui devi inserire il nome dell’entità di Home Assistant.

PLAYLISTS

Nella sezione playlists invece devi configurare le tue playlist preferite con il genere musicale di appartenenza. Il genere, in realtà, funziona semplicemente da raccoglitore di playlist, puoi anche organizzare ad esempio una categoria “Personale” dove mettere dentro playlist di diverso tipo. Su questo hai libera scelta.

genere
Genere musicale o categoria di appartenenza. Il flusso Node-RED estrae i valori di questo attributo e crea una lista (senza voci duplicate) per popolare la input_select.spotify_genre  sulla UI. Il valore impostato qui sarà usato anche dagli script per avviare una riproduzione casuale di una delle playlist associate.

playlist
Nome della playlist. Il flusso Node-RED estrae i valori di questo attributo e popola la input_select.spotify_playlist in base al genere selezionato nella UI.

uri
Questo attributo rappresenta l’indirizzo fisico della playlist di Spotify e viene usato da Node-RED per costruire i parametri necessari al servizio media_player.play_media.

Questo file, una volta modificato con la tua configurazione, deve essere copiato nella directory /config/node-red.

Per trovare l’indirizzo di una playlist puoi seguire questa semplice procedura:

• Collegati alla console web di Spotify: https://open.spotify.com
• Cerca la playlist che vuoi configurare.
• Tasto destro sulla playlist -> Condividi -> Copia link alla playlist.
• Incolla il valore nell’attributo uri della configurazione.

Installazione

Ora procediamo con l’installazione e la configurazione del backend. Il processo si divide in due fasi:

• Installazione Package con integrazione Spotify ed entità del progetto.
• Installazione flusso Node-RED.

PACKAGE DI INTEGRAZIONE

• Copia il file spotify.yaml nella directory /config/packages.
• Aggiungi nel file secrets.yaml queste due entry con i rispettivi valori della tua Spotify Application.

  spotify_client_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  spotify_client_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Riavvia Home Assistant prima di continuare con gli step successivi (IMPORTANTE).
• Dopo il riavvio vai su Impostazioni -> Integrazioni.
• Clicca in basso a destra su Aggiungi Integrazione.
• Cerca e clicca la voce Spotify nella lista.
• Nella maschera seguente potrebbe chiedere l’autenticazione a Spotify. Nel caso autenticati e il processo è terminato.

Se tutto è andato bene ti troverai questa schermata che ci segnala l’avvenuta integrazione del componente Spotify.

L’integrazione ha creato un’entità media_player chiamata “spotify_” seguita dal tuo nome e cognome.
E’ molto importante rinominare questa entità in media_player.spotify.

• Vai su Impostazioni -> Integrazioni.
• Clicca sulla voce indicata nel box dell’integrazione Spotify.

• Clicca sull’unica riga presente nella schermata e poi rinomina l’entità come in figura.

• Infine, clicca su AGGIORNA.

Attenzione!

Se avevi già integrato Spotify devi fare in modo che questa porzione di codice, presente nel Package, non venga ripetuta nella tua configurazione.

spotify:
  client_id: !secret spotify_client_id
  client_secret: !secret spotify_client_secret

La parte invece di rename dell’entità media_player la devi seguire comunque, tenendo conto che può invalidare eventuali script o automazioni che la usano.

Node-RED

Ora vediamo cosa fare per importare il flow di Node-RED che trovi nel materiale e come configurare il broker MQTT.

• Copia il file di configurazione spotify.json nella directory /config/node-red.
  Attenzione! Il file di configurazione deve essere adattato con i tuoi media player e con le tue preferenze musicali come spiegato in questo capitolo.

AGGIORNAMENTO (13 Marzo 2024)

La configurazione degli ADDONS è cambiata con l’introduzione dell’area di storage ADDON_CONFIGS come spiegato qui.

In sostanza ora per poter leggere correttamente il file spotify.json da Node Red occorre spostarlo in una nuova posizione. Tramite l’addon SAMBA è possibile accedere alla directory addon_configs, successivamente entrare nella directory a0d7b954_nodered e qui creare la directory node-red con dentro il file spotify.json.

In lettura sarà sempre possibile accedere con il path /config/node-red/spotify.json, per cui non è necessario modificare nulla nel flusso node-red.

• Accedi all’interfaccia di Node-RED con la relativa voce nella sidebar.

• Fai click sull’icona hamburger in alto a destra e seleziona la voce Import.

• Ora clicca sul tasto segnalato e importa il file nodered.json che trovi nel materiale scaricato.

• Infine, clicca su Import.

Bene, ora nella tua configurazione di Node-RED è presente il flow necessario per il corretto funzionamento. Non entro nei dettagli della logica di questo flow, ma se ti interessa approfondire ne possiamo parlare nei commenti o nel gruppo Home Assistant Italia su Facebook.

Abbiamo quasi terminato, manca soltanto la configurazione dell’indirizzo IP e delle credenziali del Broker MQTT presente nella tua rete locale.

• In alto a destra fai doppio click sulla voce Broker MQTT dentro la sezione Global Configuration Nodes.

• Inserisci l’indirizzo IP del tuo Broker MQTT nella casella Server (se stai usando l’addon del Supervisor, l’indirizzo IP corrisponde a quello della tua istanza di Home Assistant).

• Inserisci le credenziali del Broker MQTT nella scheda Security e clicca su Update.

• Clicca sul tasto DEPLOY in alto a destra per applicare tutte le modifiche fatte.
• Infine, clicca sul tasto segnalato per inizializzare il flusso correttamente.

Il nodo Controlla File della precedente schermata monitora in tempo reale i cambiamenti del file di configurazione /config/node-red/spotify.json e inizializza il flusso automaticamente ad ogni salvataggio. Per cui, in caso di necessità, puoi modificare e salvare il file senza preoccuparti di nulla.

L’installazione del Backend è terminata, se hai seguito scrupolosamente tutta la procedura il tuo ambiente è pronto per utilizzare il materiale del progetto.

Come usare gli script

Nel prossimo capitolo vedremo come installare il materiale di Frontend per avere una console totalmente integrata con il Backend appena installato.

Nel package, però, hai a disposizione due script da usare come vuoi, per la realizzazione di una UI alternativa ad esempio, oppure per le tue automazioni. Vediamo come funzionano.

script.spotify_play

Questo script gestisce l’avvio di una riproduzione tramite l’invio di un topic MQTT in rete. Il topic viene letto da Node-RED, il quale interpreta i parametri e costruisce la chiamata al servizio media_player.play_media.

spotify_play:
  alias: "Riproduci una playlist"
  sequence:
    - service: mqtt.publish
      data:
        topic: "spotify/play"
        payload: >-
          {
            "room": "{{ room }}",
            "playlist": "{{ playlist }}",
            "genre": "{{ genre }}"
          }

Lo script prevede tre parametri:

• room : Stanza di riproduzione.
  Deve essere impostato con il valore del’attributo room della sezione sources nel file di configurazione spotify.json.
• playlist: Nome della playlist.
  Deve essere impostato con il valore dell’attributo playlist della sezione playlists nel file di configurazione spotify.json.
• genre : Genere musicale.
  Deve essere impostato con il valore dell’attributo genere della sezione playlists nel file di configurazione spotify.json.

Lo stesso script può essere eseguito con tre modalità diverse, vediamo alcuni esempi.

Playlist casuale tra tutte quelle configurate nella stanza Studio.

service: script.spotify_play
data:
  room: Studio

Playlist casuale del genere Rock nella stanza Sala.

service: script.spotify_play
data:
  room: Sala
  genre: Rock

Playlist specifica nella stanza Camera.

service: script.spotify_play
data:
  room: Camera
  playlist: A Fine Giornata

script.spotify_set_room

Questo script sposta la riproduzione attiva in un’altra stanza. Imposta anche il valore di una input_text di supporto all’interfaccia grafica.

spotify_set_room:
  sequence:
  - service: input_text.set_value
    data:
      value: "{{ room }}"
    target:
      entity_id: input_text.spotify_room        
  - choose:
    - conditions:
      - condition: template
        value_template: '{{ states.media_player.spotify.state != "idle" }}'
      sequence:    
        - service: mqtt.publish
          data:
            topic: "spotify/set-source"
            payload: "{{ room }}"

Questo un esempio di utilizzo:

service: script.spotify_set_room
data:
  room: Studio

Frontend

In questo capitolo vediamo come configurare la parte di Frontend.

Una console Spotify realizzata con Lovelace che sfrutta a pieno tutte le funzionalità introdotte nel backend.

Ti lascio la stessa console in due versioni differenti: una in modalità YAML coerente con questa metodologia, e l’altra in modalità STORAGE (Gestione Lovelace da interfaccia grafica)

Naturalmente questa console è basata sulle mie preferenze musicali e sui Speaker che ho nelle diverse stanze. Dovrai adattarla in base a come imposti la tua configurazione nel file JSON dedicato.

Custom Component

Per la realizzazione di questa interfaccia è richiesta l’installazione via HACS dei seguenti custom component:

• Button Card
• Card Mod
• HTML Jinja2 Template card
• Mini Media Player

Modalità YAML

In questo blog ho descritto nei dettagli il mio metodo per la realizzazione di una Dashboard Lovelace in modalità YAML, ne ho parlato in due articoli separati dove trovi tutto il materiale e le istruzioni di installazione.

PARTE 1 | PARTE 2

Il materiale in modalità YAML di questo progetto si integra con quello rilasciato in questo capitolo della Parte 2 e va scompattato dentro la directory tablet.

Questo, invece, il codice da integrare nel file lovelace-tablet.yaml per l’aggiunta della vista MUSICA.

- title: MUSICA
  path: musica
  panel: true
  cards:
    - type: 'custom:mod-card'
      style:
        hui-vertical-stack-card$: |
          #root {
            margin: 15px auto !important;
            max-width: 90%;
          }
      card:
        type: vertical-stack
        cards:
          - !include tablet/musica/header.yaml
          - type: 'custom:button-card'
            template: row_space_20
          - type: horizontal-stack
            cards:
              - !include tablet/musica/body_col_1.yaml
              - type: 'custom:button-card'
                template: empty_card
                styles:
                  card:
                    - width: 5px
              - !include tablet/musica/body_col_2.yaml

EDIT: 06 Aprile 2021  

Mi sono reso conto che tra i template del materiale pubblicato nella parte 2 ne manca uno fondamentale per questo progetto.

Questo template va aggiunto nel file  button_card_templates.yaml

action_spotify_room:
  entity: input_text.spotify_room
  styles:
    card:
      - height: 80px
    name:
      - margin-bottom: 5px
  tap_action:
    action: call-service
    service: script.spotify_set_room
    service_data:
      room: '[[[ return variables.room ]]]'
  state:
    - value: '[[[ return variables.room ]]]'
      styles:
        icon:
          - color: var(--paper-item-icon-active-color)
          - font-weight: bold
        name:
          - color: var(--paper-item-icon-active-color)
          - font-weight: bold

Modalità STORAGE

La modalità STORAGE, per chi non lo sapesse, è la modalità di default di gestione Lovelace. Si opera totalmente da interfaccia grafica per la realizzazione di una dashboard, avendo comunque la possibilità di eseguire modifiche in YAML dalle card singole, oppure dall’editor di configurazione testuale.

Di seguito il download del materiale e la procedura per installare il frontend del progetto in modalità STORAGE, creando una nuova vista in modalità PANNELLO.

DOWNLOAD MODALITA’ STORAGE

Prima di tutto dobbiamo definire i Template del custom component Button Card (se non sai cosa sono ne ho parlato qui). In modalità STORAGE i Template vanno configurati tramite lo strumento Editor di configurazione testuale.

• Clicca sui 3 puntini in alto a destra e poi su Modifica Plancia.

• Fai click ancora sui 3 puntini e poi Editor di configurazione testuale.

• Ora copia il contenuto del file button_card_templates.yaml e incollalo in testa nell’editor che si è aperto.
  Attenzione! Se già fai uso dei template di Button Card la prima riga non va ripetuta. Devi accodare i template di questo file a quelli già presenti nella tua configurazione.

• Clicca su SALVA in alto a destra.

Ora procediamo con la creazione della vista.

• Fai click sui 3 puntini e poi su Modifica Plancia come in precedenza.
• Clicca sull’icona + indicata nell’immagine.

• Qui puoi assegnare alla vista un nome a piacere oppure impostare un’icona. L’importante è selezionare la voce modalità Pannello.

• Clicca su SALVA.
• Clicca sul pulsante Aggiungi Scheda.

• Nella maschera seguente scorri fino in fondo e clicca su Manuale.

• Ora copia il contenuto del file panel_card.yaml nella configurazione della scheda e clicca su SALVA in basso a destra.

La procedura è terminata, ora dovresti vedere la nuova vista pronta per essere utilizzata.

Conclusione

Oh, che fatica arrivare fino a qui.

Onestamente avevo sottovalutato l’impegno necessario per descrivere questo progetto, soprattutto per la parte Node-RED dove ho provato a rendere accessibile a tutti lo strumento. Spero fili tutto liscio durante la configurazione, se dovessi aver trascurato qualcosa segnalalo e corriamo ai ripari.

Infine, mi permetto di ricordare l’importanza di sostenere lavori come questo e molti altri, affinché possano continuare ad esistere e migliorare.

Ciao e buona musica,
Max

---