Skip to content

Add albumArtURI to MusicTrack didl_properties_defs#45

Merged
StevenLooman merged 2 commits intoStevenLooman:masterfrom
RicterZ:fix/music-track-album-art-uri
Mar 17, 2026
Merged

Add albumArtURI to MusicTrack didl_properties_defs#45
StevenLooman merged 2 commits intoStevenLooman:masterfrom
RicterZ:fix/music-track-album-art-uri

Conversation

@RicterZ
Copy link
Contributor

@RicterZ RicterZ commented Mar 15, 2026

Problem

MusicTrack.didl_properties_defs does not include albumArtURI, even though it is a standard UPnP/DLNA metadata field widely used by
music players to display cover art during playback.

Because to_xml() strictly iterates over didl_properties_defs, any value set on album_art_uri is silently dropped during
serialization — it never appears in the generated DIDL-Lite XML. This affects any DLNA controller that sets albumArtURI on a
MusicTrack object, including:

  • Home Assistant (dlna_dmr integration via async_upnp_client)
  • Kodi (noted in the v1.2.0 changelog as a known workaround for parsing, but serialization was never fixed)

The field is already defined on MusicAlbum (container), but was missing from MusicTrack (item).

Fix

Add ("upnp", "albumArtURI", "O") to MusicTrack.didl_properties_defs.

Tested

Verified end-to-end with Home Assistant dlna_dmr → Xiaomi TV (UPnP AVTransport): after this fix, <upnp:albumArtURI> appears correctly
in the CurrentURIMetaData SOAP payload and cover art is displayed on the TV.

albumArtURI is a standard UPnP/DLNA field commonly used by music players
(e.g., Kodi, Home Assistant dlna_dmr) to display cover art during playback.
Without this entry in didl_properties_defs, the field is silently dropped
during to_xml() serialization even when set on the object.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@StevenLooman
Copy link
Owner

Thank you for this PR @RicterZ.

it is a standard UPnP/DLNA metadata field

I don't think this is true. The didl-lite-v2.xsd does not include this property, and therefore it wasn't included in this library when I implemented this library. Please show me the spec supporting this claim.

widely used by music players to display cover art during playback

This is more likely to be true.

Still, why would a track have album art? Surely an album would have it, but a track seems less likely to me.

@codecov-commenter
Copy link

codecov-commenter commented Mar 15, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.60%. Comparing base (549381c) to head (5f3942c).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master      #45   +/-   ##
=======================================
  Coverage   94.60%   94.60%           
=======================================
  Files           3        3           
  Lines         408      408           
  Branches       46       46           
=======================================
  Hits          386      386           
  Misses         12       12           
  Partials       10       10           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@RicterZ
Copy link
Contributor Author

RicterZ commented Mar 16, 2026

Hey @StevenLooman ,

You're right that albumArtURI does not appear in didl-lite-v2.xsd itself. However, it is defined in the companion upnp.xsd schema (https://upnp.org/schemas/av/upnp.xsd), which didl-lite-v2.xsd delegates to via <xsd:group ref="upnp:upnpForItem"/>. The UPnP ContentDirectory Service specification explicitly lists albumArtURI as an Optional property for object.item.audioItem.musicTrack, the same as object.container.album.musicAlbum.

As for why a track needs it: a control point browsing a flat track list has no guarantee the parent album is available in the same response. This library already acknowledged this in v1.2.0 (CHANGES.rst):

Allow unknown properties to be parsed and stored, such as albumArtURI on Items, as used by Kodi

This PR simply promotes it from a silently-tolerated unknown property to a formally defined one. Kodi, Home Assistant's dlna_dmr, and TV casting apps (e.g. Xiaomi TV, confirmed via reverse engineering) all read albumArtURI directly from track objects.

@StevenLooman
Copy link
Owner

Thank you for pointing to the upnp.xsd schema.

I'll merge the PR once you've created a Towncrier file. I see that the instructions for this are missing in this repo. I'll add these soon. In the mean time, see https://github.com/StevenLooman/async_upnp_client/?tab=readme-ov-file#changes for the instructions. Or see the output of the failed action for what is expected regarding the filename.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@StevenLooman StevenLooman merged commit 42bbba8 into StevenLooman:master Mar 17, 2026
11 checks passed
@StevenLooman
Copy link
Owner

Thanks!

@StevenLooman
Copy link
Owner

I'll create a release for this and async-upnp-client when StevenLooman/async_upnp_client#296 is merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants