pgsql-jellyfin/docs/DATABASE_VIEWS.md

PostgreSQL Database Views

All views live in the library schema unless otherwise noted. They are read-only and safe to query from pgAdmin, BI tools, or any reporting/debugging context without risk of affecting the application.

---

library."MediaStreamInfos_v"

Reassembles the original flat MediaStreamInfos table shape that existed before the SplitMediaStreamInfos migration split audio- and video-specific columns into dedicated tables.

Use when: you want a single flat result of all stream data without writing the three-way JOIN yourself.

Columns of note:

Column	Source
ItemId, StreamIndex, StreamType, Codec, …	MediaStreamInfos (always present)
ChannelLayout, Channels, SampleRate, IsHearingImpaired	AudioStreamDetails — NULL for non-audio streams
Height, Width, AverageFrameRate, BitDepth, ColorTransfer, DvProfile, …	VideoStreamDetails — NULL for non-video streams

Example:

-- All audio streams for a specific item
SELECT "StreamIndex", "Codec", "Language", "Channels", "SampleRate", "ChannelLayout"
FROM library."MediaStreamInfos_v"
WHERE "ItemId" = '<item-uuid>'
  AND "StreamType" = 0   -- 0 = Audio
ORDER BY "StreamIndex";

---

library."VideoItems_v"

Every non-folder, non-virtual item that has at least one video stream (movies, episodes, home videos, etc.), joined with the primary video stream's technical details.

Use when: auditing codec/resolution/HDR distribution across the library, or finding items that need re-encoding.

Columns of note:

Column	Description
Type	Fully-qualified Jellyfin type name (e.g. MediaBrowser.Controller.Entities.Movies.Movie)
VideoCodec	Codec of the primary video stream (e.g. hevc, h264)
Width / Height	Resolution of the primary video stream
BitDepth	Colour bit depth (8, 10, 12)
HDRFormat	Derived string: Dolby Vision, HDR10+, HDR10, HLG, or SDR
IsDolbyVision	Boolean shortcut for DvProfile IS NOT NULL
AudioTrackCount	Number of audio streams on the item
SubtitleTrackCount	Number of subtitle streams on the item

Example queries:

-- All 4K HDR movies
SELECT "Name", "ProductionYear", "VideoCodec", "Width", "Height", "HDRFormat", "TotalBitrate"
FROM library."VideoItems_v"
WHERE "Type" LIKE '%Movie%'
  AND "Height" >= 2160
  AND "HDRFormat" <> 'SDR'
ORDER BY "Name";

-- Episodes still encoded in H.264 (candidates for HEVC re-encode)
SELECT "SeriesName", "SeasonName", "EpisodeNumber", "Name", "Width", "Height"
FROM library."VideoItems_v"
WHERE "Type" LIKE '%Episode%'
  AND "VideoCodec" = 'h264'
ORDER BY "SeriesName", "SeasonNumber", "EpisodeNumber";

---

library."UserPlaybackHistory_v"

Per-user watch history joined with item metadata and a calculated playback progress percentage.

Use when: reporting on viewing activity, finding in-progress items, or checking which users have watched what.

Columns of note:

Column	Description
Username	Jellyfin username
ItemName	Name of the item
ItemType	Jellyfin type name
Played	true if the item has been marked as played
PlayCount	Number of times fully played
LastPlayedDate	Timestamp of the most recent playback
PlaybackPositionTicks	Raw position (divide by 10,000,000 for seconds)
ProgressPct	Calculated percentage through the item (0–100), NULL if no runtime
AudioStreamIndex	Last-used audio track index
SubtitleStreamIndex	Last-used subtitle track index

Example queries:

-- All in-progress items for a user (started but not finished)
SELECT "ItemName", "ItemType", "SeriesName", "ProgressPct", "LastPlayedDate"
FROM library."UserPlaybackHistory_v"
WHERE "Username" = 'alice'
  AND "Played" = false
  AND "ProgressPct" > 0
ORDER BY "LastPlayedDate" DESC;

