Added media browsing request by albaintor · Pull Request #50 · unfoldedcircle/integration-python-library

albaintor · 2026-03-04T11:47:30Z

Hi Markus @zehnm ,

To begin with the new media browsing in Kodi integration, I modified the Python integration library with new request/messages.

For now I simulate requests and it seems to work correctly.

Only browse_media request is handled at this time. I will add support for play_media and then :

clear_playlist
browse_media
search_media
search_media_classes

zehnm · 2026-03-04T12:06:01Z

Please wait with enhancing the integration library: the Integration-API specification for media browsing and searching is not yet finalized in the core-api repository and might still change!
Also the reference implementation to verify the API is not yet finished.

albaintor · 2026-03-04T12:35:23Z

Ok sorry, I was anticipating a little bit too much : I just want to have a working solution, then it won't be a problem to bring some changes. I can keep going with my simulator and raise questions on discord channel.

zehnm

The Python integration library should be similar as the Node.js library.

Instead of a generic params: dict[str, Any] browse parameter, it is much more convenient for integration developers to know what they are getting, and what to send back.
Please check https://github.com/unfoldedcircle/integration-node-library/blob/main/lib/entities/media_player.ts for all definitions.
They can easily be converted into Python classes with your AI agent of choice, including Python docs :-)

zehnm · 2026-03-18T15:47:37Z

I can offer to do the refactoring after the next release is out.

albaintor · 2026-03-19T09:21:49Z

I am on it

albaintor · 2026-03-19T11:27:57Z

All done, I have integrated it locally in Kodi integration and it works fine. Just the pagination "count" field to check vs NodeJS implementation

JackJPowell · 2026-03-19T14:51:20Z

    data: AssistantEventData | None = None
+
+
+class MediaContentType(str, Enum):


strEnum is the preferred approach for defining enums. It also aligns with the behavior found when calling asdict() as it returns the value of the enum rather than the enum.

The one question would be if it is better to align with the previous declarations using (str, Enum) or if it is agreed that this is the better approach, using it going forward.

Ok I changed it StrEnum

I do want @zehnm to weigh in on this change. It does break with the other enum definitions. I think it's better, and is a natural break point, but since it isn't like the others we should see what he thinks.

I'm traveling today but should get a chance to look at it on the train

strEnum definitely makes sense with the minimal Python version 3.11.
I can change all other str, Enum definitions before the next library release.

albaintor · 2026-03-19T17:27:19Z

OK I have made the fixes reported by @JackJPowell

albaintor · 2026-03-20T14:55:02Z

Ok this is done, you can review, thanks

- move media-player related classes to media_player.py - create msg_definitions.py for internal WS msg data definitions - Replace MediaType with MediaContentType - Use StrEnum for all media-player enums

zehnm · 2026-03-24T18:55:36Z

Since I don't call myself a Python developer, I've asked Junie Pro for some feedback about the enums.
Maybe @JackJPowell can chime in too?

Using MediaClass | str | None is indeed the correct and modern Pythonic way to handle extensible enums. It provides excellent developer experience with IDE autocompletion for known values while remaining flexible.

Why this works well:

Static Analysis: Tools like Mypy and Pyright understand that the value can be one of the enum members OR any string.
IDE Support: Developers get suggestions for MediaClass.ALBUM, but can also pass "custom_type".
Runtime: Since StrEnum values are strings, they serialize to JSON naturally without extra conversion.

I'll prepare the changes and also improve the Paging / Pagination classes. An integration driver should always receive a Paging class for consistent handling.

- Rename `PagingOptions` to `Paging` - Replace `PagingOptions` with `Paging` for better consistency. - Add validation, default values, and utility methods to `Paging`. - Make Paging mandatory in `BrowseOptions` and `SearchOptions` - Update references across `media_player.py` and `api.py` to use the new `Paging` class.

zehnm · 2026-03-24T21:39:46Z

Refactoring should be done now. I'll test it tomorrow.

JackJPowell · 2026-03-25T01:10:37Z

I wonder if we could add MediaClass / MediaContentType as optional types instead of str but I think I had issues manipulating enum types instead of strings. I could test this on my side

I suspect the trouble was before the change to strEnum. Glad your testing worked since the change above looks good and looks like it should work 😅

zehnm

I will fix the media_classes definition in SearchMediaFilter

Updated `media_classes` attribute in `SearchMediaFilter` to accept both `MediaClass` and custom string values. Added unit tests.

zehnm

I've fixed all issues from the last review, added documentation and made the browse and search error handling more robust.

@JackJPowell @albaintor please double check if I didn't introduce new issues :-)

The media-player module is refactored in PR #50

JackJPowell · 2026-03-26T17:55:57Z

+        if self.album is not None:
+            validate_str("album", self.album)
+        if isinstance(self.media_class, str):
+            validate_str("media_class", self.media_class, 0)


Just wanted to confirm this was intentional that it's valid to have an empty string for media_class and media_type since None is valid for these too.

Yes, that's a special quirk for Home Assistant. None and empty are different things. And some HA media-player integrations hand out empty media_class and media_type values and expect them again for continue browsing or start playing media.
If you omit it, HA rejects it.
It's also documented in the media-player entity documentation.

JackJPowell · 2026-03-26T18:05:46Z

Pytest is the testing framework preference now, but these tests will still run under pytest if we wanted to move in that direction and can be easily converted later. AI can do it in a heartbeat as well.

JackJPowell · 2026-03-26T18:14:23Z

