[upnpcontrol] Add semantic tags

[andrewfg]

This PR adds semantic tags.

Note: it is rather tentative since the Property tags of some channels are not self evident e.g. 'PlayList' and 'Track' => Perhaps we need to add some more properties?

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

[andrewfg]

Pinging @mherwege / @jimtng apropos missing properties..

[jimtng]

• I think the following shouldn't be given semantic tags, or at the very least, definitely not Channel
  • uri
  • favoriteselect
  • album
  • albumart
  • creator
  • publisher
  • genre
  • tracknumber
  • trackduration
  • trackposition
  • reltrackposition

This should not be set to MediaControl:

• upnprenderer
• browse
• playlistselect
• playlist

[jimtng]

I don't think we need to apply semantic tags to every single channel. @rkoshak wdyt?

[andrewfg]

the following shouldn't be given semantic tags, or at the very least, definitely not Channel

Yeah. I was wondering if we should add Property.Track ??

This should not be set to MediaControl

ditto Property.PlayList ??

[jimtng]

Yeah. I was wondering if we should add Property.Track ??

If we were to do so, IMO, only one channel should receive this property.
Having multiple channels with the same property seem counter-intuitive and defeats the purpose of semantic tagging.

As I understand it, Semantic tagging is to give meaning to the data, but if you have multiple "items" with the same semantic tag, it is not helpful at all for an external "entity" to "see" and understand your "Thing". If I want to advance the track, which item should I change if there are multiple "Track" channels?

Ditto Playlist / mediacontrol etc.

[andrewfg]

@jimtng you probably misunderstood me. On a player the current Track has many sub Track_Properties -- Title, Genre, Composer, Artist, Album, Duration, etc..

[jimtng]

Title, Genre, Composer, Artist, Album, Duration, etc..

I agree, these could all get the same property.

I'd propose:
Point: Track, Property: Information/Data/Details

And set the Track Number to Point: Track, Property: Number/Sequence

[jimtng]

We should probably also look at Plex / other media-player stuff like Echo, Chromecast, TVs? Receivers, Sonos?, they'd all have similar stuff

[andrewfg]

I'd propose: Point: Track
Property: Information/Data/Details

I don't think Track is a Point.

I would rather suggest Point.Info + Property.TrackInfo (or Point.Status + Property.TrackInfo ..)

We should probably also look at Plex / other media-player stuff

Agreed. We just need to get it right for the first one, and then it is essentially copy/paste.

[jimtng]

Point.Status + Property.TrackInfo sounds fine to me.

[rkoshak]

I don't think we need to apply semantic tags to every single channel. @rkoshak wdyt?

If it's a Channel that is unlikely to be something exposed to end users of the home OH is controlling it doesn't need a tag.

But that raises the question of whether the binding author has enough information to make that choice on behalf of the end user and which user should we impose the extra step on, those who do want to expose these to the end user (and therefore they need to select a tag on their own) or those who do not (and therefore they have to remove the auto-suggested tag).

I don't have a good answer. It feels better to always recommend a tag and let the user remove them later. But that's only because of consistency.

Overall, my rule of thumb is only about 60% of Items actually belong in the semantic model. But I'm pretty minimal, so maybe 75-80% for most users.

I think the following shouldn't be given semantic tags

I would expect several of those to be something exposed to the end user like artist, album art, etc. If you'd want to see it in MainUI's Overview tabs, you need to tag it with something.

Having multiple channels with the same property seem counter-intuitive and defeats the purpose of semantic tagging.

Tags are there to provide a little extra bit of information about what an Item represents. It is not meant to uniquely identify an Item. It's perfectly acceptable to have more than one Channel of a Thing with the same semantic Property tags.

If I want to advance the track, which item should I change if there are multiple "Track" channels?

The one with the Point tag that indicates it's something you can control. Just like temperature:

• Measurement/Temperature = what's the current temperature
• Setpoint/Temperature = control the desired temperature

So I'd expect something like "trackPosition" to be "Status/Track" or "Position/Track" where "trackDuration" to be "Measurement/Track" or "Status/Track" or something like that. But they are all track Properties. I don't have any problem with having these extra sub-track property tags, but I do want to point out that property tags never stand alone and the tags alone are not there to uniquely identify an Item.

I don't think Track is a Point.

I strongly agree. "Track" isn't a verb nor something that can be converted to a verb (in the meaning we are using it here, we are not hunting). It's a noun.

