Media Player Service Enhancements

The following enhancements were made to built-in services that are supported by the HA Media Player platform.

As a quick summary, the following options are NOT present in the original soundtouch component and will be new functionality for SoundTouch device users:

Grouping / Zone Support
Play Media Extensions
Repeat Modes
Seek Position Play
Shuffle Modes
Sound Modes
State Custom Variables

The integration also supports a number of custom services. Check out the Services Provided wiki document for a complete list.

The following HA media player standard features are supported by this integration:

BROWSE_MEDIA
GROUPING
NEXT_TRACK
PAUSE
PLAY
PLAY_MEDIA
PREVIOUS_TRACK
REPEAT_SET
SEEK
SELECT_SOUND_MODE
SELECT_SOURCE
SHUFFLE_SET
STOP
TURN_OFF
TURN_ON
VOLUME_MUTE
VOLUME_SET
VOLUME_STEP

`join` / `unjoin` (Zone Support)

The integration supports the HA media player GROUPING feature, which allow you to easily create groups (or Zones as they are referred to in the SoundTouch world). The HA media player join and unjoin services can be used to create a zone, add / remove members, remove a zone, etc.

The join service will create a new zone if one does not already exist.

For example:

# Create zone - bose_st10_1 is master, bose_st10_2,3,4 are members.
service: media_player.join
target:
  entity_id:
    - media_player.bose_st10_1
  device_id: []
  area_id: []
data:
  group_members:
    - media_player.bose_st10_2
    - media_player.bose_st10_3
    - media_player.bose_st10_4

# Remove members bose_st10_2,3 from the zone:
service: media_player.unjoin
data: {}
target:
  entity_id:
    - media_player.bose_st10_3
    - media_player.bose_st10_4

The HACS custom mini-media player also supports the join / unjoin calls for grouping as well; just make sure you specify platform: media_player instead of platform: soundtouch in the speaker_group settings, like so:

...
    speaker_group:
      platform: media_player
      show_group_count: true
      sync_volume: true
      icon: mdi:speaker-multiple
      entities:
        - entity_id: media_player.bose_st10_1
          name: Bose ST10-1
        - entity_id: media_player.bose_st10_2
          name: Bose ST10-2
        - entity_id: media_player.bose_st10_3
          name: Bose ST10-3
        - entity_id: media_player.bose_st10_4
          name: Bose ST10-4
        - entity_id: media_player.bose_st300
          name: Bose ST-300 SoundBar

`media_seek` (Seek Support)

The integration supports the HA media player SEEK feature, which allows you to change the position of the currently playing media as it is playing. Note that not all sources or media support seek functions.

The following HA media player attributes are updated to support seek functions:

media_duration - current duration (total time) of the playing media, in seconds.
media_position - current position in the playing media, in seconds.
media_position_updated_at - utc datetime of when the position was last updated.

Note that the current media position value will only be updated every 30 seconds for devices that are members of a zone, while the master zone will update the position value every second. This is driven by the SoundTouch device, and cannot be corrected by the integration nor the underlying API. This causes progress bars for zone members to be off in the HA UI since they can be up to 30 seconds different than the master zone.

YAML example:

# Start playing media from 100 seconds going forward.
service: media_player.media_seek
target:
  entity_id: media_player.bose_st10_1
data:
  seek_position: 100

The HACS custom mini-media player also supports media_seek functions; just make sure you specify the runtime: false option under the hide: options. This will show a progress bar with current position, duration, and estimated time remaining values. You can drag the progress bar to change the play position, like so:

`play_media`

The integration modifies supports of the HA media player PLAY_MEDIA feature, which allows you to play media from a given source.

Note that only a limited number of sources support PLAY_MEDIA functions. See example YAML below for details.

The following arguments are passed to the play_media service:

media_content_id - content id to play on the specified source.
media_content_type - type of media (album, artist, playlist, track, etc).
source (extra keyword property) - source title to select for playing the content; must exactly match (case-sensitive) a source title in the source list.

Example YAML - Spotify

Note that a Premium-level membership is required in order to play Spotify content.

# play Spotify music service content - album.
service: media_player.play_media
target:
  entity_id: media_player.bose_st10_1
data:
  media_content_id: "spotify:album:6vc9OTcyd3hyzabCmsdnwE"
  media_content_type: album
  extra:
    source: "Spotify (yourSpotifyUserId)"

# play Spotify music service content - artist.
service: media_player.play_media
target:
  entity_id: media_player.bose_st10_1
data:
  media_content_id: "spotify:artist:3jdODvx7rIdq0UGU7BOVR3"
  media_content_type: artist
  extra:
    source: "Spotify (yourSpotifyUserId)"

# play Spotify music service content - playlist.
service: media_player.play_media
target:
  entity_id: media_player.bose_st10_1
data:
  media_content_id: "spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE"
  media_content_type: playlist
  extra:
    source: "Spotify (yourSpotifyUserId)"

