Documentation Index
Fetch the complete documentation index at: https://mintlify.com/chrisbenincasa/tunarr/llms.txt
Use this file to discover all available pages before exploring further.
Local Media Sources allow you to schedule media directly from your filesystem without needing a separate media server like Plex, Jellyfin, or Emby. Tunarr traverses your directories to discover media files and their metadata, which can then be added to channels just like content from any other source.
Local sources are especially useful if your media is not managed by a server, if you want to include filler content like commercials or bumpers, or if you simply prefer a lightweight setup with no external dependencies.
Tunarr uses NFO files — small XML sidecar files stored alongside your media — to read rich metadata such as titles, descriptions, artwork references, genres, and external IDs. If your media does not already have NFO files, many popular tools can generate them for you, including:
- Jellyfin and Emby — both support writing NFO files for managed libraries
- Sonarr, Radarr, and other *arr stack applications
Even without NFO files, Tunarr can still scan most library types using filenames and embedded audio/video tags as a fallback. See the individual library type sections below for details.
Ignoring Folders
To exclude a folder from scanning, create an empty file named .tunarrignore inside it. Tunarr also automatically skips any folder or file whose name begins with a ..
Library Types
Tunarr supports five distinct library types for local media. Select the appropriate type when creating the local source so Tunarr knows which directory conventions and metadata formats to expect.
Movies
TV Shows
Other Videos
Music
Music Videos
Movie libraries support several directory structures. The recommended approach is one subfolder per movie, with the video file and an NFO file inside.Example directory layout:movies/
├── The Matrix (1999)/
│ ├── The Matrix (1999).mkv
│ └── movie.nfo
│
├── The Matrix Reloaded (2003)/
│ ├── The Matrix Reloaded (2003).mkv
│ └── The Matrix Reloaded (2003).nfo
│
├── The Matrix Revolutions (2003).mkv
└── The Matrix Revolutions (2003).nfo
movie.nfo. For flat files, it looks for $MOVIE_FILE.nfo where $MOVIE_FILE is the exact video filename without its extension.Artwork: Tunarr scans for poster, fanart, landscape, and banner artwork files alongside each movie entry.Fallback: Without an NFO file, Tunarr parses metadata from the filename itself, including the year and external IDs (IMDb, TMDB), using built-in regex patterns. TV Show libraries require each series to have its own subfolder within the library root. Season subfolders are optional but recommended for clean organization.Example directory layout:tv/
├── Breaking Bad/
│ ├── tvshow.nfo
│ └── Season 01/
│ ├── Breaking Bad (2008) - S01E01 - Pilot.mkv
│ └── Breaking Bad (2008) - S01E01 - Pilot.nfo
│
└── Californication/
├── tvshow.nfo
├── Californication (2007) - S01E01 - Pilot.mkv
├── Californication (2007) - S01E01 - Pilot.nfo
└── Californication (2007) - S01E01 - Pilot.en.srt
tvshow.nfo and placed in the show’s root folder. Each episode should have its own NFO file named identically to the video file but with .nfo substituted for the video extension.Artwork: Tunarr scans for poster, fanart, landscape, and banner artwork for each show, season, and episode.Fallback: Without tvshow.nfo, Tunarr creates a show entry using the folder name and no additional metadata. Fallback metadata is not supported for individual episodes or seasons at this time. Other Videos libraries support a freeform directory structure of arbitrary depth, including files placed directly in the library root. This type is ideal for filler content such as commercials, bumpers, or short clips that don’t fit the strict movie or TV show conventions.Example directory layout:commercials/
├── 1999/
│ ├── Coke.mkv
│ └── Coke.nfo
│
├── 2000/
│ └── Food/
│ ├── Burger King.mkv
│ └── Burger King.nfo
│
├── Random.mkv
└── Random.nfo
$VIDEO.nfo where $VIDEO is the exact video filename with the extension swapped. NFO files may use either a <movie> or <episodedetails> root tag.Artwork: Tunarr scans for thumbnail artwork for each video item.Fallback: Without an NFO file, Tunarr creates an entry using the video filename as the title. The file’s local directory path is also available as a tag (for example, commercials/1999/), which can be used for filtering when scheduling. Music libraries expect a hierarchical structure: artist folders at the top level, album folders nested within each artist, and track files inside album folders.Example directory layout:music/
├── Billy Joel/
│ ├── artist.nfo
│ ├── folder.jpg
│ ├── Greatest Hits Volume I & II (1985)/
│ │ ├── album.nfo
│ │ ├── folder.jpg
│ │ ├── 01 - Piano Man.flac
│ │ └── 02 - The Entertainer.flac
│ └── The Stranger (1977)/
│ ├── album.nfo
│ ├── 01 - Movin' Out.mp3
│ └── 02 - The Stranger.mp3
│
└── The Beatles/
├── artist.nfo
└── Abbey Road (1969)/
├── album.nfo
└── 01 - Come Together.m4a
.aac, .aif, .aifc, .aiff, .alac, .dff, .dsf, .flac, .mp3, .m4a, .ogg, .opus, .oga, .ogx, .spx, .wav, .wmaNFO metadata: Tunarr supports NFO files for both artists (artist.nfo) and albums (album.nfo), following Kodi-compatible conventions. Key supported fields include:
- Artist:
name, sortname, musicBrainzArtistID, genre, style, mood, born, formed, biography
- Album:
title, musicbrainzalbumid, genre, style, mood, theme, releasedate, label, compilation, albumArtistCredits
Track metadata: Tunarr reads native embedded audio tags (ID3v1, ID3v2, APE, Vorbis comments, iTunes/MP4 tags) directly from track files. Metadata such as genre extracted from tracks is retroactively applied to the parent album.Artwork: Artist folders are scanned for poster.* or folder.* (poster) and fanart.* and banner.*. Album folders are scanned for poster.* or folder.*.Fallback: Without NFO files, Tunarr uses embedded audio tags for title, track number, year, and genres. Artist and album names fall back to the folder name. Album folder names may include a year in parentheses (for example, Album Name (2024)) which Tunarr parses automatically. Tracks missing a title or track number in embedded tags are skipped during scanning. Music Video libraries support a freeform directory structure of arbitrary depth, similar to Other Videos. You can organize music videos by artist, genre, era, or any folder layout you prefer.Example directory layout:music_videos/
├── Artist Name/
│ ├── Song Title.mkv
│ └── Song Title.nfo
│
├── Another Artist/
│ ├── Video One.mp4
│ ├── Video One.nfo
│ ├── Video Two.mp4
│ └── Video Two.nfo
│
├── Random Video.mkv
└── Random Video.nfo
.mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, and other common video formats.NFO metadata: Tunarr reads NFO files using the <musicvideo> root tag convention from Kodi. Each video’s NFO file should be named $VIDEO.nfo where $VIDEO matches the video filename with the extension swapped. Supported fields include:| Field | Description |
|---|
title | Video title (required) |
artist | One or more artist names |
album | Associated album |
plot | Description or plot summary |
premiered | Release date (YYYY-MM-DD) |
year | Release year |
genre | One or more genre tags |
director | One or more directors |
tag | One or more keyword tags |
studio | Studio or record label |
thumb | Thumbnail artwork references |
<?xml version="1.0" encoding="UTF-8"?>
<musicvideo>
<title>Thriller</title>
<artist>Michael Jackson</artist>
<album>Thriller</album>
<year>1983</year>
<genre>Pop</genre>
<director>John Landis</director>
</musicvideo>
Music videos can also be imported from Jellyfin and Emby servers. Music Video libraries from those sources are synced automatically when the library is enabled for synchronization. 