[andrewfg]

@rkoshak / @jimtng / @jlaur / @lsiepel so how shall we proceed here? Whatever we decide here for this binding would set the precedent for all other bindings that play audio or video media. The issues are how to tag channels that inform the state of the "now playing" track or clip. To be specific:

• Tags describing "human" attributes of tracks e.g. Album, Artist, Composer, Title, Genre, Track Number etc.
• Tags describing "physical" attributes of tracks e.g. Duration, Sample Rate, Channels (mono/stereo/5.1), Medium (mp3, flac) etc.
• Tag(s) describing "state of play" attributes of tracks e.g. Time-position, Time-to-go, Play/Pause etc.

I think we have two options..

1. Tag all such data as Point.Status -- eventually in conjunction with (a yet to be defined new) Property.TrackInfo (or simply Property.Info) tag.
2. Do not tag any such channels.

=> So please cast your votes for 1. or 2. above (personally I vote for 1.)..

[rkoshak]

Option 1 makes sense. 2 doesn't bother me either.

[mherwege]

1 for me. I would stick to Property.Info at first. That can be relevant in non-mediaplayer context as well (e.g. service status messages for car bindings).

[andrewfg]

See openhab/openhab-core#4745

[andrewfg]

@jimtng / @rkoshak based on feedback from other PRs in the pipeline, I have done the following:

1. applied Status;Info to all track metadata channels
2. applied Control:Progress to track position controls
3. removed a couple of tags at your suggestion
4. changed some xyz:MediaControl to xyz:Mode

I am therefore fairly confident that a) this PR is ready to be merged, and b) that it sets a kind of benchmark for other media players still in the pipeline.

[lsiepel]

When looking at this i find it a bit hard to match the statement from @rkoshak

Tags are there to provide a little extra bit of information about what an Item represents.

with the applied tags Status/Info in this PR.

I totally agree that the tags have to add value.

To me these tags are too generic, about all channels in all bindings could be tagged with this.
I would prefer to add more details. Maybe some like Status/TrackInfo or maybe even be more specific. like MusicTrackInfo or VideoTrackInfo ?

[andrewfg]

TrackInfo was my original suggestion for the new property when we added it to OH core. But others suggested to make it more generic so it could cover other potential use cases.

EDIT: to be fair the Info tag does supply info that the tag is about (static) information rather than (active) state.

Note: if we would change the tag to TrackInfo we would need to do that in Core and possibly revisit other PRs in addons. Just a comment; not a reason for not doing it though..

EDIT 2: we could also add more explanation to the tag description text in my other PR in core on that topic.

[lsiepel]

As the info is very specific about music and it is used in many bindings.
I would be interested in core maintainers view on this topic. If you ask me, i would opt for a more detailed tag.

[andrewfg]

..and/or we we could just change the description (far right hand column)

https://github.com/openhab/openhab-core/blob/b94c25a5b847404bb393461aad3fb7794f986aee/bundles/org.openhab.core.semantics/model/SemanticTags.csv#L71

..and this..

https://github.com/openhab/openhab-docs/blob/1bbe162089656e4e37e15458872e77d06aacd668/developers/bindings/thing-xml.md?plain=1#L1027

[lsiepel]

https://github.com/openhab/openhab-core/blob/b94c25a5b847404bb393461aad3fb7794f986aee/bundles/org.openhab.core.semantics/model/SemanticTags.csv#L71

https://github.com/openhab/openhab-docs/blob/1bbe162089656e4e37e15458872e77d06aacd668/developers/bindings/thing-xml.md?plain=1#L1027

IMO all should be aligned.

1. The CSV (very generic text) does not match the XML (specific use described for the tag)
2. The description from the XML is perfect, but the tag does not match that description. At first the tag should be self-explenatory. Maybe MediaInfo is a better match.

i know you might have been told otherwise before, so better that @jimtng, @jlaur or others join the discussion before you adapt anything.

[andrewfg]

..just for info the word “metadata” is often used to describe what (I think) we mean by the Info property..

[andrewfg]

@lsiepel #18664 included several media player and media service addons for which the tagging was discussed and agreed. This PR for this addon was a precursor to #18664 and also relates to a media player / service addon. So since #18664 was finally agreed, I think we can now merge this one too, please.

[lsiepel]

Thanks, LGTM.