-- Top 10 most-played items across all users
SELECT "ItemName", "ItemType", SUM("PlayCount") AS "TotalPlays"
FROM library."UserPlaybackHistory_v"
GROUP BY "ItemName", "ItemType"
ORDER BY "TotalPlays" DESC
LIMIT 10;

---

library."ItemProviders_v"

Items with their external provider IDs (IMDb, TMDB, TVDB, etc.) pivoted into named columns. Providers not explicitly named appear in a JSONB OtherProviders column.

Use when: cross-referencing Jellyfin items against external databases, finding items with missing metadata IDs, or bulk-exporting IDs for external tools.

Columns of note:

Column	Description
ImdbId	IMDb identifier (e.g. tt0111161)
TmdbId	The Movie Database ID
TvdbId	TheTVDB series/episode ID
TvRageId	TVRage ID (legacy)
MusicBrainzAlbumId	MusicBrainz album MBID
MusicBrainzArtistId	MusicBrainz artist MBID
OtherProviders	JSONB object of any remaining provider key/value pairs

Example queries:

-- Movies missing a TMDB ID
SELECT "Name", "ProductionYear", "ImdbId"
FROM library."ItemProviders_v"
WHERE "Type" LIKE '%Movie%'
  AND "TmdbId" IS NULL
ORDER BY "Name";

-- Look up an item by IMDb ID
SELECT "ItemId", "Type", "Name", "ProductionYear"
FROM library."ItemProviders_v"
WHERE "ImdbId" = 'tt0111161';

---

library."ItemPeople_v"

All cast and crew entries linked to the items they appear in.

Use when: browsing which items feature a specific actor or director, building cast-focused reports, or auditing people metadata.

Columns of note:

Column	Description
PersonName	Name of the person
PersonType	Role type: Actor, Director, Writer, Producer, etc.
Role	Specific character name or role description (may be empty)
SortOrder / ListOrder	Display ordering within the item's people list

Example queries:

-- All items featuring a specific actor
SELECT "ItemType", "ItemName", "SeriesName", "ProductionYear", "Role"
FROM library."ItemPeople_v"
WHERE "PersonName" = 'Bryan Cranston'
  AND "PersonType" = 'Actor'
ORDER BY "ProductionYear";

-- Directors with the most items in the library
SELECT "PersonName", COUNT(*) AS "DirectedItems"
FROM library."ItemPeople_v"
WHERE "PersonType" = 'Director'
GROUP BY "PersonName"
ORDER BY "DirectedItems" DESC
LIMIT 20;

---

library."LibrarySummary_v"

Aggregate statistics broken down by item type — one row per type. Provides a quick dashboard overview of the entire library.

Use when: getting a high-level snapshot of library size, total runtime, storage usage, and video quality distribution.

Columns of note:

Column	Description
Type	Jellyfin item type
ItemCount	Total number of items of this type
TotalRuntimeHours	Sum of all runtimes in hours
TotalSizeGB	Sum of all file sizes in gigabytes
AvgCommunityRating	Average community rating across items with a rating
Count4K	Items with primary video height ≥ 2160
Count1080p	Items with height 1080–2159
Count720p	Items with height 720–1079
CountSD	Items with height < 720
CountDolbyVision	Items with a Dolby Vision video stream
CountHDR10Plus	Items with HDR10+ flag set
CountHDR10	Items with HDR10 (smpte2084 transfer, no DV or HDR10+)

Example:

-- Full summary
SELECT "Type", "ItemCount", "TotalRuntimeHours", "TotalSizeGB",
       "Count4K", "Count1080p", "Count720p", "CountSD",
       "CountDolbyVision", "CountHDR10Plus", "CountHDR10"
FROM library."LibrarySummary_v";

---

StreamType Reference

The StreamType integer used in MediaStreamInfos and MediaStreamInfos_v maps to:

Value	Type
0	Audio
1	Video
2	Subtitle
3	EmbeddedImage
4	Data / Attachment