Caution

This is the documentation for the current development branch of the CometVisu. It is possible that some of the described features are not yet available in the current release.

Also there might be lots of errors in this documentation as some parts of the content have been translated by an online translation service.

The media-player widget

Author: Tobias Bräutigam

Available since: 2022

Description

The media player widget provides the possibility to control a music player. The widget shows the current song, offers the possibility to start or stop playing, to skip a song forward or backward. It also shows how much of the current song has already been played and allows to adjust the volume.

The widget uses buttons for start/stop, skip forward and backward and a slider for the volume.

No background image

With background image

<cv-media-player>
    <cv-address slot="subtitleAddress" transform="DPT:24.001" mode="read">1/4/0</cv-address>
    <cv-address slot="titleAddress" transform="DPT:24.001" mode="read">1/4/1</cv-address>
    <cv-address slot="previousAddress" transform="DPT:1.001" value="0" mode="write">1/4/2</cv-address>
    <cv-address slot="playPauseAddress" transform="DPT:1.001">1/4/3</cv-address>
    <cv-address slot="playTimeAddress" transform="DPT:5.010" mode="read" target="progress">1/4/4</cv-address>
    <cv-address slot="durationAddress" transform="DPT:5.010" mode="read" target="store:duration">1/4/5</cv-address>
    <cv-address slot="nextAddress" transform="DPT:1.001" value="1" mode="write">1/4/2</cv-address>
    <cv-address slot="volumeAddress" transform="DPT:5.001">1/4/6</cv-address>
    <cv-address slot="tileAddress" transform="DPT:24.001" mode="read" target="background-image">1/4/7</cv-address>
    <cv-address slot="tileAddress" transform="DPT:1.001" mode="read" target="show-exclude">1/4/8</cv-address>
</cv-media-player>

The widget uses the following addresses:

song title	slot="titleAddress"
album / artist	slot="subtitleAddress"
previous song	slot="previousAddress"
start / stop	slot="playPauseAddress"
current playtime	slot="playTimeAddress"
total playtime	slot="durationAddress"
next song	slot="nextAddress"
volume	slot="volumeAddress"
widget	slot="tileAddress"

The addresses for the widget itself slot="tileAddress" are optional and allow some special features using the target attribute.

For example, the visibility of the widget can be controlled to hide it when the music player is not available. As shown in the example, the widget would be removed if the value “0” were received on the address “1/4/8”. If the value “1” is received, it will be visible again. This behavior is activated by target="show-exclude".

It is also possible to show the cover of the currently played song as the background image of the tile. This is done with the entry from the example <cv-address slot="tileAddress" transform="DPT:24.001" mode="read" target="background-image">1/4/7</cv-address>. The address must either provide the URL of the image that the CometVisu can load, or the image directly as a Data-URI. The latter will probably not be possible with the KNX backend due to the restrictions on the amount of data that can be sent on the KNX bus, but e.g. the openHAB backend can deliver such data.

The media player widget supports an optional menu by adding one or more <cv-menu-item slot="menu"> elements.

<cv-media-player>
   <cv-menu-item slot="menu" name="Favoriten" action="popup" icon="ri-star-line">...</cv-menu-item>
   <cv-menu-item slot="menu" name="Stumm" action="toggleState" icon="ri-volume-mute-line">...</cv-menu-item>
    ...
</cv-media-player>

Allowed attributes in the media player element

Element	Attribute
	Name	Content	Description
cv-media-player	progress-mapping	string	Map the bus value to a value between 0 and 100 to display a progress mapping
	mapping	string	Map the bus value to a different value, text or symbol for displaying. See also mapping
	size	button, 0.5x0.5, 1x0.5, 1x1, 2x1, 2x1.5, 1x2, 2x2, 2x4 or 4x2	Size of the tile in {columns}x{rows}, 1x1 is the default size.
	visible-on	mobile or desktop	Controls this element’s visibility by screen size.
	class	string	Add this value to the CSS class so that it can be formatted by a user provided style sheet.
	style	string	Custom CSS style rules for this widget.

Allowed child elements and their attributes

Element	Attribute
Structure	Name	Content	Description
cv-media-player span	slot	title
	tr	true or false	Defines that the text content of this element should be translated.

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-address	slot	subtitleAddress, titleAddress, previousAddress, playPauseAddress, playTimeAddress, durationAddress, nextAddress, volumeAddress or tileAddress
	transform	string	Defines the datatype in the backend, e.g. DPT:1.001 for KNX datapoint type 1.001.
	mode	disable, read, write or readwrite	Defines if this address is only used to read, write, both readwrite or none of them ``disable`.
	value	string	Fixed value sent to this address.
	on	click, down or up	Event on which a value should be sent to this address (only useful in mode=``write or readwrite`), also needs ``value.
	target	string	Target in the parent widget the value if this address should be use for. The possible values depend on the parent widget.
	format-pos	decimal	Position for format string when multiple addresses are used.
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	selector	string	Only MQTT: JSON selector
	backend	string	Optional name of the backend this address belongs to.
	mapping	string	Map the bus value to a different value, text or symbol for displaying. See also mapping
	format	string	Formatting of the value (printf syntax).
	delay	positiveInteger	Optional delay in milliseconds that a write-request to this address is delayed.
	send-mode	on-change or always	Usually the elements that are using this address receive an update-event only when that value hast changed (on-change). This check can be disabled always to send the update-event every time when a new value has been received from the backend.

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-menu-item	name	string	Name of the menu entry.
	icon	string	Icon of the menu entry.
	action	popup or toggleState	The action that is executed when this menu item has been clicked.
