public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Documentation] Markdown improvements t to z (#14371)

Browse Source 
* Apply markdown fixes for bindings with letter _t_
* Apply markdown fixes for bindings with letter _u_
* Apply markdown fixes for bindings with letter _v_
* Apply markdown fixes for bindings with letter _w_
* Apply markdown fixes for bindings with letter _x_
* Apply markdown fixes for bindings with letter _y_
* Apply markdown fixes for bindings with letter _z_

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
2023-04-11 12:54:54 +02:00
committed by GitHub
parent 69a09ed825
commit ce3f673380
54 changed files with 1655 additions and 1778 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
bundles/org.openhab.binding.upnpcontrol/README.md
View File

@@ -14,7 +14,6 @@ Controls are available to control the playback of the media on the renderer.
Currently playing media can be stored as a favorite.
Each discovered renderer will also be registered as an openHAB audio sink.
## Supported Things
Two thing types are supported, a server thing, `upnpserver`, and a renderer thing, `upnprenderer`.
@@ -24,19 +23,16 @@ A second test set included a [TVersity Media Server](http://tversity.com/).
It complies with part of the UPnP AV Media standard, but has not been verified to comply with the full specification.
Tests have focused on the playback of audio, but if the server and renderer support it, other media types should play as well.
## Binding Configuration
The binding has one configuration parameter, `path`.
This is used as the disk location for storing and retrieving playlists and favorites.
The default location is `$OPENHAB_USERDATA/upnpcontrol`.
## Discovery
UPnP media servers and media renderers in the network will be discovered automatically.
## Thing Configuration
Both the `upnprenderer` and `upnpserver` thing require a configuration parameter, `udn` (Universal Device Name).
@@ -54,48 +50,47 @@ It should not be changed in normal circumstances.
Additionally, a `upnpserver` device has the following optional configuration parameters:
* `filter`: when true, only list content that is playable on the renderer, default is `false`.
- `filter`: when true, only list content that is playable on the renderer, default is `false`.
* `sortCriteria`: sort criteria for the titles in the selection list and when sending for playing to a renderer.
- `sortCriteria`: sort criteria for the titles in the selection list and when sending for playing to a renderer.
The criteria are defined in UPnP sort criteria format, examples: `+dc:title`, `-dc:creator`, `+upnp:album`.
Support for sort criteria will depend on the media server.
The default is to sort ascending on title, `+dc:title`.
* `browseDown`: when browse or search results in exactly one container entry, iteratively browse down until the result contains multiple container entries or at least one media entry, default is `true`.
- `browseDown`: when browse or search results in exactly one container entry, iteratively browse down until the result contains multiple container entries or at least one media entry, default is `true`.
* `searchFromRoot`: always start search from root instead of the current id, default is `false`.
- `searchFromRoot`: always start search from root instead of the current id, default is `false`.
A `upnprenderer` has the following optional configuration parameters:
* `seekStep`: step in seconds when sending fast forward or rewind command on the player control, default 5s.
- `seekStep`: step in seconds when sending fast forward or rewind command on the player control, default 5s.
* `notificationVolumeAdjustment`: volume adjustment from current volume in percent (range -100 to +100) for notifications when no volume is set in `playSound` command, default 10.
- `notificationVolumeAdjustment`: volume adjustment from current volume in percent (range -100 to +100) for notifications when no volume is set in `playSound` command, default 10.
* `maxNotificationDuration`: maximum duration for notifications (default 15s), no maximum duration when set to 0s.
- `maxNotificationDuration`: maximum duration for notifications (default 15s), no maximum duration when set to 0s.
The full syntax for manual configuration is:
```
```java
Thing upnpcontrol:upnpserver:<serverId> [udn="<udn of media server>", refresh=<polling interval>, filter=<true/false>, sortCriteria="<sort criteria string>", browseDown=<true/false>, searchFromRoot=<true/false>, responseTimeout=<UPnP timeout in milliseconds>]
Thing upnpcontrol:upnprenderer:<rendererId> [udn="<udn of media renderer>", refresh=<polling interval>, notificationVolumeAdjustment=<signed percent>, maxNotificationDuration=<duration in seconds>, seekStep=<step>, responseTimeout=<UPnP timeout in milliseconds>]
```
## Channels
### `upnpserver`
The `upnpserver` has the following channels (item type and access mode indicated in brackets):
* `upnprenderer` (String, RW): The renderer to receive media content for playback.
- `upnprenderer` (String, RW): The renderer to receive media content for playback.
The channel allows selecting from all discovered media renderers.
This list is dynamically adjusted as media renderers are being added/removed.
* `currenttitle` (String, R): Current title of media container or entry ready for playback.
- `currenttitle` (String, R): Current title of media container or entry ready for playback.
* `browse` (String, RW): Browse and serve media content, current ID of media container or entry ready for playback.
- `browse` (String, RW): Browse and serve media content, current ID of media container or entry ready for playback.
The browsing will start at the top of the content directory tree and allows you to go down and up (represented by ..) in the tree.
The list of containers (directories) and media entries for selection in the content hierarchy is updated dynamically when selecting a container or entry.
@@ -107,7 +102,7 @@ The `upnpserver` has the following channels (item type and access mode indicated
The `browseDown` configuration parameter influences the result in such a way that, for `browseDown = true`, if the result only contains exactly one container entry, the result will be the content of the container and not the container itself.
* `search` (String, W): Search for media content on the server.
- `search` (String, W): Search for media content on the server.
Search criteria are defined in UPnP search criteria format.
Examples: `dc:title contains "song"`, `dc:creator contains "SpringSteen"`, `unp:class = "object.item.audioItem"`, `upnp:album contains "Born in"`.
@@ -120,32 +115,32 @@ The `upnpserver` has the following channels (item type and access mode indicated
The `browseDown` configuration parameter influences the result in such a way that, for `browseDown = true`, if the result only contains exactly one container entry, the result will be the content of the container and not the container itself.
* `playlistselect` (String, W): Select a playlist from the available playlists currently saved on disk.
- `playlistselect` (String, W): Select a playlist from the available playlists currently saved on disk.
This will also update `playlist` with the selected value.
* `playlist` (String, RW): Name of existing or new playlist.
- `playlist` (String, RW): Name of existing or new playlist.
* `playlistaction` (String, W): action to perform with `playlist`.
- `playlistaction` (String, W): action to perform with `playlist`.
Possible command options are:
* `RESTORE`: restore the playlist from `playlist`.
- `RESTORE`: restore the playlist from `playlist`.
If the restored playlist contains content from the current server, this content will update the `browse` command option list.
Note that playlists can contain a mix of media entries and container references.
All media in the result list, playable on the current selected `upnprenderer` channel, are automatically queued to the renderer as next media for playback.
* `SAVE`: save the current `browse` command option list into `playlist`.
- `SAVE`: save the current `browse` command option list into `playlist`.
If `playlist` already exists, it will be overwritten.
* `APPEND`: append the current `browse` command option list to `playlist`.
- `APPEND`: append the current `browse` command option list to `playlist`.
If `playlist` does not exist yet, a new playlist will be created.
* `DELETE`: delete `playlist` from disk and remove from `playlistselect` command option list.
- `DELETE`: delete `playlist` from disk and remove from `playlistselect` command option list.
A number of convenience channels replicate the basic control channels from the `upnprenderer` thing for the currently selected renderer on the `upnprenderer` channel.
These channels are `volume`, `mute` and `control`.
@@ -191,7 +186,6 @@ Examples of these are:
| `rfvolume` | Dimmer | RW | playback front right volume |
| `rfmute` | Switch | RW | playback front right mute |
## Audio Support
Two audio sinks are registered for each media renderer.
@@ -207,17 +201,16 @@ The `maxNotificationDuration` configuration parameter of the renderer will limit
Normal playing will resume after the notification has played or when the maximum notification duration has been reached, whichever happens first.
Longer sounds or streams will be cut off.
## Managing a Playback Queue
There are multiple ways to serve content to a renderer for playback.
* Directly provide a URI on the `URI` channel or through `playSound` or `playStream` actions:
- Directly provide a URI on the `URI` channel or through `playSound` or `playStream` actions:
Playing will start immediately, interrupting currently playing media.
No metadata for the media is available, therefore will be provided in the media channels for metadata (e.g. `title`, `album`, ...).
* Content served from one or multiple `upnpserver` servers:
- Content served from one or multiple `upnpserver` servers:
This is done on the `upnpserver` thing with the `upnprenderer` set the the renderer for playback.
The media at any point in time in the `upnpserver browse` option list (result from browse, search or restoring a playlist), will be queued to the `upnprenderer` for playback.
@@ -228,7 +221,7 @@ There are multiple ways to serve content to a renderer for playback.
The `upnprenderer` will use that queue until it is replaced by another queue from the same or another `upnpserver`.
Note that querying the content hierarchy on the `upnpserver` will update the `upnpserver browse` option list each time, and therefore the queue on the `upnprenderer` will be updated each time as long as `upnprenderer` is selected on `upnpserver`.
* Selecting a favorite or playlist on the renderer.
- Selecting a favorite or playlist on the renderer.
Playback of the favorite or playlist will start immediately.
@@ -277,7 +270,6 @@ That way, it is possible to combine multiple sources for playback.
When selecting a playlist on a renderer, the playlist will be queued for playback, replacing the current queue.
Playback will start immediately.
## Using Search
Searching content on a media server may take a lot of time, depending on the functionality and the performance of the media server.
@@ -287,12 +279,12 @@ Rather than searching for individual items, it is therefore often better to sear
For example:
* `upnp:class derivedfrom "object.item.audioItem.musicTrack" and dc:title contains "Fight For Your Right"` would search for all music tracks with "Fight For Your Right" in the title.
- `upnp:class derivedfrom "object.item.audioItem.musicTrack" and dc:title contains "Fight For Your Right"` would search for all music tracks with "Fight For Your Right" in the title.
This search is potentially slow.
* `dc:title contains "Evening" and upnp:class = "object.container.playlistContainer"` would search for all playlists with "Evening" in the name.
- `dc:title contains "Evening" and upnp:class = "object.container.playlistContainer"` would search for all playlists with "Evening" in the name.
* `dc:title = "Donnie Darko" and upnp:class = "object.container.playlistContainer"` would search for a playlist with a specific name.
- `dc:title = "Donnie Darko" and upnp:class = "object.container.playlistContainer"` would search for a playlist with a specific name.
With the last example, if the `browseDown` configuration parameter is `true`, the result will not be the playlist, but the content of the playlist.
This allows immediately starting a play command without having to browse down to the first result of the list (the unique container).
@@ -307,14 +299,14 @@ This option is helpful if you do not want to limit search to a selected containe
BasicUI has a number of limitations that impact the way some of the channels can be used from it:
* BasicUI does not support dynamic refreshing of the selection list in the `upnpserver` channels `renderer`, `browse`, `playlistselect` and in the `upnprenderer` channel `favoriteselect`.
- BasicUI does not support dynamic refreshing of the selection list in the `upnpserver` channels `renderer`, `browse`, `playlistselect` and in the `upnprenderer` channel `favoriteselect`.
A refresh of the browser will be required to show the adjusted selection list.
* The `upnpserver search` channel requires input of a string to trigger a search.
- The `upnpserver search` channel requires input of a string to trigger a search.
The `upnpserver playlist` channel and `upnprenderer favorite` channel require input of a string to set a playlist or favorite.
This cannot be done with BasicUI, but can be achieved with rules.
* The player control in BasicUI does not support fast forward or rewind.
- The player control in BasicUI does not support fast forward or rewind.
None of these are limitations when using the main UI.
@@ -322,14 +314,14 @@ None of these are limitations when using the main UI.
.things:
```
```java
Thing upnpcontrol:upnpserver:mymediaserver [udn="0ec457ae-6c50-4e6e-9012-dee7bb25be2d", refresh=120, filter=true, sortCriteria="+dc:title"]
Thing upnpcontrol:upnprenderer:mymediarenderer [udn="538cf6e8-d188-4aed-8545-73a1b905466e", refresh=600, seekStep=1]
```
.items:
```
```java
Group MediaServer <player>
Group MediaRenderer <player>
@@ -370,7 +362,7 @@ String PlaylistAction "Playlist Action" (MediaServer) {channel=
.sitemap:
```
```perl
Slider item=Volume
Switch item=Mute
Switch item=Loudness
@@ -408,7 +400,7 @@ Switch item=PlaylistAction
Audio sink usage examples in rules:
```
```java
playSound(“doorbell.mp3”)
playStream("upnpcontrol:upnprenderer:mymediarenderer", "http://icecast.vrtcdn.be/stubru_tijdloze-high.mp3”)
playSound("upnpcontrol:upnprenderer:mymediarenderer-notify", "doorbell.mp3", new PercentType(80))