Paging results for media sources with large number of items

[allenporter]

Proposal

Extend the media source API to improve performance and user experience for media sources with a large number of items.

Background

Media sources with a large number of items in a folder have two choices on how they can handle things:

• (a) Return all results in a single response. This may be a larger result and it might be slow or expensive to produce. For a cloud integration, it could involve multiple round trips.
• (b) Return a fixed # of results. This would effectively truncate the results and can be fast, but may be surprising to a user.

An example of (a) is the nest integration which reads recent camera snapshots from a local json file and returns 1.7MB response for 1k items. An example of (b) is Google Photos Recent Items where I made an arbitrary choice to truncate to 100 most recent photos (and it also does (a) in some scenarios)

Proposal Overview

A media source supports browsing based on an identifier and returns an object with a list of child nodes that are displayed in a grid. The changes would be:

• A media source will be extended to support returning a partial list of children with an optional page token.
• The page token can be passed into a subsequent call for the same identifier and return additional children.
• This can be repeated until the list of children is complete and now additional page token is returned.
• The page token will be an opaque string, and the format is specific to the integration.

Usage Survey

• Integrations like Nest could be updated to return smaller responses.
• Google Photos could be extended to support scrolling through the entire grid (given there is a limit) or to make handling large albums more efficient (albums support 20k, but we fetch all photos in an album today)
• Synology DSM currently has a limit of 1k photos in an album and returns all of them at once. It could instead return pages to page through more using an offset parameter in the API. I believe the device supports a limit of 2k
• Unifi protect is already truncated
• Radio browser currently returns a 1.9MB response object. It supports an offset parameter.

Implications

• This proposal does not support paging in reverse
• This proposal would not allow quickly jumping to the end of the results, and would still require paging through the results.
• Integrations are responsible managing the lifecycle of the page tokens and their format )need to real with cases where the page token is invalid, expired, etc)

Alternatives & Caveats

• Another common approach for paging is to use an offset integer. This typically looks like a simpler API, however are usually less performant as databases need to still scan through items to jump to the offset. Pagination with a token can allow for implementations that are performant using index scans. Also, integrations can implement offsets if they want by returning a number in the page token.
• We could decide to always do (b) and always limit response sizes. In the case of Nest example above it uses 1k events which we could decide doesn't need to be that large.

[emontnemery]

The proposal seems fine, but it's a bit unclear exactly how it would work. Could you maybe open a draft implementation PR, or add some code example here @allenporter ?