Skip to content

Home

Jump to bottom Edit New page
Jason G. Karlin edited this page Dec 23, 2023 · 149 revisions

Welcome to the alexa media player wiki! Please help us update this if you see errors or things to add.

What This Is

This is a custom component to allow control of Amazon Alexa devices in Homeassistant using the unofficial Alexa API.

Please note this mimics the Alexa app so Amazon may cut off access at anytime.

What It Does

Allows for control of Amazon Echo products as Home Assistant media devices with the following features:

  • Run Custom command
  • Play/Pause/Stop
  • Next/Previous (Track)
  • Volume
  • Retrieval for displaying in home assistant of:
    • Song Title
    • Artists Name
    • Album Name
    • Album Image
  • Shuffle
  • Repeat

Notable Additional Features

Run Custom Command

(versions >= 3.4.0)

You can now issue a voice command directly to a device as if you're speaking to it.

service: media_player.play_media
target:
  entity_id: media_player.guest_room
data:
  media_content_type: custom
  media_content_id: 'what time is it'

Play Music

We can basically do anything a Alexa Routine can do. You'll have to discover specifics, but here are some examples (and please help add them below!). To play music using the media_player.play_media service, you have to define the media_content_type appropriately. Search the forum for other examples.

Examples

Service examples

Spotify

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "Release Radar",
  "media_content_type": "SPOTIFY"
}

Amazon

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "cats the musical",
  "media_content_type": "AMAZON_MUSIC"
}

Playlist named "Duets"

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "My playlist Duets",
  "media_content_type": "AMAZON_MUSIC"
}

Apple Music

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "7 rings",
  "media_content_type": "APPLE_MUSIC"
}

Deezer

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "Falco",
  "media_content_type": "DEEZER"
}

I Heart Radio

entity_id: media_player.great_room
media_content_id: kiss
media_content_type: I_HEART_RADIO

Tunein

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "BBC one",
  "media_content_type": "TUNEIN"
}

_Please note the BBC services are not available via TuneIn in the United Kingdom_
_Try using a custom command instead :)_
{
  "entity_id": "media_player.guest_room",
  "media_content_id": "radio paradise main mix",
  "media_content_type": "TUNEIN"
}

SAAVN (JIOSAAVN)

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "Madras Melodies",
  "media_content_type": "SAAVN"
}

SiriusXM

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "Big 40 Countdown",
  "media_content_type": "SIRIUSXM"
}

Play in Alexa groups

It is currently not possible to play to an Alexa group using routines. However, there is currently a hack that may or may not work where you can play to an Alexa group using any Alexa entity on that account. For example, to play "boyz ii men" to the "everywhere group", you can set the "media_content_id" like the following. NOTE: The "entity_id" is set to media_player.guest_room(this could be any alexa device) instead of media_player.everywhere

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "boyz ii men in everywhere group",
  "media_content_type": "AMAZON_MUSIC"
}

Shuffle Play

You can shuffle, if supported, by mentioning shuffle at the beginning of the media_content_id.

Please note that Amazon seems to have removed shuffle command as stated in the following issue We leave the reference here as noone knows if Amazon will ever enable it again... A possible workaround would be to play the media, enable the shuffle entity then use the media_player.media_next_track service adding some wait in the middle.

entity_id: media_player.echo_show
media_content_id: shuffle greenday
media_content_type: AMAZON_MUSIC

Timer

(versions >= 3.2.0)

You can specify the amount of seconds the music will play before stopping. NOTE: This will only work if the target device is the playing device. If your target device will play on another device, the timer will not work.

entity_id: media_player.echo_show
media_content_id: taylor swift
media_content_type: AMAZON_MUSIC
extra: {"timer": 30}

Query errors

If you get errors, please check Alexa history to see if there's special parsing happening. There have been multiple reports of inconsistent behavior.

Acronym issues

ESPN

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "e._s._p._n. radio",
  "media_content_type": "TUNEIN"
}

NPR

  1. “BBC one” This works.
  2. "NPR” This has always worked but no longer…Alexa says it “can not play by artist on Tune-in”
  3. "N P R” sorta works but picks the incorrect media channel.
  4. “n. p. r.” now works properly. I found out by verbally asking Alexa to play N P R and checking history.

Please also note that different services may parse text differently.

Play sounds

(versions >= 2.4.0)

Sounds are also available using the media_player.play_media service.

Examples

{
  "entity_id": "media_player.guest_room",
  "media_content_id": "amzn_sfx_doorbell_chime_01",
  "media_content_type": "sound"
}

Script sample:

###scripts.yaml
door_bell_alexa:
  sequence:
    - service: media_player.play_media
      target:
        entity_id: media_player.guest_room
      data:
        media_content_type: sound
        media_content_id: amzn_sfx_doorbell_chime_01

