Skip to content

Commit 650efbc

Browse files
zehnmzehnm
committed
add stable_ids parameter to media browsing and searching
1 parent d9a46e7 commit 650efbc

6 files changed

Lines changed: 92 additions & 62 deletions

File tree

‎core-api/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ in YAML format.
2727

2828
| UCR Firmware | Core Simulator | REST API | WS API |
2929
|--------------|----------------|----------|--------|
30+
| | 0.70.4 | 0.45.1 | 0.35.1 |
3031
| | 0.70.3 | 0.45.0 | 0.35.0 |
3132
| 2.8.4-beta | 0.69.3 | 0.44.4 | 0.34.0 |
3233
| 2.8.3-beta | 0.68.1 | 0.44.1 | 0.34.0 |

‎core-api/rest/UCR-core-openapi.yaml‎

Lines changed: 24 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.3
22
info:
33
title: Remote Two/3 REST Core-API
4-
version: 0.45.0
4+
version: 0.45.1
55
contact:
66
name: API Support
77
url: 'https://github.com/unfoldedcircle/core-api/issues'
@@ -2575,6 +2575,15 @@ paths:
25752575
A `media_id` or `media_type` field may only be omitted from a request if it was not present in the response at all
25762576
or if it was explicitly set to `null` in the browse response.
25772577

2578+
The `stable_ids` query parameter is a hint that the client requires stable media identifiers in the returned
2579+
`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration
2580+
might be able to use a workaround generating stable identifiers on the client side.
2581+
2582+
Roon is such an example, which generates new media keys for every new browse or search request. Use cases like
2583+
"select an identifier of my favorite playlist, so I can still play it next month" aren't possible with changing
2584+
identifiers. As a workaround, the integration driver returns a path structure (`Library/Playlists/Favorite Songs`)
2585+
that is resolved when playing an item.
2586+
25782587
The paging query parameters can be used to retrieve a specific page of media items and to limit result size:
25792588

25802589
- `limit`: Maximum number of items to return per page. Default is 10.
@@ -2592,6 +2601,7 @@ paths:
25922601
- $ref: '#/components/parameters/entity_id'
25932602
- $ref: '#/components/parameters/media_id'
25942603
- $ref: '#/components/parameters/media_type'
2604+
- $ref: '#/components/parameters/stable_ids'
25952605
- $ref: '#/components/parameters/page'
25962606
- $ref: '#/components/parameters/limit'
25972607
responses:
@@ -2644,6 +2654,11 @@ paths:
26442654
A `media_id` or `media_type` field may only be omitted from a request if it was not present in the response at all
26452655
or if it was explicitly set to `null` in the search response.
26462656

2657+
The `stable_ids` query parameter is a hint that the client requires stable media identifiers in the returned
2658+
`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration
2659+
might be able to use a workaround generating stable identifiers on the client side. See browse endpoint for more
2660+
information.
2661+
26472662
The paging query parameters can be used to retrieve a specific page of media items and to limit result size:
26482663