# play Spotify music service content - track.
service: media_player.play_media
target:
  entity_id: media_player.bose_st10_1
data:
  media_content_id: "spotify:track:06p6rTVmcxF7eK6ggOLmua"
  media_content_type: track
  extra:
    source: "Spotify (yourSpotifyUserId)"

`repeat_set` (Repeat Mode)

The integration supports the HA media player REPEAT_SET feature, which allow you to repeat media content that is currently playing.

Note that not all sources or media support repeat functions.

For example:

# Repeat one track.
service: media_player.repeat_set
data:
  repeat: one
target:
  entity_id: media_player.bose_st10_1

# Repeat all tracks.
service: media_player.repeat_set
data:
  repeat: all
target:
  entity_id: media_player.bose_st10_1

# Disable repeat mode.
service: media_player.repeat_set
data:
  repeat: "off"
target:
  entity_id: media_player.bose_st10_1

`select_sound_mode`

The integration supports the HA media player SELECT_SOUND_MODE feature for SoundTouch devices that support the /audiodspcontrols service. Note that not all SoundTouch devices support the /audiodspcontrols service. If not supported, then sound mode enhancements are not supported, and the sound_mode_list state will display a "not capable" status. Please refer to the wiki Audio DSP Controls guide for more information on the /audiodspcontrols service, and how to check what audio modes your SoundTouch device supports.

If the device supports it, you can switch between various audio modes that the device supports. For example, a SoundTouch 300 SoundBar will support Normal and Dialog audio modes but will not support Direct or Night audio modes.

The following values are possible when calling the HA media player select_sound_mode service:

AUDIO_MODE_DIALOG or Dialog
Dialogue mode improves the clarity of dialogue and vocals in movies, TV programs and podcasts by adjusting the tonal balance of the system.
AUDIO_MODE_DIRECT or Direct
No optimizations made; the audio is directly from the source.
AUDIO_MODE_NIGHT or Night
Audio Mode for a nighttime environment.
AUDIO_MODE_NORMAL or Normal
Audio Mode for a normal environment.
AUDIO_MODE_UNSPECIFIED
Audio Mode is not specified.

For example:

service: media_player.select_sound_mode
data:
  sound_mode: AUDIO_MODE_DIALOG
target:
  entity_id: media_player.bose_soundtouch_300

The sound mode title can also be used:

service: media_player.select_sound_mode
data:
  sound_mode: Dialog
target:
  entity_id: media_player.bose_soundtouch_300

`select_source`

The select_source service call was extended to support source selection specific to the SoundTouch device.

For sources that do not require a station or location value (e.g. AUX, BLUETOOTH, etc) the switch happens immediately.

For sources that require a station or location (e.g. PANDORA, SPOTIFY, TUNEIN, etc), a lookup is performed on the recent stations activity to retrieve the last station that was played on that source. Note that the source WILL NOT SWITCH if there are no recently played items for that source.

Use the following as guidelines when selecting sources:

select only a named source (e.g. standard behavior for backward compatibility).
Your service call would look like this:

service: media_player.select_source
data:
  source: BLUETOOTH
target:
  entity_id: media_player.soundtouch_10

Note that the AUX source requires the source account value to be specified, like so:

service: media_player.select_source
data:
  source: AUX:AUX
target:
  entity_id: media_player.soundtouch_10

select a source by title name. This allows you to select a source by its UI-friendly title name. The title names are listed in the device configuration options dialog. Your service call would look like this:
```
service: media_player.select_source
data:
  source: 'Pandora (yourpandorauserid)'
target:
  entity_id: media_player.soundtouch_10
```
select a named source with a sourceAccount value.
This is required functionality for specific SoundTouch devices (e.g. ST-300) that require you to supply a sourceAcccount value when switching the source. For example, for selecting a PRODUCT:TV source:
```
service: media_player.select_source
data:
  source: PRODUCT:TV
target:
  entity_id: media_player.soundtouch_300
```
or selecting a PANDORA:YourPandoraUserId source with a user-id sourceAccount value:
```
service: media_player.select_source
data:
  source: PANDORA:MyPandoraUserId
target:
  entity_id: media_player.soundtouch_300
```
specify LOCAL to call the SoundTouch SelectLocalSource service.
This is required functionality for specific SoundTouch devices that utilize a LOCAL source. Note that the LOCAL source does not show up in the list of sources provided by the device (via the /sources service). The integration will issue a call to the /selectLocalService service via the SoundTouch webservices api to select the proper source.
Your service call would look like this:
```
service: media_player.select_source
data:
  source: LOCAL
target:
  entity_id: media_player.soundtouch_300
```
specify LASTSOURCE to call the SoundTouch SelectLastSource service.
This allows you to select the previous source that was selected prior to the currently selected source. The integration will issue a call to the /selectLastSource service via the SoundTouch webservices api to select the proper source.
Your service call would look like this:
```
service: media_player.select_source
data:
  source: LASTSOURCE
target:
  entity_id: media_player.soundtouch_300
```
specify LASTSOUNDTOUCHSOURCE to call the SoundTouch SelectLastSoundTouchSource service.
This allows you to select the previous SoundTouch source that was selected prior to the currently selected source. The integration will issue a call to the /selectLastSoundTouchSource service via the SoundTouch webservices api to select the proper source.
Your service call would look like this:
```
service: media_player.select_source
data:
  source: LASTSOUNDTOUCHSOURCE
target:
  entity_id: media_player.soundtouch_300
```

