Skip to content

MOVIE_NAMING.md

Latest commit

 

History

History
164 lines (119 loc) · 3.93 KB

MOVIE_NAMING.md

File metadata and controls

164 lines (119 loc) · 3.93 KB
Raw

Movie naming guidelines

Koko matches movie files more reliably when each media type lives under its own top-level folder and movie files follow a predictable naming pattern.

Recommended folder layout

Keep movies separate from shows, music, books, and photos.

/Media
  /Books
  /Movies
  /Music
  /Photos
  /TV Shows

When you create a movie library in Koko, point it at the movie root such as Media/Movies.

Preferred movie layout

The most reliable option is one folder per movie:

/Movies
  /Movie Title (2024)
    Movie Title (2024).mkv

This layout works well when you also keep artwork, subtitles, or alternate editions alongside the movie.

Examples:

/Movies
  /Avatar (2009)
    Avatar (2009).mkv
  /Batman Begins (2005)
    Batman Begins (2005).mp4
    Batman Begins (2005).en.srt
    poster.jpg

Flat movie layout

Koko also supports movies stored directly inside the library root:

/Movies
  Avatar (2009).mkv
  Batman Begins (2005).mp4

This can work well for smaller libraries, but folder-per-movie is still recommended when you have local assets.

Optional metadata tags in braces

You can include helpful tags in curly braces or square brackets after the movie title and year. Multiple tags can be split across multiple bracket groups, or combined in one group with :.

Supported examples:

Batman Begins (2005) {tmdb-272}.mp4
Batman Begins (2005) {imdb-tt0372784}.mp4
Batman Begins (2005) [tmdb-272:tvdb-321].mp4
Batman Begins (2005) [tmdb-272] [edition-Blu-ray].mp4
Blade Runner (1982) {edition-Final Cut}.mkv

Useful tag forms:

  • {tmdb-272}
  • {tvdb-321}
  • {imdb-tt0372784}
  • {edition-Director's Cut}
  • {edition-Extended}

Koko strips these tags before title matching and uses provider identifiers as hints where possible. TMDB matching can use direct tmdb IDs and can resolve tvdb or imdb IDs through TMDB's external-id lookup. TheTVDB matching can use direct tvdb IDs.

Legacy and quality suffixes

Koko also accepts legacy file names where the format is separated by a dash:

Beyond The Sky (2018) - Bluray-1080p.mkv
Movie Title (2024) - 2160p WEB-DL x265.mkv

The format suffix is stripped from the display title and metadata search title. You may also put the format in brackets:

Beyond The Sky (2018) [Bluray-1080p].mkv
Movie Title (2024) [2160p:WEB-DL:x265].mkv

For titles that normally contain a colon but are stored on Windows, use a dash before the subtitle:

Top Gun- Maverick (2022) - 1080p.mkv

Koko displays this as Top Gun: Maverick.

Multiple editions

If you keep more than one edition of the same movie, include the edition tag in the folder name, filename, or both.

/Movies
  /Blade Runner (1982) {edition-Director's Cut}
    Blade Runner (1982) {edition-Director's Cut}.mp4
  /Blade Runner (1982) {edition-Final Cut}
    Blade Runner (1982) {edition-Final Cut}.mkv

Split movie files

Split files are best kept in their own movie folder.

Koko recognizes common part suffixes such as:

  • cd1, cd2
  • disc1, disc2
  • disk1, disk2
  • dvd1, dvd2
  • part1, part2
  • pt1, pt2

Example:

/Movies
  /The Dark Knight (2008)
    The Dark Knight (2008) - pt1.mp4
    The Dark Knight (2008) - pt2.mp4

General naming tips

  • Include the release year whenever possible.
  • Prefer spaces over noisy scene-release formatting.
  • Avoid leaving quality, codec, or release-group tags in the display title when you can place them elsewhere.
  • Keep subtitle, poster, and backdrop files in the same movie folder when you use local assets.
  • Keep folder and filename titles aligned to reduce ambiguous matches.

Examples Koko matches well

/Movies
  /Alien (1979)
    Alien (1979).mkv

/Movies
  /Dune Part Two (2024) {tmdb-693134}
    Dune Part Two (2024) {tmdb-693134}.mkv

/Movies
  /Mad Max Fury Road (2015) {edition-Black and Chrome}
    Mad Max Fury Road (2015) {edition-Black and Chrome}.mkv