@@ -1,193 +1,659 @@
 """


Entity specific classes are not exported in init.py so I assume we don't want to start by adding the new MediaPlayer classes either... but wanted to point it out

I guess they should be exported :-) Completely forgot about it!

I've added the unique media-player classes in init.
Python modules and exports will always feel weird to me...
Let me know if you see missing things or other improvements

JackJPowell

Just very minor things. Mostly questions with a couple of additions to init

JackJPowell · 2026-03-26T21:07:16Z

Those last changes look great! I think everything is being exported now.

zehnm · 2026-03-27T08:21:26Z

Thanks everyone!

Breaking Changes - Renamed `MediaType` to `MediaContentType` and changed enums to lowercase. See media-player entity documentation for more information (#50). - Changed `str, Enum` to new Python 3.11 `StrEnum` class (#54). - All entity constructors require named parameters for the optional fields (#49, #54).

Added media browsing request

55b4c45

albaintor marked this pull request as draft March 4, 2026 11:47

albaintor added 2 commits March 8, 2026 19:04

Added missing methods and commands

5140403

Fixed search media response type

6d0a3a5

zehnm requested changes Mar 18, 2026

View reviewed changes

Comment thread ucapi/entity.py Outdated

albaintor added 2 commits March 19, 2026 10:41

Refactoring and added typed definitions

e55a4b4

Finalized & tested updated API with browsing/search support

69ab522

albaintor marked this pull request as ready for review March 19, 2026 11:27

albaintor requested a review from zehnm March 19, 2026 11:28

JackJPowell suggested changes Mar 19, 2026

View reviewed changes

JackJPowell reviewed Mar 19, 2026

View reviewed changes

Comment thread ucapi/media_player.py

JackJPowell reviewed Mar 19, 2026

View reviewed changes

Comment thread ucapi/media_player.py

albaintor added 3 commits March 19, 2026 17:01

Removed forced media_type to MediaContentType as it can be custom

0665b31

Fixed bug

8f9f553

Fixed bug

7c0e585

JackJPowell reviewed Mar 19, 2026

View reviewed changes

Comment thread ucapi/api.py Outdated

albaintor added 2 commits March 19, 2026 18:14

Nailed bug finally

0081b3d

Fixes reported by Jack

4c16fbf

zehnm requested changes Mar 20, 2026

View reviewed changes

Comment thread ucapi/api_definitions.py Outdated

Comment thread ucapi/api_definitions.py Outdated

Comment thread ucapi/media_player.py Outdated

Comment thread ucapi/media_player.py

Fixes following Markus review

d11cfea

albaintor requested review from JackJPowell and zehnm March 20, 2026 14:55

JackJPowell approved these changes Mar 21, 2026

View reviewed changes

albaintor requested a review from zehnm March 24, 2026 18:29

Refactor media classes

7fdc544

- move media-player related classes to media_player.py - create msg_definitions.py for internal WS msg data definitions - Replace MediaType with MediaContentType - Use StrEnum for all media-player enums

zehnm added 3 commits March 24, 2026 20:01

Use MediaClass and MediaContentType in BrowseMediaItem

e1b8fad

Merge branch 'main' into fork/albaintor/media_browsing

3553d3e

zehnm added 2 commits March 25, 2026 09:02

Separate SearchOptions from BrowseOptions

ee0e117

Add documentation to media-player classes

d2c1146

zehnm requested changes Mar 25, 2026

View reviewed changes

Comment thread ucapi/media_player.py Outdated

zehnm added 2 commits March 25, 2026 10:15

Fix SearchMediaFilter to support custom media classes

99046c3

Updated `media_classes` attribute in `SearchMediaFilter` to accept both `MediaClass` and custom string values. Added unit tests.

Improve error handling in browse and search

0ce29c7

zehnm approved these changes Mar 25, 2026

View reviewed changes

zehnm requested a review from JackJPowell March 25, 2026 10:06

zehnm added a commit that referenced this pull request Mar 25, 2026

refactor!: replace "str, Enum" with StrEnum

e3bff0e

The media-player module is refactored in PR #50

zehnm mentioned this pull request Mar 25, 2026

Replace "str, Enum" with StrEnum #54

Merged

zehnm added 2 commits March 25, 2026 17:55

Add text field validation in BrowseMediaItem

70f18fe

fixup! Add text field validation in BrowseMediaItem

6615bce

JackJPowell reviewed Mar 26, 2026

View reviewed changes

Comment thread ucapi/api_definitions.py Outdated

JackJPowell reviewed Mar 26, 2026

View reviewed changes

PR feedback: add exports and validate paging limit

1b867d8

JackJPowell approved these changes Mar 26, 2026

View reviewed changes

zehnm merged commit e5ed5f9 into unfoldedcircle:main Mar 27, 2026
6 checks passed

		data: AssistantEventData \| None = None


		class MediaContentType(str, Enum):

Conversation

albaintor commented Mar 4, 2026

Uh oh!

zehnm commented Mar 4, 2026

Uh oh!

albaintor commented Mar 4, 2026

Uh oh!

zehnm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zehnm commented Mar 18, 2026

Uh oh!

albaintor commented Mar 19, 2026

Uh oh!

albaintor commented Mar 19, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

albaintor commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

albaintor commented Mar 20, 2026

Uh oh!

zehnm commented Mar 24, 2026

Uh oh!

zehnm commented Mar 24, 2026

Uh oh!

JackJPowell commented Mar 25, 2026

Uh oh!

zehnm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zehnm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JackJPowell left a comment

Choose a reason for hiding this comment

Uh oh!

JackJPowell commented Mar 26, 2026

Uh oh!

Uh oh!

zehnm commented Mar 27, 2026