`shuffle_set` (Shuffle Mode)

The integration supports the HA media player SHUFFLE_SET feature, which allow you to shuffle tracks in a playlist for random play order.

Note that not all sources or media support shuffle functions.

For example:

# enable shuffle mode (on).
service: media_player.shuffle_set
data:
  shuffle: true
target:
  entity_id: media_player.bose_st10_1

# disable shuffle mode (off).
service: media_player.shuffle_set
data:
  shuffle: false
target:
  entity_id: media_player.bose_st10_1

`sound_mode_list`

The sound_mode_list state value will display the sound modes that are available for the device (see Figure 1 below). The integration will issue a call to the /audiodspcontrols service via the SoundTouch webservices api (supportedaudiomodes attribute) to retrieve the list of supported sound modes.

Note that not all SoundTouch devices support the /audiodspcontrols service. If not supported, the sound_mode_list will display a "not capable" status.

The sound_mode in the list can be specified as-is on a call to the media_player.select_sound_mode service.
For example:

service: media_player.select_sound_mode
data:
  sound_mode: AUDIO_MODE_DIALOG
target:
  entity_id: media_player.bose_soundtouch_300

Or by using the sound mode title value:

service: media_player.select_sound_mode
data:
  sound_mode: Dialog
target:
  entity_id: media_player.bose_soundtouch_300

`source_list`

As of version 1.0.23, the source_list state value will now display a unique source title (see Figure 1 below). The list is also sorted alphabetically, to make it easier to find a source in the list. The list is updated in real-time (if websocket support is enabled) as sources are added and removed.

The source in the list can be specified as-is on a call to the media_player.select_source service.
For example:

service: media_player.select_source
data:
  source: PRODUCT:TV
target:
  entity_id: media_player.soundtouch_300

State Custom Variables

The following custom state variables have been added (see Figure 1 below):

soundtouchplus_nowplaying_isadvertisement: true / false true if the currently playing source is playing an advertisment; otherwise, false.
note that not all sources support advertisement detection; AFAIK, only Pandora supports this feature.
soundtouchplus_nowplaying_isfavorite: true / false true if the currently playing source content is marked as a favorite; otherwise, false.
note that not all sources support favorites; AFAIK, only Pandora supports this feature.
soundtouchplus_source: PRODUCT:TV
current source and sourceAccount selection.
soundtouchplus_sound_mode: AUDIO_MODE_DIALOG
current selected sound_mode value, or "not capable" if /audiodspcontrols service not supported.
soundtouchplus_tone_bass_level: 25
current bass level (within bass_level_range), or "not capable" if device does not support /audioproducttonecontrols service.
soundtouchplus_tone_bass_level_range: Min=-100, Max=100
current bass level range supported, or "not capable" if device does not support /audioproducttonecontrols service.
soundtouchplus_tone_treble_level: 25
current treble level (within treble_level_range), or "not capable" if device does not support /audioproducttonecontrols service.
soundtouchplus_tone_treble_level_range: Min=-100, Max=100
current treble level range supported, or "not capable" if device does not support /audioproducttonecontrols service.

State Enhancement Screenshot

Figure 1 - Developer Tools, State Display, ST-300
Unique values are hi-lited out for privacy.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Media Player Service Enhancements

`join` / `unjoin` (Zone Support)

`media_seek` (Seek Support)

`play_media`

Example YAML - Spotify

`repeat_set` (Repeat Mode)

`select_sound_mode`

`select_source`

`shuffle_set` (Shuffle Mode)

`sound_mode_list`

`source_list`

State Custom Variables

State Enhancement Screenshot

Clone this wiki locally

Media Player Service Enhancements

join / unjoin (Zone Support)

media_seek (Seek Support)

play_media

Example YAML - Spotify

repeat_set (Repeat Mode)

select_sound_mode

select_source

shuffle_set (Shuffle Mode)

sound_mode_list

source_list

State Custom Variables

State Enhancement Screenshot

Clone this wiki locally

`join` / `unjoin` (Zone Support)

`media_seek` (Seek Support)

`play_media`

`repeat_set` (Repeat Mode)

`select_sound_mode`

`select_source`

`shuffle_set` (Shuffle Mode)

`sound_mode_list`

`source_list`