Skip to main content

​
Overview

Media items represent individual pieces of content in your ErsatzTV libraries: movies, TV episodes, music videos, songs, and images. The Media Items API provides query and management capabilities.
The Media Items API is primarily accessed through the web UI search and browse interfaces. Direct API endpoints for media item queries are provided through the search functionality.

​
Media Item Types

ErsatzTV supports the following media types:

Movies

Feature films and standalone video content

TV Episodes

Television show episodes organized by series and season

Music Videos

Music video clips with artist and album metadata

Songs

Audio tracks with album and artist information

Images

Still images for display (e.g., channel logos, artwork)

Other Videos

Miscellaneous video content not categorized as movies or episodes

​
Media Item Structure

​
Movie Metadata

Movies include:
  • Title
  • Release year
  • Plot summary
  • Genres
  • Content rating
  • Runtime
  • IMDb/TMDB IDs
  • Poster and backdrop artwork
  • Subtitle tracks
  • Audio tracks
  • Video codec information

​
Episode Metadata

TV episodes include:
  • Series title
  • Season number
  • Episode number
  • Episode title
  • Air date
  • Plot summary
  • Poster artwork
  • Subtitle tracks
  • Audio tracks
  • Video codec information

​
Music Video Metadata

Music videos include:
  • Track title
  • Artist name(s)
  • Album name
  • Release year
  • Genre
  • Duration
  • Thumbnail artwork

​
Accessing Media Items

​
Through Collections

The primary way to work with media items programmatically is through Smart Collections: 
GET /api/collections/smart
Collections use query syntax to dynamically group media items: 
title:"Breaking Bad" AND season:1
ErsatzTV’s search functionality indexes all media items. While search is primarily accessed through the web UI, it uses the same underlying media item data.

​
Media Item Properties

​
Common Properties

All media items share these base properties:
​
id
integer
Unique media item identifier
​
mediaType
string
Type: Movie, Episode, MusicVideo, Song, Image, OtherVideo
​
libraryId
integer
ID of the library containing this item
​
path
string
File system or remote path to the media file
​
state
string
Item state: Normal, Unavailable, FileNotFound

​
Metadata Properties

​
title
string
Primary title of the media item
​
sortTitle
string
Title used for sorting (e.g., “Matrix, The”)
​
year
integer
Release or air year
​
genres
array
List of genre tags
​
tags
array
Custom tags for organization
​
plot
string
Description or plot summary

​
Technical Properties

​
duration
string
Runtime in HH:MM:SS format
​
videoCodec
string
Video codec (e.g., “h264”, “hevc”, “av1”)
​
videoProfile
string
Codec profile (e.g., “Main”, “High”)
​
audioCodec
string
Audio codec (e.g., “aac”, “ac3”, “dts”)
​
audioChannels
integer
Number of audio channels (e.g., 2, 6 for 5.1)
​
resolution
string
Video resolution (e.g., “1920x1080”, “3840x2160”)
​
frameRate
number
Frames per second (e.g., 23.976, 29.97)

​
Media Item States

Media items can be in different states:

​
Normal

Item is available and accessible for playback.

​
Unavailable

Item is temporarily unavailable (e.g., remote server offline).

​
FileNotFound

Item file no longer exists. Item is moved to trash during next library scan.
Items in FileNotFound state should be removed from schedules and collections.

​
Media Item Operations

​
Indexing

Media items are automatically indexed during library scans: 
POST /api/libraries/{id}/scan
See Libraries API for scan details.

​
Metadata Refresh

Metadata is refreshed during library scans. For immediate refresh:
  1. Navigate to the item in the web UI
  2. Click Refresh Metadata
  3. Or trigger a library scan via API

​
Trash Management

Items marked for deletion are moved to trash: 
POST /api/maintenance/empty_trash
This permanently removes trashed items from the database.

​
Working with Media Items

​
Creating Collections

Group media items using smart collections: 
POST /api/collections/smart/new

{
  "name": "Action Movies",
  "query": "mediatype:movie AND genre:action"
}
See Collections API for details.

​
Scheduling Content

Add media items to channel schedules:
  1. Create a collection containing desired items
  2. Add the collection to a channel schedule
  3. Content plays according to schedule rules
See Schedules API for scheduling details.

​
Query Syntax

Smart collections use a query language to filter media:

​
Basic Queries

title:"Star Wars"
mediatype:movie
year:1977
genre:scifi

​
Logical Operators

title:"Star Wars" AND year:1977
genre:action OR genre:adventure
NOT genre:horror

​
Ranges

year:>2000
year:2010..2020
runtime:<120

​
Episode Queries

title:"Breaking Bad" AND season:1
title:"The Office" AND season:2 AND episode:1
Query syntax is case-insensitive. Use quotes for multi-word values.

​
Media Item Artwork

Artwork is cached and served via the artwork endpoint: 
GET /iptv/logos/{fileName}
Artwork types:
  • Poster - Vertical artwork for movies and shows
  • Thumbnail - Episode thumbnails
  • Backdrop - Horizontal background images
  • Logo - Channel and show logos

​
Subtitles

Media items can include subtitle tracks:

​
Embedded Subtitles

Subtitles embedded in the media file container.

​
External Subtitles

Sidecar subtitle files (.srt, .ass, .vtt).

​
Subtitle Extraction

Extract embedded subtitles to external files: 
POST /api/subtitles/extract/{mediaItemId}

​
Best Practices

Use Collections

Manage groups of media items with smart collections instead of individual items

Regular Scans

Schedule regular library scans to keep media metadata up to date

Clean Trash

Periodically empty trash to remove deleted items from the database

Monitor States

Check for items in FileNotFound state and remove from schedules

​
Troubleshooting

​
Media Not Appearing

If media items don’t appear after adding files:
  1. Trigger a library scan: POST /api/libraries/{id}/scan
  2. Check library path permissions
  3. Verify file formats are supported
  4. Review scan logs for errors

​
Missing Metadata

If metadata is incomplete:
  1. Ensure files follow proper naming conventions
  2. Check metadata provider settings (TMDB, TVDB)
  3. Manually refresh metadata in the web UI
  4. Consider re-scanning with deep scan enabled

​
Playback Issues

If media items won’t play:
  1. Verify file paths are accessible
  2. Check FFmpeg profile compatibility
  3. Review transcoding logs
  4. Test file playback outside ErsatzTV

​
Next Steps

Collections

Create smart collections to organize media items

Schedules

Add media items to channel schedules

Build docs developers (and LLMs) love

Get started for freeTalk to us