Additional potential sounds can be found here.

Known available sounds:

Click to expand

Bells and Buzzer

  • bells: “bell_02”
  • buzzer: “buzzers_pistols_01”
  • church_bell: “amzn_sfx_church_bell_1x_02”
  • doorbell1: “amzn_sfx_doorbell_01”
  • doorbell2: “amzn_sfx_doorbell_chime_01”
  • doorbell3: “amzn_sfx_doorbell_chime_02”

Holidays

  • xmas_bells: “christmas_05”
  • halloween_door: “horror_10”

Misc

  • air_horn: “air_horn_03”
  • boing1: “boing_01”
  • boing2: “boing_03”
  • camera: “camera_01”
  • squeaky_door: “squeaky_12”
  • ticking_clock: “clock_01”
  • trumpet: “amzn_sfx_trumpet_bugle_04”

Animals

  • cat_meow: “amzn_sfx_cat_meow_1x_01”
  • dog_bark: “amzn_sfx_dog_med_bark_1x_02”
  • lion_roar: “amzn_sfx_lion_roar_02”
  • rooster: “amzn_sfx_rooster_crow_01”
  • wolf_howl: “amzn_sfx_wolf_howl_02”

Scifi

  • aircraft: “futuristic_10”
  • engines: “amzn_sfx_scifi_engines_on_02”
  • red_alert: “amzn_sfx_scifi_alarm_04”
  • shields: “amzn_sfx_scifi_sheilds_up_01”
  • sirens: “amzn_sfx_scifi_alarm_01”
  • zap: “zap_01”

Crowds

  • applause: “amzn_sfx_crowd_applause_01”
  • cheer: “amzn_sfx_large_crowd_cheer_01”

Set Echo Show background

(versions >= 2.10.0)

You can set the background of an Echo Show using the media_player.play_media service with media_content_type set to image. The url must be a valid https image to be accepted. To undo, follow these instructions.

Examples

entity_id: media_player.echo_show
media_content_id: "https://home-assistant.io/images/cast/splash.png"
media_content_type: image

Notification service

(versions >= 1.2.0)

Please see Notification Component for TTS, announcements, or mobile push.

Please note we do not support the Media Player UI for TTS!

Online status of devices

