README
Wibby Server is a self-hosted personal video media server built for Apple Silicon Macs. It uses a Go backend, SQLite for persistence, and a React web app.
The macOS version is currently stable. Planned platform support will follow in this order:
- Docker
- Windows
- Ubuntu
The broader Wibby ecosystem is also in progress, with apps planned for:
- Android TV
- iOS, including iPhone and iPad
- Apple TV
- Android
Apple Vision Pro support may be explored in the future.
Accepted Media Naming Formats
Wibby scans supported video files recursively inside each library root.
Supported video extensions:
.mkv
.mp4
.m4v
.avi
.mov
.webm
Ignored examples:
.DS_Store
Thumbs.db
._filename.mkv
sample.mkv
Movies
Movie libraries accept folder-based names, file-based names, and scene-style names.
Recommended movie format
Movies/
Movie Name (Year)/
Movie Name (Year).mkv
Example:
Movies/
Batman Begins (2005)/
Batman Begins (2005).mp4
Parsed as:
Title: Batman Begins
Year: 2005
Movie file directly in the library root
Movies/
Movie Name (Year).mkv
Example:
Movies/
Inception (2010).mkv
Parsed as:
Title: Inception
Year: 2010
Movie folder with provider ID
Movies/
Movie Name (Year) {tmdb-ID}/
Movie Name (Year) {tmdb-ID}.mkv
Example:
Movies/
Batman Begins (2005) {tmdb-272}/
Batman Begins (2005) {tmdb-272}.mp4
Parsed as:
Title: Batman Begins
Year: 2005
Provider: tmdb
Provider ID: 272
Scene-style movie filename
Movies/
Movie.Name.Year.Quality.Source.Codec.mkv
Example:
Movies/
Inception.2010.1080p.BrRip.x264.YIFY.mp4
Parsed as:
Title: Inception
Year: 2010
Movie inside collection folders
Movies/
Collection Name/
Movie Name/
video-file.mkv
Example:
Movies/
Marvel/
Iron Man/
video-file.mkv
Parsed as:
Title: Iron Man
Better:
Movies/
Marvel/
Iron Man (2008)/
Iron Man (2008).mkv
Parsed as:
Title: Iron Man
Year: 2008
Loose movie filename fallback
Movies/
Movie Name.mkv
Example:
Movies/
Iron Man.mkv
Parsed as:
Title: Iron Man
No year is detected unless the folder or filename includes one.
Generic movie folder names
These folder names are treated as generic and are not used as movie titles:
Movies
Movie
Films
Film
TV Series
TV libraries are parsed as episodes.
The scanner accepts this layout:
TV Shows/
Show Name/
Season XX/
episode-file.mkv
With the updated parser, it also accepts flat Plex-style show folders:
TV Shows/
Show Name/
episode-file.mkv
TV show folder names
Show name only
TV Shows/
Show Name/
Example:
TV Shows/
Doctor Who/
Parsed as:
Show: Doctor Who
Show name with year
TV Shows/
Show Name (Year)/
Example:
TV Shows/
Doctor Who (1963)/
Parsed as:
Show: Doctor Who
Year: 1963
This is recommended when multiple shows share the same name.
Show name with TMDb ID
TV Shows/
Show Name (Year) {tmdb-ID}/
Example:
TV Shows/
The Office (UK) (2001) {tmdb-2996}/
Parsed as:
Show: The Office (UK)
Year: 2001
Provider: tmdb
Provider ID: 2996
Season folders
Season folders can use these formats:
Season 01
Season.01
Season_01
Season-01
Season 1
Examples:
TV Shows/
Doctor Who (1963)/
Season 25/
TV Shows/
The Office (UK) (2001) {tmdb-2996}/
Season 01/
Standard TV episode format
Recommended:
TV Shows/
Show Name (Year)/
Season XX/
Show Name - SXXEYY - Episode Title.mkv
Example:
TV Shows/
Doctor Who (1963)/
Season 25/
Doctor Who - S25E02 - The Happiness Patrol (1).mkv
Parsed as:
Show: Doctor Who
Year: 1963
Season: 25
Episode: 2
Episode title: The Happiness Patrol (1)
TV episode with show year in filename
TV Shows/
Show Name (Year)/
Season XX/
Show Name (Year) - SXXEYY - Episode Title.mkv
Example:
TV Shows/
Doctor Who (1963)/
Season 01/
Doctor Who (1963) - S01E01 - An Unearthly Child (1).mp4
Parsed as:
Show: Doctor Who
Year: 1963
Season: 1
Episode: 1
Episode title: An Unearthly Child (1)
Flat Plex-style TV episode format
Accepted with the updated parser:
TV Shows/
Show Name (Year)/
Show Name - SXXEYY - Episode Title.mkv
Example:
TV Shows/
Doctor Who (1963)/
Doctor Who - S25E02 (149) - The Happiness Patrol (1).mkv
Parsed as:
Show: Doctor Who
Year: 1963
Season: 25
Episode: 2
Episode title: (149) - The Happiness Patrol (1)
Cleaner version:
TV Shows/
Doctor Who (1963)/
Doctor Who - S25E02 - The Happiness Patrol (1).mkv
Parsed as:
Show: Doctor Who
Year: 1963
Season: 25
Episode: 2
Episode title: The Happiness Patrol (1)
Flat Plex-style TV episode with TMDb show folder
Accepted with the updated parser:
TV Shows/
Show Name (Year) {tmdb-ID}/
Show Name - SXXEYY - Episode Title.mkv
Example:
TV Shows/
The Office (UK) (2001) {tmdb-2996}/
The Office (UK) - S01E01 - Downsize.mp4
Parsed as:
Show: The Office (UK)
Year: 2001
Provider: tmdb
Provider ID: 2996
Season: 1
Episode: 1
Episode title: Downsize
Episode filename with only SXXEYY
Accepted with the updated parser when the show folder provides the show name:
TV Shows/
Show Name (Year)/
SXXEYY - Episode Title.mkv
Example:
TV Shows/
Doctor Who (1963)/
S25E02 - The Happiness Patrol (1).mkv
Parsed as:
Show: Doctor Who
Year: 1963
Season: 25
Episode: 2
Episode title: The Happiness Patrol (1)
Also accepted inside a season folder:
TV Shows/
Doctor Who (1963)/
Season 25/
S25E02 - The Happiness Patrol (1).mkv
Multi-episode TV filename
Accepted:
TV Shows/
Show Name (Year)/
Season XX/
Show Name - SXXEYY-EZZ - Episode Title.mkv
Example:
TV Shows/
Grey's Anatomy (2005)/
Season 02/
Grey's Anatomy (2005) - S02E01-E03.avi
Parsed as:
Show: Grey's Anatomy
Year: 2005
Season: 2
Episode: 1
Only the first episode number is stored.
Date-based TV episodes
Accepted:
TV Shows/
Show Name (Year)/
Season XX/
Show Name (Year) - YYYY-MM-DD - Episode Title.mkv
Example:
TV Shows/
The Colbert Report (2005)/
Season 08/
The Colbert Report (2005) - 2011-11-15 - Elijah Wood.avi
Parsed as:
Show: The Colbert Report
Year: 2005
Season: 8
Air date: 2011-11-15
Episode title: Elijah Wood
Loose TV fallback
If a video file is inside a valid show folder and season folder but the filename does not contain an episode number, Wibby may still accept it as a season item.
Example:
TV Shows/
Show Name (Year)/
Season 01/
random-video-file.mkv
Parsed as:
Show: Show Name
Year: Year
Season: 1
Episode: unknown
This is accepted, but not recommended.
Better:
TV Shows/
Show Name (Year)/
Season 01/
Show Name - S01E01 - Episode Title.mkv
Generic TV folder names
These folder names are treated as generic and are not used as show names:
TV
TV Show
TV Shows
Shows
Show
Series
Television
Television Shows
Recommended library layout
Movies:
Movies/
Batman Begins (2005)/
Batman Begins (2005).mp4
Inception (2010)/
Inception (2010).mkv
TV shows with season folders:
TV Shows/
Doctor Who (1963)/
Season 25/
Doctor Who - S25E01 - Remembrance of the Daleks (1).mkv
Doctor Who - S25E02 - The Happiness Patrol (1).mkv
Flat Plex-style TV shows:
TV Shows/
Doctor Who (1963)/
Doctor Who - S25E01 - Remembrance of the Daleks (1).mkv
Doctor Who - S25E02 - The Happiness Patrol (1).mkv
TV shows with TMDb hint:
TV Shows/
The Office (UK) (2001) {tmdb-2996}/
Season 01/
The Office (UK) - S01E01 - Downsize.mp4