DOCSEARCHbyAlgolia
Submit Docs

Spotcast Documentation

repository·master·Indexed 21 days ago

https://github.com/fondberg/spotcast

A Home Assistant custom component that enables starting Spotify playback on idle Chromecast or Spotify Connect devices. It implements a cast platform to allow Google Cast media players to play Spotify URIs and browse the Spotify library. The component provides the spotcast.start service for playback control and a sensor for discovering Chromecast devices. Note: The fondberg/spotcast repository is abandoned; users are advised to migrate to Mincka/spotcast.

Tokens
2.8K
Snippets
7
Records
13
Agent score
74%

What's inside Spotcast

  1. What Spotcast does and does not do

    master

    Spotcast is a Home Assistant custom component designed to start Spotify playback on an idle Chromecast device or a Spotify Connect device.

    Important Limitations:

    • It is not a full Spotify Chromecast media_player component.
    • It only serves to initiate playback.
    • Controlling the Chromecast device or the Spotify playback after the initial start must be handled by their respective components (e.g., the Chromecast media player component or the Spotify integration).

  2. Find a Spotify Device ID

    master

    To target a specific Spotify Connect device, you often need its spotify_device_id. You can find this using one of three methods:

    1. Spotify Developer Portal

    1. Go to the Spotify developer console.
    2. Click TRY IT.
    3. Extract the ID from the RESPONSE SAMPLE on the right side.

    2. Spotcast Debug Logs

    1. Enable debug logs for custom_components.spotcast in your configuration.yaml.
    2. Reboot Home Assistant.
    3. Play media on the target device.
    4. Check Configuration >> Logs >> Load Full Home Assistant Log.
    5. Look for the get_spotify_devices entry. The ID is inside the list of devices.

    3. Sonos Device ID (via Web Player)

    1. Open the Spotify Web Player and connect to your Sonos device.
    2. Open Browser DevTools (F12) and go to the Network tab.
    3. Look for a request URL like: https://gew1-spclient.spotify.com/connect-state/v1/connect/transfer/from/.../to/my_sonos_device_id.
    4. The my_sonos_device_id part is your target ID.
    # Example log entry to look for:
2022-01-13 19:10:35 DEBUG (SyncWorker_0) [custom_components.spotcast.helpers] get_spotify_devices: media_player.spotify_felix: Spotify Félix Cusson: [{'id': '################################', 'is_active': True, ...}]

# The ID is: ################################

  3. Install Spotcast via HACS or Manual Installation

    master

    You can install Spotcast into Home Assistant using two methods:

    1. HACS (Recommended): Use the Home Assistant Community Store (HACS) to search for and install the component.
    2. Manual Installation: Copy all files from the custom_components/spotcast/ directory of the repository into the custom_components/spotcast/ folder within your Home Assistant configuration directory.
    # Manual installation logic