Additional attribute to tell you if the Alexa device is online (extremely useful if you want to send a TTS after one has come back online (such as one in a vehicle)

Last called device

As of >= 3.6.0, a notify target will be created automatically notify.alexa_media_last_called.

Note: The entity ID of the media device should not end with a number.

Each device will report whether it is the last_called for a specific Alexa account with the attribute last_called, the timestamp last_called_timestamp, and command last_called_summary (summary in versions >= 3.5.0). This allows us to identify the device that was called according to the Alexa Activities API.

For basic TTS notifications you do not need to create your own sensor, but it can be useful for other purposes like room-aware lighting or sensor reports.

Sending Notifications to the Last Called Device

###scripts.yaml

alexa_tts:
  sequence:
    - service: notify.alexa_media_last_called
      data:
        message: "YOUR MESSAGE"
        data:
          type: "tts"

Setting Up a Last Alexa Sensor

Add the following Template sensor configuration to configuration.yaml or templates.yaml to create the sensor.

template:
  - sensor:
      - name: Last Alexa
        state: |-
          {{ expand(integration_entities('alexa_media') | select('search', 'media_player'))
          | selectattr('attributes.last_called', 'eq', True) | map(attribute='entity_id') | first }}
        availability: |-
          {{ expand(integration_entities('alexa_media') | select('search', 'media_player'))
          | selectattr('attributes.last_called','eq',True) | first is defined }}

If you are using more than one Amazon account, see Legacy Last Called Sensor.

Script Examples

Using a script to set the volume for the last called device

This can be useful if you want to set up different default volume levels for different echos. For example the Echo dot 2nd gen. is much quieter at volume 0.3 than an Echo dot 3rd gen. So you probably want to set a higher volume for the 2nd gen. Echo dot.

###scripts.yaml

alexa_set_volume:
  sequence:
    - service: media_player.volume_set
      target:
        entity_id: "{{ states('sensor.last_alexa') }}"
      data:
        volume_level: >
          {% if is_state("sensor.last_alexa", "media_player.echo_dot_second_gen") %}
            0.5
          {% else %}
            0.3
          {% endif %}

Further Script and Automation Examples

update_last_called service

(versions >= 1.1.0)

You can now force a last_called update with the alexa_media.update_last_called service . This is intended to be used in scripts/automations to get the latest data. With no service data, it will refresh all accounts. If you want to selectively refresh an email account:

{
  "email": ["email1", "email2"]
}

Sequence commands

(versions >= 1.0.0)

Alexa accepts certain pre-defined sequences and this is what provides TTS and play_media. This is now exposed through the media_player.play_media service when the media_content_type is set to sequence

Example json:

{
  "entity_id": "media_player.alexa",
  "media_content_id": "Alexa.Joke.Play",
  "media_content_type": "sequence"
}

Supported sequences (may be region specific):

  • Alexa.Weather.Play
  • Alexa.Traffic.Play
  • Alexa.FlashBriefing.Play
  • Alexa.GoodMorning.Play
  • Alexa.GoodNight.Play
  • Alexa.SingASong.Play
  • Alexa.TellStory.Play
  • Alexa.FunFact.Play
  • Alexa.Joke.Play
  • Alexa.Music.PlaySearchPhrase
  • Alexa.Calendar.PlayTomorrow
  • Alexa.Calendar.PlayToday
  • Alexa.Calendar.PlayNext
  • Alexa.Date.Play
  • Alexa.CleanUp.Play
  • Alexa.ImHome.Play

Follow these instructions to discover more sequences and please update this list!

Alexa Routines

(versions >= 1.0.0)

Running Alexa Routines is now supported. Routines are automations setup inside the Alexa App. Please create them using the Alexa app and ensure they are enabled. This is now exposed through the media_player.play_media service when the media_content_type is set to routine Example json:

{
  "entity_id": "media_player.alexa",
  "media_content_id": "Goodnight",
  "media_content_type": "routine"
}

Example script to use a Routine called Radio Paradise that is set to play the radio station Radio Paradise from TuneIn on All Speakers

script:
  radioparadise:
    alias: Play Radio Paradise
    icon: "mdi:play"
    sequence:
    - service: media_player.play_media
      data:
        media_content_id: Radio Paradise # Routine name in Alexa app, this is set to play on All Speakers
        media_content_type: routine
      target:
        entity_id: media_player.den_echo_dot # need to select a default player
    mode: single

Lovelace card

type: entities
entities:
  - action_name: Play
    entity: script.radioparadise
  - action_name: Stop
    entity: script.stopmusic
show_header_toggle: false
title: Radio Paradise

Triggering a skill

(versions >= 2.7.0)

- alias: Trigging a skill.
  initial_state: "on"
  trigger:
    platform: state
    entity_id: input_boolean.start_my_car
    to: "on"
  condition: []
  action:
    - service: media_player.play_media
      data:
        media_content_id: <Skill ID>
        media_content_type: skill
      target:
        entity_id: media_player.my_echo_dot

You can find skill ID's by inspecting the JSON when navigating to https://alexa.amazon.com and clicking on skills.

Note: At the moment we do not collect a list of Skill IDs. However, for common skills please feel free to add their IDs to this wiki.

Common Skill IDs

  • BBC: amzn1.ask.skill.d0f09984-4805-4275-a118-d7f63f45fa55
  • NPR: amzn1.ask.skill.8e0fbda3-b70c-481d-878f-a2e5e17158c9
  • Jeopardy: amzn1.echo-sdk-ams.app.6d474311-b5aa-4f47-a97b-1036bc3e1954
  • Question of the Day: amzn1.ask.skill.0f26244c-7411-4c2c-8401-d808c57eedef
  • My Media for Alexa: amzn1.ask.skill.e4c09d45-60d3-4684-a23f-aeb8c1e28586

This functionality is intended to be used with Alexa Actions, a guide a custom skill designed to allow for actionable notifications from Home Assistant to your Alexa devices.

Automatic updates

HACS - Home Assistant Community Store

(versions >= 1.3.0)

We support HACS.

  1. Open HACS
  2. Go to the Store and search for Alexa Media

Guard Mode

(versions >= 1.3.0)

Arm and disarm Alexa guard mode using an Alarm Control Panel. To arm, use ARM_AWAY. ARM_HOME is the same as DISARM. Please ensure you've enabled through the Alexa app. You can find more instructions on integrating with Home Assistant here.

# Arms Alexa Guard.  
     - service: alarm_control_panel.alarm_arm_away
       entity_id: alarm_control_panel.alexa_guard # (or whatever yours is called)
# Only Disarm if armed.  Otherwise, Exit out.
    - condition: state
      entity_id: alarm_control_panel.alexa_guard
      state: armed

    - service: alarm_control_panel.alarm_disarm
      entity_id: alarm_control_panel.alexa_guard # (or whatever yours is called)

I found that I needed to use my unique name plus use state: armed_away to detect if Guard was active. You can find your unique number by just reviewing your Entities in Developer Tools.

# Only Disarm if armed.  Otherwise, Exit out.
    - condition: state
      entity_id: alarm_control_panel.alexa_guard_ # (or whatever yours is called)
      state: armed_away

    - service: alarm_control_panel.alarm_disarm
      entity_id: alarm_control_panel.alexa_guard_ # (or whatever yours is called)

We do not support any Guard notifications at the moment as the Alexa API does not provide an effective way to monitor.

Switches

(versions >= 1.4.0)

The component will create the following switches for each online media player.

  1. switch.<media_player>_repeat_switch
  2. switch.<media_player>_shuffle_switch
  3. switch.<media_player>_do_not_disturb_switch Do Not Disturb

Remark: If you are using any Includes during integration setup, you have to include the name of the switches for each switch the integration should create as well. Otherwise this switch is not created and excluded from setup.

Repeat and Shuffle are only available if the relevant music service supports them. Check against the Alexa App.

Notifications

(Alarms/Timers/Reminders)

(versions >= 2.3.0)

Each online media player that supports Notifications will create the following sensors:

  1. sensor.<media_player>_next_alarm
  2. sensor.<media_player>_next_timer
  3. sensor.<media_player>_next_reminder

Remark: If you are using any Includes during integration setup, you have to include the name of the sensors for each sensor the integration should create as well. Otherwise this sensor is not created and excluded from setup.

This will give the date time value for the very next active notification that will trigger or None if nothing will trigger for that sensor. This date time value can be used by templates to trigger actions when the time passes.

Additional attributes are exposed:

  • sorted_active - Sorted list of all active alarms for templating
  • sorted_all - Sorted list of all alarms for templating
  • recurrence - How often the alarm/reminder will recur
  • reminder - For the Reminder sensor, this it the name of the reminder

We currently only support reading Notifications.

clear_history service

Important note: Since the end of October 2023, this service no longer works due to a change in the API by Amazon.

(versions >= 2.3.0)

This service can clear Alexa's voice history recordings. It cannot delete history entries without a recording. You have to still delete those manually in the Alexa app.

Warning: Using this service will cause issues for your last_called sensor since it will be deleting the records and triggering devices behind the scene. Use this service during times you don't need last_called to be accurate.

Delete from certain accounts

With no service data, it will delete the last 50 entries for all accounts. If you want to selectively delete from an email account:

{
  "email": ["email1", "email2"]
}

Delete fewer entries than 50

Alexa has a hard limit of 50 per request, but you can select fewer.

{
  "entries": 30
}

Automation example

- alias: Clear Alexa History
  trigger:
    platform: time_pattern
    minutes: '/15'
  condition:[]
  action:
    - service: alexa_media.clear_history

Discover and control devices connected to an Echo

Some recent Echo devices include an integrated temperature sensor and the ability to control Zigbee lights directly. Alexa Media Player can be configured to add these entities to Home Assistant.

Setup

  1. Install and configure Alexa Media Player as normal
  2. Go to the Integrations page in Home Assistant
  3. Press "Options" on the Alexa Media Player integration card
  4. Check the box for "Include devices connected via Echo"
  5. Press "Submit"

This will add new entities for each temperature sensor and light detected. Temperature sensors will be associated to the Echo device directly and should have a name of "[Echo name] Temperature". Light entities will not be associated with the Echo device and should have a name that matches their current name in the Alexa app.

Limitations

  1. This will add devices connected directly to your Echo device. It will NOT add smart devices connected to Alexa via Skills.
  2. If the emulated_hue integration is enabled, older Hue lights will be ignored and not added to HA.
  3. Only the temperature sensor of an Echo device is currently supported
  4. If you change the state of lights via Alexa routines or via the Alexa app, you may notice a several minute delay before the Home Assistant entity is updated. This is a limitation of the Alexa API.
  5. Alexa supports a limited number of colors and color temperatures. AMP will use the closest possible color to the requested color.

Uninstalling Integration

If you wish to uninstall this integration:

  1. Remove the integration from your Integrations page, under Configuration > Integrations.
  2. Remove any configuration from your configuration.yaml. If you do not, you will get an error message every time you restart Home Assistant that says 'error setting up alexa_media'.
  3. Click Uninstall on the component in HACS. This step will delete the custom_component files.
  4. Manually delete any .pickle files from /config/.storage.
  5. (>= 3.4.2) Deregister Amazon Media Player from the Alexa app under Amazon devices (Manage my devices).

In development

PLEASE NOTE: These features are not in the main release and are for testing only. Check the dev branch if you want to try it. We may not be able to help you with configuration questions as we'll be focusing on getting it ready for release, but appreciate bug reports.

Guides

In German

There is a video tutorial how to install and configure this component available in german at youtube: https://youtu.be/giyo6Pv3GLo

In English

Here is a YouTube Play list by 3ATIVE for: Setup (install) | Controlling devices (Node-Red) | advanced TTS and more: https://www.youtube.com/playlist?list=PLWRTMby105biP9gE08iGLab1FP6n7_mka

Add a custom footer
Clone this wiki locally