Skip to content

refactor(api): make media image requests single-item #845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wizzomafizzo merged 2 commits into from
May 25, 2026
Merged

refactor(api): make media image requests single-item #845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c3271b
refactor(api): make media image requests single-item
wizzomafizzo May 25, 2026
5ca31c6
fix(api): address media image review feedback
wizzomafizzo May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 2 additions & 22 deletions docs/api/methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1352,8 +1352,9 @@ Single requests return the existing single `media` response shape. Batch request
| text | string | Yes | Text value or source path for the property. |
| contentType | string | Yes | MIME type for binary-backed properties, empty for text-only values. |
| extension | string | No | File extension without a dot, derived from MIME type or source path. |
| data | string | No | Base64-encoded binary property data. Omitted for text-only properties. |
| blobSize | number | No | Size in bytes for binary-backed properties. |

Binary property data is not returned by `media.meta`. Use `media.image` to fetch image bytes.
Property keys are canonical type tags such as `property:description`, `property:image-image`, or `property:manual`.

#### Example
Expand Down Expand Up @@ -1444,12 +1445,8 @@ An object identifying the media row by `mediaId` or `(system, path)`. Canonical
| system | string | No | System ID. Required when `mediaId` is omitted. |
| path | string | No | Canonical indexed media path. Required when `mediaId` is omitted. |
| imageTypes | string[] | No | Image type preference order. Defaults to `image`, `boxart`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, `fanart`. |
| items | object[] | No | Batch request items. Each item uses either `mediaId` or `system`/`path`, and may include item-level `imageTypes`. Maximum 50 items. Cannot be mixed with top-level media ref fields. |

Supported image type values are `image`, `boxart`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, and `fanart`. They resolve to canonical property tags such as `property:image-image` and `property:image-boxart`.

Single requests return the existing single image response shape. Batch requests return `{ "items": [...] }` in input order. Each batch item contains either `image` or `error`. Top-level `imageTypes` applies to all batch items unless an item has its own `imageTypes` override.

#### Result

| Key | Type | Required | Description |
Expand All @@ -1476,23 +1473,6 @@ Single requests return the existing single image response shape. Batch requests
}
```

##### Batch Request

```json
{
"jsonrpc": "2.0",
"id": "e5f6a7b8-7a5d-11ef-9c7b-020304050608",
"method": "media.image",
"params": {
"imageTypes": ["boxart", "image"],
"items": [
{"mediaId": 42},
{"mediaId": 43, "imageTypes": ["screenshot"]}
]
}
}
```

##### Response

```json
Expand Down
8 changes: 4 additions & 4 deletions docs/scraper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,8 +131,8 @@ JSON-RPC methods:
| `media.scrape` | Starts a scraper run as a background operation |
| `media.scrape.status` | Returns the latest scraper status snapshot |
| `media.scrape.cancel` | Cancels the active scraper run |
| `media.meta` | Returns tags and properties for one or more media rows and their titles |
| `media.image` | Returns the best matching image property as base64 data for one or more media rows |
| `media.meta` | Returns tags and metadata-only properties for one or more media rows and their titles |
| `media.image` | Returns the best matching image property as base64 data for one media row |
| `media.clean.orphans` | Removes missing media rows and orphaned related data |

`media.scrape` params:
Expand Down Expand Up @@ -162,6 +162,6 @@ Progress is queryable with `media.scrape.status` and broadcast as `media.scrapin

Only one scraper can run at a time, and scraping is mutually exclusive with media indexing.

`media.meta` returns the full metadata graph for media rows: media-level tags and properties, title-level tags and properties, and the stored system identity. Single requests accept `mediaId` or `system`/`path` and keep the single-response shape; batch requests use `items` and return per-item results.
`media.meta` returns the full metadata graph for media rows: media-level tags and properties, title-level tags and properties, and the stored system identity. Single requests accept `mediaId` or `system`/`path` and keep the single-response shape; batch requests use `items` and return per-item results. Binary property bytes are not included; clients should use `media.image` for image data.

`media.image` accepts image type preferences such as `image`, `boxart`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, and `fanart`. These resolve to canonical image property tags; for example `boxart` becomes `property:image-boxart` and `image` becomes `property:image-image`. Media-level properties are preferred over title-level properties for the same type. Stale file paths are removed automatically and lookup falls through to the next available source. Batch requests use `items`, with optional per-item `imageTypes` overriding the top-level preference order.
`media.image` accepts one media ref plus image type preferences such as `image`, `boxart`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, and `fanart`. These resolve to canonical image property tags; for example `boxart` becomes `property:image-boxart` and `image` becomes `property:image-image`. Media-level properties are preferred over title-level properties for the same type. Stale file paths are removed automatically and lookup falls through to the next available source.
Loading
Loading