cp -r custom_components/spotcast/* /config/custom_components/spotcast/

  4. Requirements for Spotcast

    master

    Before configuring Spotcast, ensure you meet the following requirements:

    1. Home Assistant Version: Compatible with versions since 2021.12.0, but requires 2024.11.0 or newer to run v4 or newer.
    2. Official Spotify Integration: Since version 3.5.2, you must have the official Home Assistant Spotify Integration installed and configured. Spotcast relies on this integration to provide the correct device list with the necessary scopes.

  5. Obtain Spotify `sp_dc` and `sp_key` cookies

    master

    Spotcast requires sp_dc and sp_key cookies for authentication. To obtain them:

    1. Open a new Incognito/Private window and log in to https://open.spotify.com.
    2. Open the Browser Developer Tools (F12 or Ctrl+Shift+I / Cmd+Option+I).
    3. For Chrome: Go to the Application tab -> Storage -> Cookies -> https://open.spotify.com.
    4. For Firefox: Go to the Storage tab -> Cookies -> https://open.spotify.com.
    5. Locate and copy the values for sp_dc and sp_key.

    CRITICAL: Do not log out of Spotify after copying the values, or the cookies will become invalid.

  6. Configure Spotcast for multiple accounts

    master

    To support multiple Spotify accounts, define an accounts dictionary in your spotcast configuration. Each account entry must include its own sp_dc and sp_key.

    Note: If you are using v3.5.2 or greater, these additional accounts must also be added to the official Home Assistant Spotify Integration for them to function correctly.

    spotcast:
  sp_dc: !secret primary_sp_dc
  sp_key: !secret primary_sp_key
  country: SE #optional
  accounts:
    niklas:
      sp_dc: !secret niklas_sp_dc
      sp_key: !secret niklas_sp_key
    ming:
      sp_dc: !secret ming_sp_dc
      sp_key: !secret ming_sp_key

  7. Configure the Spotcast sensor

    master

    The Spotcast sensor provides a list of discovered Chromecast devices as both a JSON object and an array of objects. Since v3.4.0, it relies on data from the core Home Assistant Cast integration.

    You can configure the sensor in your configuration.yaml. The country parameter is optional and defaults to SE if omitted.

    Sensor Name: sensor.chromecast_devices

    Attributes:

    • devices_json: A list of device objects containing name, cast_type, model_name, uuid, and manufacturer.
    • last_update: Timestamp of the last update.
    sensor:
  - platform: spotcast
    country: SE

  8. Configure Spotcast for a single account

    master

    To use Spotcast with a single Spotify account, add the spotcast block to your configuration.yaml. You must provide sp_dc and sp_key (ideally using !secret for security) and can optionally provide a country code.

    Prerequisite: As of v3.5.2, you must also have the official Home Assistant Spotify Integration installed and configured for Spotcast to work, as it provides the necessary device list.

    spotcast:
  sp_dc: !secret sp_dc
  sp_key: !secret sp_key
  country: SE #optional

  9. Store Spotify credentials in `secrets.yaml`

    master

    To avoid storing sensitive credentials in plain text in configuration.yaml, use the !secret tag and store the values in your secrets.yaml file.

    Single account example:

    sp_dc: [your sp_dc here]
sp_key: [your sp_key here]

    Multiple accounts example:

    primary_sp_dc: [your sp_dc here]
primary_sp_key: [your sp_key here]
niklas_sp_dc: [your niklas sp_dc here]
niklas_sp_key: [your niklas sp_key here]
ming_sp_dc: [your ming sp_dc here]
ming_sp_key: [your ming sp_key here]
    # secrets.yaml
sp_dc: [your sp_dc here]
sp_key: [your sp_key here]

  11. Call the `spotcast.start` service

    master

    The spotcast.start service allows you to control Spotify playback on various devices from Home Assistant. You can target devices using a spotify_device_id, a device_name (friendly name), or an existing Home Assistant entity_id.

    Common Usage Patterns

    1. Start playback with a specific URI Use a uri (track, playlist, or album) to start specific content. You can also use random_song: true to start at a random position in a playlist.

    2. Search for content Instead of a URI, you can provide a search query. This will be resolved into a URI (e.g., an artist or track name).

    3. Transfer current playback To move whatever is currently playing on a user's account to a new device, omit the uri parameter. Use force_playback: true to ensure playback continues even if nothing is currently active.

    4. Play podcasts Use a Spotify 'show' URI. Use ignore_fully_played: true to skip episodes the user has already heard.

    5. Use multiple accounts If you have configured multiple accounts in your secrets.yaml, specify the account key to use a non-default account.

    # Start playback on a specific device using a URI
- service: spotcast.start
  data:
    spotify_device_id: "ab123c5d7347324c2b1234567890f8d6dc40350"
    uri: "spotify:playlist:5xddIVAtLrZKtt4YGLM1SQ"
    random_song: true

# Transfer current playback to a device by name
- service: spotcast.start
  data:
    device_name: "Speaker kitchen"
    force_playback: true

# Start playback using a different configured account
- service: spotcast.start
  data:
    account: "niklas"
    device_name: "Speaker kitchen"
    uri: "spotify:playlist:5xddIVAtLrZKtt4YGLM1SQ"

  12. Use the Spotcast Websocket API

    master

    Spotcast exposes a Websocket API for retrieving playlists, devices, and player information. This is useful for custom frontend integrations.

    Available Methods

    • spotcast/playlists: Retrieve playlists. Supports playlist_type values:
      • user or default: User's saved playlists.
      • featured: Spotify's featured playlists.
      • discover-weekly: Personalized