cv-media-player cv-menu-item cv-address	transform	string	Transformation of the bus system value to be shown.
	mode	disable, read, write or readwrite	“disable” deactivates the communication, “read” will only fetch data from the backend, “write” will only write to it and an address with “readwrite” will be both, read from and written to.
	variant	string
	format-pos	decimal	Position for format string when multiple addresses are used.
	selector	string	Only MQTT: JSON selector
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	ignore-error	true or false	Only MQTT: ignore decode errors.
cv-media-player cv-menu-item cv-address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-popup	modal	true or false	Disables the background while the popup is open.
	fullscreen	true or false	Open the popup in fullscreen mode.
	title	string	Headline of this popup.
	auto-close-timeout	integer	Time in seconds when the popup is automatically closed.
	visible-on	mobile or desktop	Controls this element’s visibility by screen size.
	class	string	Add this value to the CSS class so that it can be formatted by a user provided style sheet.
	style	string	Custom CSS style rules for this widget.
cv-media-player cv-popup custom #text		string
cv-media-player cv-popup cv-address	transform	string	Transformation of the bus system value to be shown.
	mode	disable, read, write or readwrite	“disable” deactivates the communication, “read” will only fetch data from the backend, “write” will only write to it and an address with “readwrite” will be both, read from and written to.
	variant	string
	format-pos	decimal	Position for format string when multiple addresses are used.
	selector	string	Only MQTT: JSON selector
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	ignore-error	true or false	Only MQTT: ignore decode errors.
cv-media-player cv-popup cv-address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-address	transform	string	Defines the datatype in the backend, e.g. DPT:1.001 for KNX datapoint type 1.001.
	mode	disable, read, write or readwrite	Defines if this address is only used to read, write, both readwrite or none of them ``disable`.
	value	string	Fixed value sent to this address.
	on	click, down or up	Event on which a value should be sent to this address (only useful in mode=``write or readwrite`), also needs ``value.
	target	string	Target in the parent widget the value if this address should be use for. The possible values depend on the parent widget.
	format-pos	decimal	Position for format string when multiple addresses are used.
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	selector	string	Only MQTT: JSON selector
	backend	string	Optional name of the backend this address belongs to.
	mapping	string	Map the bus value to a different value, text or symbol for displaying. See also mapping
	format	string	Formatting of the value (printf syntax).
	delay	positiveInteger	Optional delay in milliseconds that a write-request to this address is delayed.
	send-mode	on-change or always	Usually the elements that are using this address receive an update-event only when that value hast changed (on-change). This check can be disabled always to send the update-event every time when a new value has been received from the backend.
cv-media-player cv-address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-popup	modal	true or false	Disables the background while the popup is open.
	fullscreen	true or false	Open the popup in fullscreen mode.
	title	string	Headline of this popup.
	auto-close-timeout	integer	Time in seconds when the popup is automatically closed.
	visible-on	mobile or desktop	Controls this element’s visibility by screen size.
	class	string	Add this value to the CSS class so that it can be formatted by a user provided style sheet.
	style	string	Custom CSS style rules for this widget.
cv-media-player cv-popup custom #text		string
cv-media-player cv-popup cv-address	transform	string	Transformation of the bus system value to be shown.
	mode	disable, read, write or readwrite	“disable” deactivates the communication, “read” will only fetch data from the backend, “write” will only write to it and an address with “readwrite” will be both, read from and written to.
	variant	string
	format-pos	decimal	Position for format string when multiple addresses are used.
	selector	string	Only MQTT: JSON selector
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	ignore-error	true or false	Only MQTT: ignore decode errors.
cv-media-player cv-popup cv-address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

Element	Attribute
Structure	Name	Content	Description
cv-media-player cv-address	transform	string	Defines the datatype in the backend, e.g. DPT:1.001 for KNX datapoint type 1.001.
	mode	disable, read, write or readwrite	Defines if this address is only used to read, write, both readwrite or none of them ``disable`.
	value	string	Fixed value sent to this address.
	on	click, down or up	Event on which a value should be sent to this address (only useful in mode=``write or readwrite`), also needs ``value.
	target	string	Target in the parent widget the value if this address should be use for. The possible values depend on the parent widget.
	format-pos	decimal	Position for format string when multiple addresses are used.
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	selector	string	Only MQTT: JSON selector
	backend	string	Optional name of the backend this address belongs to.
	mapping	string	Map the bus value to a different value, text or symbol for displaying. See also mapping
	format	string	Formatting of the value (printf syntax).
	delay	positiveInteger	Optional delay in milliseconds that a write-request to this address is delayed.
	send-mode	on-change or always	Usually the elements that are using this address receive an update-event only when that value hast changed (on-change). This check can be disabled always to send the update-event every time when a new value has been received from the backend.
cv-media-player cv-address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic