ShowShark Media Naming Guide
This guide explains how ShowShark reads your folder and file names to identify
movies, TV shows, music, and YouTube archives. Following these conventions gives
ShowShark the best chance of finding the correct metadata from TMDB and OMDB.
Location Types
Every library location in ShowShark has a type. The type determines which
parsing rules are applied to the files inside it.
+----------+----------------------------------------------------------+
| Type | What ShowShark expects inside |
+----------+----------------------------------------------------------+
| Movies | One folder per movie |
| TV Shows | One folder per show, with season subfolders |
| YouTube | One folder per channel, video files inside |
| Music | Artist / Album / Track folder hierarchy |
| General | Mix of movies and shows (auto-detected) |
| Pictures | Not scanned |
+----------+----------------------------------------------------------+
Typed locations (Movies, TV Shows, YouTube, Music) skip auto-detection and
route files directly. This avoids misclassification; a "General" location has
to guess whether each file is a movie or a TV episode based on context clues.
Recommendation: Always use a typed location when possible. If your media is
a mix of movies and shows in the same folder tree, use General.
Movies
Folder Naming
Each movie should live in its own folder. ShowShark reads the folder name to
determine the title and year, then searches TMDB/OMDB.
Best format: Movie Title (YYYY)
The year in parentheses is the single most important hint you can provide. It
disambiguates remakes, reboots, and similarly-named films.
+----------------------------------------+-----------------------+------+
| Folder Name | Parsed Title | Year |
+----------------------------------------+-----------------------+------+
| The Matrix (1999) | The Matrix | 1999 |
| Dune (2021) | Dune | 2021 |
| Blade Runner 2049 (2017) | Blade Runner 2049 | 2017 |
| John Wick (2023) - Chapter 4 | John Wick Chapter 4 | 2023 |
| Rampage.2018.1080p.BluRay.DTS.x264 | Rampage | 2018 |
| Some Movie | Some Movie | none |
+----------------------------------------+-----------------------+------+
Three naming patterns are recognized:
Pattern 1: Title (YYYY) -- preferred, cleanest
Pattern 2: Title (YYYY) - Subtitle -- year in the middle
Pattern 3: Title.YYYY.720p.BluRay -- dot-separated scene names
Patterns 1 and 2 use parenthesized four-digit years. Pattern 3 uses a
dot-separated year (common in scene release names).
Title Candidate Generation
ShowShark generates multiple search candidates from a single folder name to
improve matching odds. For example:
Folder: "John Wick (2023) - Chapter 4"
Candidates tried in order:
1. John Wick Chapter 4
2. Chapter 4
3. John Wick
This means the subtitle after the year is incorporated into the search. If
the full combined title does not match, the base title is tried as a fallback.
Trailing Articles
Folder names with a trailing article are automatically uninverted before
searching:
+------------------------------+----------------------------+
| Folder Name | Searched As |
+------------------------------+----------------------------+
| Muppet Movie, The (1979) | The Muppet Movie |
| Day to Remember, A (2003) | A Day to Remember |
+------------------------------+----------------------------+
And / & Variants
ShowShark automatically generates both "and" and "&" variants for movie titles:
"Simon and Garfunkel (2020)" --> also tries "Simon & Garfunkel"
"Tom & Jerry (2021)" --> also tries "Tom and Jerry"
NFO Files (IMDB ID Hint)
If a .nfo file in the movie folder contains an IMDB ID (e.g. tt0133093),
ShowShark will use it to resolve the canonical title from OMDB before
searching. This is the most reliable way to ensure a correct match for
hard-to-find titles.
The Matrix (1999)/
movie.mkv
movie.nfo <-- contains "tt0133093" anywhere in the file
Subfolder Fallback
If the immediate parent folder does not contain a (YYYY) year, ShowShark
checks the grandparent. This handles release-group subfolder structures:
The Matrix (1999)/
The.Matrix.1999.Remastered.1080p/
movie.mkv <-- year found in grandparent
Movie File Layout (Recommended)
Movies/
The Matrix (1999)/
The Matrix.mkv
Inception (2010)/
Inception.mkv
Blade Runner 2049 (2017)/
Blade Runner 2049.mkv
Blu-ray Disc (BDMV)
Blu-ray disc folders are detected automatically when a BDMV/ subdirectory
is present. The folder naming rules are the same as regular movies:
Movies/
The Matrix (1999)/
BDMV/
index.bdmv
STREAM/
00001.m2ts
TV Shows
Folder Structure
ShowShark expects this hierarchy:
Show Name (YYYY)/
Season NN/ or sNN/
episode files
The show folder name is parsed the same way as movies -- a title with an
optional (YYYY) year suffix. The year is especially important when multiple
shows share the same name.
+---------------------------------------+---------------------+------+
| Show Folder | Parsed Title | Year |
+---------------------------------------+---------------------+------+
| Inspector Gadget (1983) | Inspector Gadget | 1983 |
| Inspector Gadget (2015) | Inspector Gadget | 2015 |
| The Sopranos | The Sopranos | none |
| Breaking Bad (2008) | Breaking Bad | 2008 |
+---------------------------------------+---------------------+------+
Important: Without the year, two shows with the same name will be merged
into a single entry. The year tells ShowShark to search TMDB specifically for
that year's series, resulting in separate entries with correct metadata.
Season Folders
Season directories are identified by these patterns (case-insensitive):
+---------------+----------------+
| Folder Name | Season Number |
+---------------+----------------+
| s01 | 1 |
| S02 | 2 |
| Season 03 | 3 |
| Season 12 | 12 |
+---------------+----------------+
Episode File Naming
ShowShark looks for episode numbers in the filename using several patterns,
tried in this order:
+----------------------------+--------+---------+-------------------------+
| Filename Pattern | Season | Episode | Notes |
+----------------------------+--------+---------+-------------------------+
| show.s03e12.mkv | 3 | 12 | Standard, recommended |
| show.S03E12.mkv | 3 | 12 | Case-insensitive |
| show.s01e048-051.mkv | 1 | 48 | Range (first used) |
| show.2e16.mkv | 2 | 16 | Compact (2+ digit ep) |
| show.e12.mkv | -- | 12 | Episode only |
| show.3x12.mkv | 3 | 12 | Alternative format |
| show.1of3.mkv | -- | 1 | Mini-series format |
+----------------------------+--------+---------+-------------------------+
When a file is inside a recognized season folder, the season from the folder
takes priority over any season parsed from the filename.
Recommended format: s01e01 -- it is the most widely recognized and
unambiguous pattern.
Bare Number Fallback
If none of the standard episode patterns are found, ShowShark tries to extract
an episode number from bare numbers in the filename. This uses two strategies:
Strategy 1 -- Packed season+episode (3-4 digits):
File in s02/ folder: "jetsons 206 winner takes all.avi"
206 --> season 2, episode 06 (matches because file is in s02/)
Strategy 2 -- Simple bare number:
File in s01/ folder: "DuckTales - 89 - Title.mkv"
89 --> episode 89
Intermediate Directory Fallback
If the episode number cannot be found in the filename, ShowShark also checks
intermediate directory names between the season folder and the file. This
handles cases where filenames are obfuscated but the episode info is in a
parent folder:
Show Name/s01/e05 - Title/obfuscated_file.mkv
^^^ episode 5 found here
Part Number Detection (Shows Location Only)
In a TV Shows location, files with "Part" numbering but no season folder
are treated as a mini-series at season 1:
+-----------------------------------+--------+---------+
| Filename | Season | Episode |
+-----------------------------------+--------+---------+
| show.name.Part1.720p.mkv | 1 | 1 |
| show.name.Part.2.mkv | 1 | 2 |
| show.name.CD1.mkv | 1 | 1 |
| show.name.Disc2.mkv | 1 | 2 |
+-----------------------------------+--------+---------+
This only applies in typed TV Shows locations. In General locations, part
numbers are not used for episode detection (to avoid misclassifying multi-part
movies).
TV Show File Layout (Recommended)
TV Shows/
Breaking Bad (2008)/
s01/
Breaking.Bad.s01e01.Pilot.mkv
Breaking.Bad.s01e02.mkv
s02/
Breaking.Bad.s02e01.mkv
Inspector Gadget (1983)/
Season 01/
Inspector.Gadget.s01e01.mkv
Inspector Gadget (2015)/
Season 01/
Inspector.Gadget.s01e01.mkv
Blu-ray Disc TV Seasons
For Blu-ray TV seasons, place the disc folder inside a season directory:
Show Name/
s01/
Disc 1/
BDMV/
...
ShowShark reads the show name from the grandparent of the season directory and
numbers episodes by playlist order on the disc.
YouTube Archives
YouTube-type locations expect one subfolder per channel, with video files
inside. ShowShark uses dates in the filenames for season/episode numbering
(year = season, MMDD = episode number).
Folder Structure
YouTube/
Channel Name/
20230415 - Video Title [dQw4w9WgXcQ].mp4
2023-06-01 - Another Video [xYzAbCdEfGh].mp4
Filename Parsing
ShowShark extracts three things from YouTube filenames:
1. Date --> used for season (year) and episode (MMDD) numbering
2. Video ID --> 11-character ID in square brackets, used for API lookup
3. Title --> remaining text after removing the date and video ID
Date Formats
These date formats are recognized anywhere in the filename:
+--------------------+--------+---------------------------+
| Format | Example| Notes |
+--------------------+--------+---------------------------+
| yyyymmdd | 20230415 | Compact, no separators |
| yyyy-mm-dd | 2023-04-15 | ISO style |
| yyyy.mm.dd | 2023.04.15 | Dot-separated |
| mm-dd-yyyy | 04-15-2023 | US convention |
| mm/dd/yyyy | 04/15/2023 | US with slashes |
+--------------------+--------+---------------------------+
When the date format is ambiguous (could be mm-dd or dd-mm), ShowShark
prefers MM-DD-YYYY (US convention) but falls back to DD-MM-YYYY if the
first interpretation has an invalid month.
Video ID
The video ID is an 11-character alphanumeric string in square brackets,
typically appended by yt-dlp:
Why This Video Has 1000 Views [dQw4w9WgXcQ].mp4
^^^^^^^^^^^
If present, ShowShark uses the video ID for a direct YouTube API lookup to
get the official title and description. If no video ID is embedded, ShowShark
falls back to fuzzy title matching against the channel's uploads list.
yt-dlp Metadata Files
ShowShark can read .info.json sidecar files generated by yt-dlp. These
provide the richest metadata (title, description, tags, categories) without
any API calls. If a .info.json file exists alongside the video, it is
preferred over all other metadata sources.
Dateless Files
Files without a recognizable date are placed in season 0 and numbered
sequentially in the order they are discovered during the scan.
YouTube File Layout (Recommended)
YouTube/
Tom Scott/
20210305 - Why This Video Has 47 Million Views [BxV14h0kFs0].mp4
20210305 - Why This Video Has 47 Million Views [BxV14h0kFs0].info.json
Technology Connections/
20230801 - The Dishwasher [Ll6-jJ6WtGE].mp4
Music
Music files are identified by their audio file extension. ShowShark reads
embedded tags (via GStreamer) first and uses the directory structure as a
fallback when tags are missing or incomplete.
Tag Priority
1. Embedded tags (ID3, Vorbis, etc.) -- artist, album, title, track
2. Directory structure fallback -- grandparent = artist,
parent = album,
filename = title
Filename Parsing
When tags are missing, the track number and title are parsed from the
filename:
+----------------------------+-------+-----------------+
| Filename | Track | Title |
+----------------------------+-------+-----------------+
| 01 - Song Title.mp3 | 1 | Song Title |
| 01. Song Title.flac | 1 | Song Title |
| 01 Song Title.ogg | 1 | Song Title |
| 12 - Track Name.m4a | 12 | Track Name |
| Song Title.mp3 | none | Song Title |
+----------------------------+-------+-----------------+
Album Art
ShowShark looks for album art in this priority order:
1. Embedded art in the audio file (ID3 APIC, etc.)
2. Image file in the same directory, matching these names:
cover.jpg, cover.png, folder.jpg, folder.png,
album.jpg, album.png, front.jpg, front.png
The first album art found for an album wins; subsequent tracks in the same
album will not override it.
Music File Layout (Recommended)
Music/
Pink Floyd/
The Dark Side of the Moon/
01 - Speak to Me.flac
02 - Breathe.flac
cover.jpg
Radiohead/
OK Computer/
01 - Airbag.flac
General Locations
General locations use heuristics to determine whether each file is a movie or
a TV episode. The rules are:
1. If a season directory is found in the path --> TV episode
2. If the filename contains an episode pattern --> TV episode
3. Otherwise --> Movie
Because this is guesswork, typed locations (Movies, TV Shows) will always
produce better results. Use General only when your folder tree mixes both
types.
Supported File Extensions
ShowShark recognizes the following file types:
Video: mp4 m4v mov avi mkv wmv flv webm mpeg mpg 3gp
ts mts m2ts
Audio: mp3 m4a aac flac wav aiff ogg wma opus alac
Image: jpg jpeg png heic heif gif tiff tif webp bmp
(images are skipped during scanning; only used for album art)
Quick Reference: Best Practices
+--------+--------------------------------------------------------------+
| Do | Include the year in parentheses for movies and shows |
+--------+--------------------------------------------------------------+
| Do | Use typed locations (Movies, TV Shows) instead of General |
+--------+--------------------------------------------------------------+
| Do | Use s01e01 format for episode filenames |
+--------+--------------------------------------------------------------+
| Do | Use named season folders (s01, Season 01) |
+--------+--------------------------------------------------------------+
| Do | Keep one movie per folder, one show per folder |
+--------+--------------------------------------------------------------+
| Do | Add .nfo files with IMDB IDs for hard-to-match movies |
+--------+--------------------------------------------------------------+
| Do | Keep yt-dlp .info.json files alongside YouTube downloads |
+--------+--------------------------------------------------------------+
| Avoid | Putting two different shows with the same name without years |
+--------+--------------------------------------------------------------+
| Avoid | Mixing movies and episodes in the same folder |
+--------+--------------------------------------------------------------+
| Avoid | Bare numbers in filenames without standard episode patterns |
+--------+--------------------------------------------------------------+
| Avoid | Loose files without a parent folder (e.g. movie.mkv at root) |
+--------+--------------------------------------------------------------+