searchmedia
Find playable media files in a Kodi library by name, with filters for artist, actor, or director. Provides paginated results and total count.
Instructions
Find playable files by name: music/tv-show/movie, drilled to leaf files with paging (limit/offset) and a total count. For music, title means the ALBUM name — songs cannot be matched by their own title. Movie and tv-show queries can also filter by actor/director. Finds media items only — for people lookups (bands, artists, who is in the library) use contributors. Returns { "type", "total", "returned", "offset", "truncated", "rows": [ { "file", "id", "label", "title", … } ] }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| type | Yes | Media kind to search: music | tv-show | movie. | |
| artist | No | Music only: performer name (substring, case-insensitive). Resolves the artist; music needs artist or title. | |
| actor | No | movie/tv-show only: cast-member name (substring, case-insensitive). For tv-show it matches episode cast, which includes guest stars; combinable with title. | |
| director | No | movie/tv-show only: director name (substring, case-insensitive). For tv-show it matches per-episode directors; combinable with title. | |
| title | No | Container/title to match (substring, case-insensitive): album for music, show for tv-show, the movie title for movie. tv-show needs title, actor or director; without title the person is matched library-wide and rows carry showtitle. Music without artist resolves the album library-wide. | |
| season | No | tv-show only: season number to narrow the episodes. | |
| number | No | Position within the container: track number (music) or episode number (tv-show). | |
| limit | No | Max leaf rows to return (default 50, max 500). Page with offset. | |
| offset | No | Number of leaf rows to skip — paginate together with limit. | |
| count | No | When true, return only the total match count (zero rows) — a cheap count. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The searched media type, echoed back. | |
| total | Yes | Full match count, before any paging. | |
| returned | Yes | Rows in this page. | |
| offset | Yes | Rows skipped before this page. | |
| truncated | Yes | Whether matches remain beyond this page. | |
| approximate | No | Present (true) when total/paging are app-side estimates (a substring title matched several albums). | |
| resolved | No | The container the query resolved to — { "artist"?|"show"?, "artistid"|"tvshowid" } — when it drilled through one. | |
| rows | Yes | The matching leaf rows, paged. |