26492664
- `limit`: Maximum number of items to return per page. Default is 10.
@@ -2688,6 +2703,7 @@ paths:
26882703
schema:
26892704
type: string
26902705
maxLength: 255
2706+
- $ref: '#/components/parameters/stable_ids'
26912707
- $ref: '#/components/parameters/page'
26922708
- $ref: '#/components/parameters/limit'
26932709
responses:
@@ -2726,49 +2742,6 @@ paths:
27262742
$ref: '#/components/responses/Err500InternalServerError'
27272743
'503':
27282744
$ref: '#/components/responses/Err503ServiceUnavailable'
2729-
'/entities/{entityId}/media/queue':
2730-
get:
2731-
tags:
2732-
- entities
2733-
summary: "\U0001F6A7 Get the current playback queue."
2734-
description: 'Initial draft, do not use!'
2735-
operationId: getMediaQueue
2736-
parameters:
2737-
- $ref: '#/components/parameters/entity_id'
2738-
- $ref: '#/components/parameters/page'
2739-
- $ref: '#/components/parameters/limit'
2740-
responses:
2741-
'200':
2742-
description: Successful operation.
2743-
headers:
2744-
Pagination-Count:
2745-
description: Total number of items.
2746-
schema:
2747-
type: integer
2748-
Pagination-Limit:
2749-
description: Number of returned items.
2750-
schema:
2751-
type: integer
2752-
Pagination-Page:
2753-
description: Current page number. 1-based.
2754-
schema:
2755-
type: integer
2756-
content:
2757-
application/json:
2758-
schema:
2759-
$ref: '#/components/schemas/MediaQueueResponse'
2760-
'400':
2761-
$ref: '#/components/responses/Err400BadRequest'
2762-
'401':
2763-
$ref: '#/components/responses/Err401Unauthorized'
2764-
'403':
2765-
$ref: '#/components/responses/Err403Forbidden'
2766-
'404':
2767-
$ref: '#/components/responses/Err404NotFound'
2768-
'500':
2769-
$ref: '#/components/responses/Err500InternalServerError'
2770-
'503':
2771-
$ref: '#/components/responses/Err503ServiceUnavailable'
27722745
/activities:
27732746
head:
27742747
tags:
@@ -11185,6 +11158,13 @@ components:
1118511158
required: false
1118611159
schema:
1118711160
type: boolean
11161+
stable_ids:
11162+
name: stable_ids
11163+
in: query
11164+
description: Use stable media identifiers.
11165+
required: false
11166+
schema:
11167+
type: boolean
1118811168
schemas:
1118911169
AccessTokenId:
1119011170
type: string

