-
Notifications
You must be signed in to change notification settings - Fork 1
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
- Source Select
- 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
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
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:
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.
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)"
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
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
orDialog
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
orDirect
No optimizations made; the audio is directly from the source. -
AUDIO_MODE_NIGHT
orNight
Audio Mode for a nighttime environment. -
AUDIO_MODE_NORMAL
orNormal
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
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 asourceAcccount
value when switching the source. For example, for selecting aPRODUCT: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 SoundTouchSelectLocalSource
service.
This is required functionality for specific SoundTouch devices that utilize aLOCAL
source. Note that theLOCAL
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 SoundTouchSelectLastSource
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 SoundTouchSelectLastSoundTouchSource
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
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
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
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
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_polling_enabled
: true / false
true if device polling is enabled; otherwise, false. This can be a temporary condition, in that polling will be enabled if websocket support is enabled and the connection is lost / has not been re-established. -
soundtouchplus_presets_lastupdated
: integer
epoch date when the preset list was last updated. -
soundtouchplus_recents_cache_enabled
: true / false
true if the recently played items cache is enabled; otherwise, false if disabled. -
soundtouchplus_recents_cache_max_items
: integer
maximum number of items to keep in the recently played cache file. -
soundtouchplus_recents_cache_lastupdated
: integer
epoch date when the recently played list cache was last updated. -
soundtouchplus_recents_lastupdated
: integer
epoch date when the recently played list was last updated. -
soundtouchplus_source
: PRODUCT:TV
current source and sourceAccount selection. -
soundtouchplus_sound_mode
: AUDIO_MODE_DIALOG
current selected sound_mode value, or "not capable" if device does not support the audio dsp controls service. -
soundtouchplus_tone_bass_level
: 25
current bass level (within bass_level_range), or "not capable" if device does not support the audio product tone controls service. -
soundtouchplus_tone_bass_level_range
: Min=-100, Max=100
current bass level range supported, or "not capable" if device does not support the audio product tone controls service. -
soundtouchplus_tone_treble_level
: 25
current treble level (within treble_level_range), or "not capable" if device does not support the audio product tone controls service. -
soundtouchplus_tone_treble_level_range
: Min=-100, Max=100
current treble level range supported, or "not capable" if device does not support the audio product tone controls service. -
soundtouchplus_websockets_enabled
: true / false
true if websocket support is enabled for the device; false if device does not support websockets or if websockets were disabled during device setup.
Figure 1 - Developer Tools, State Display, ST-300
Unique values are hi-lited out for privacy.