‎core-api/websocket/UCR-core-asyncapi.yaml‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ asyncapi: 2.2.0
88
id: 'urn:com:unfoldedcircle:core'
99
info:
1010
title: Remote Two/3 WebSocket Core-API
11-
version: '0.35.0-beta'
11+
version: '0.35.1-beta'
1212
contact:
1313
name: API Support
1414
url: https://github.com/unfoldedcircle/core-api/issues
@@ -1513,6 +1513,15 @@ components:
15131513
description: |
15141514
Retrieves the content of a media container or the root if no `media_id` is specified.
15151515
Requires the `media_browser` feature on the target `media_player` entity.
1516+
1517+
The `stable_ids` parameter is a hint that the client requires stable media identifiers in the returned
1518+
`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration
1519+
might be able to use a workaround generating stable identifiers on the client side.
1520+
1521+
Roon is such an example, which generates new media keys for every new browse or search request. Use cases like
1522+
"select an identifier of my favorite playlist, so I can still play it next month" aren't possible with changing
1523+
identifiers. As a workaround, the integration driver returns a path structure (`Library/Playlists/Favorite Songs`)
1524+
that is resolved when playing an item.
15161525
tags:
15171526
- name: entity
15181527
payload:
@@ -1525,6 +1534,9 @@ components:
15251534
description: |
15261535
Searches for media items within the active system of the `media_player` entity.
15271536
Requires the `media_search` feature on the target `media_player` entity.
1537+
1538+
The `stable_ids` parameter is a hint that the client requires stable media identifiers in the returned
1539+
`media_id` and `media_type` fields. See `browse_media` for more information.
15281540
tags:
15291541
- name: entity
15301542
payload:
@@ -4742,6 +4754,9 @@ components:
47424754
Optional media content type to restrict browsing.
47434755
Either a defined MediaContentType value or an integration dependent identifier.
47444756
type: string
4757+
stable_ids:
4758+
description: Hint to the integration to return stable media IDs.
4759+
type: boolean
47454760
paging:
47464761
$ref: '#/components/schemas/paging'
47474762
required:
@@ -4775,6 +4790,9 @@ components:
47754790
Optional media content type to restrict browsing.
47764791
Either a defined MediaContentType value or an integration dependent identifier.
47774792
type: string
4793+
stable_ids:
4794+
description: Hint to the integration to return stable media IDs.
4795+
type: boolean
47784796
filter:
47794797
$ref: '#/components/schemas/MediaSearchFilter'
47804798
paging:

‎doc/entities/entity_media_player.md‎

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -283,12 +283,13 @@ This allows better integration into Remote Two, like default UI mappings and gro
283283
Media browsing uses a dedicated command and is not part of the standard media-player entity commands.
284284

285285

286-
| cmd_id | Parameters | Description |
287-
|:-------------|:-----------|:--------------------------------------------------|
288-
| browse_media | entity_id | Browse media from a media-player entity. |
289-
| | media_id | Optional media content ID to restrict browsing. |
290-
| | media_type | Optional media content type to restrict browsing. |
291-
| | paging | Optional paging object to limit returned items. |
286+
| cmd_id | Parameters | Description |
287+
|:-------------|:-----------|:-----------------------------------------------------------------|
288+
| browse_media | entity_id | Browse media from a media-player entity. |
289+
| | media_id | Optional media content ID to restrict browsing. |
290+
| | media_type | Optional media content type to restrict browsing. |
291+
| | stable_ids | Optional hint that the client requires stable media identifiers. |
292+
| | paging | Optional paging object to limit returned items. |
292293

293294
The `media_id` and `media_type` parameters are optional and can be used to restrict browsing to a specific media item
294295
or content type. Both fields can be returned in the browse response on the root item and on every child item to describe
@@ -300,6 +301,15 @@ within that entity. This ensures that it can be reused in subsequent `play_media
300301
calls. Integrations may use either one of the pre-defined semantic content types (see [Media Content Types](#media-content-types))
301302
or provider-specific URIs for `media_type`, as long as values are stable and reused consistently.
302303

304+
Certain media providers may not support stable identifiers, but the integration might be able to use a workaround
305+
generating stable identifiers on the client side. The `stable_ids` parameter is a hint that the client really requires
306+
stable media identifiers in the returned `media_id` and `media_type` fields, because the identifier won't be used right
307+
now to play a media item but sometime in the future.
308+
Roon is such an example, which generates new media keys for every new browse or search request. Use cases like
309+
"select an identifier of my favorite playlist, so I can still play it next month" aren't possible with changing
310+
identifiers. As a workaround, the integration driver can return a path structure (`Library/Playlists/Favorite Songs`)
311+
or another sort of identifier that can be used to identify or resolve the item in the future.
312+
303313
**Important:** When using `media_id` and `media_type` values in further calls, they must match the values returned in
304314
the previous `media_browse` response exactly. If an integration returns an empty string (`""`) as value, that exact
305315
empty string will be sent back on later calls and does not mean "no value."
@@ -506,16 +516,17 @@ Media searching uses a dedicated command and is not part of the standard media-p
506516
Note: The filter object is not yet formally defined in the Integration-API. The fields below are examples of possible
507517
filters and are not required.
508518

509-
| cmd_id | Parameters | Description |
510-
|--------------|----------------------|--------------------------------------------------------|
511-
| search_media | entity_id | Search for media items in a media-player entity. |
512-
| | query | Free-text search query. |
513-
| | media_id | Optional media content ID to limit the search scope. |
514-
| | media_type | Optional media content type to limit the search scope. |
515-
| | filter.media_classes | Optional list of media classes to filter the results. |
516-
| | filter.artist | 🚧 TBD if a set of well-known filters like `artist` |
517-
| | filter.album | 🚧 and `album`, or dynamic |
518-
| | paging | Optional paging object to limit returned items. |
519+
| cmd_id | Parameters | Description |
520+
|--------------|----------------------|------------------------------------------------------------------|
521+
| search_media | entity_id | Search for media items in a media-player entity. |
522+
| | query | Free-text search query. |
523+
| | media_id | Optional media content ID to limit the search scope. |
524+
| | media_type | Optional media content type to limit the search scope. |
525+
| | stable_ids | Optional hint that the client requires stable media identifiers. |
526+
| | filter.media_classes | Optional list of media classes to filter the results. |
527+
| | filter.artist | 🚧 TBD if a set of well-known filters like `artist` |
528+
| | filter.album | 🚧 and `album`, or dynamic |
529+
| | paging | Optional paging object to limit returned items. |
519530

520531
The `media_id` and `media_type` parameters behave the same as in `browse_media`: they can be used to restrict the
521532
search to a specific container or content type, and integrations should propagate and reuse the values consistently.
@@ -525,6 +536,7 @@ Empty strings must be preserved and echoed back as-is. Only omit a field if it w
525536
- The optional `filter.media_classes` filter may only contain media classes that are supported by the integration.
526537
- Supported media classes must be specified in the `search_media_classes` attribute by the integration.
527538
- Only well-known [Media Classes](#media-classes) should be used without any custom media classes.
539+
- See [Media Browsing](#media-browsing) for a description of the `stable_ids` parameter.
528540
- 🚧 The `filter.artist` and `filter.album` fields are examples of possible future filters and are not yet formally defined.
529541
- The optional `paging` object can be used to retrieve a specific page of media items and to limit result size.
530542

‎integration-api/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ The provided Bash wrapper script [`create-html-docker.sh`](create-html-docker.sh
2323

2424
| Integration API | UCR Firmware | Core Simulator |
2525
|-----------------|--------------|----------------|
26+
| 0.15.1 | | 0.70.4 |
2627
| 0.15.0 | | 0.70.3 |
2728
| 0.13.0 | 2.8.0-beta | 0.64.4 |
2829
| 0.12.1 | 2.2.4-beta | 0.58.3 |

‎integration-api/UCR-integration-asyncapi.yaml‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ asyncapi: 2.2.0
88
id: 'urn:com:unfoldedcircle:integration'
99
info:
1010
title: Remote Two/3 WebSocket Integration API
11-
version: '0.15.0-beta'
11+
version: '0.15.1-beta'
1212
contact:
1313
name: API Support
1414
url: https://github.com/unfoldedcircle/core-api/issues
@@ -811,6 +811,15 @@ components:
811811
description: |
812812
Retrieves the content of a media container or the root if no `media_id` is specified.
813813
Requires the `media_browser` feature on the target `media_player` entity.
814+
815+
The `stable_ids` parameter is a hint that the client requires stable media identifiers in the returned
816+
`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration
817+
might be able to use a workaround generating stable identifiers on the client side.
818+
819+
Roon is such an example, which generates new media keys for every new browse or search request. Use cases like
820+
"select an identifier of my favorite playlist, so I can still play it next month" aren't possible with changing
821+
identifiers. As a workaround, the integration driver returns a path structure (`Library/Playlists/Favorite Songs`)
822+
that is resolved when playing an item.
814823
tags:
815824
- name: entity
816825
payload:
@@ -823,6 +832,9 @@ components:
823832
description: |
824833
Searches for media items within the active system of the `media_player` entity.
825834
Requires the `media_search` feature on the target `media_player` entity.
835+
836+
The `stable_ids` parameter is a hint that the client requires stable media identifiers in the returned
837+
`media_id` and `media_type` fields. See `browse_media` for more information.
826838
tags:
827839
- name: entity
828840
payload:
@@ -1455,6 +1467,9 @@ components:
14551467
Optional media content type to restrict browsing.
14561468
Either a defined MediaContentType value or an integration dependent identifier.
14571469
type: string
1470+
stable_ids:
1471+
description: Hint to the integration to return stable media IDs.
1472+
type: boolean
14581473
paging:
14591474
$ref: '#/components/schemas/Paging'
14601475
required:
@@ -1488,6 +1503,9 @@ components:
14881503
Optional media content type to restrict browsing.
14891504
Either a defined MediaContentType value or an integration dependent identifier.
14901505
type: string
1506+
stable_ids:
1507+
description: Hint to the integration to return stable media IDs.
1508+
type: boolean
14911509
filter:
14921510
$ref: '#/components/schemas/MediaSearchFilter'
14931511
paging:

0 commit comments

Comments
 (0)