Point a media player at a folder of video files and you get a list of file names. Holiday in Lisbon 2019.mp4, My Show S02E05.mkv, Garden Documentary (2014).mkv, IMG_2041.mov. What a person wants is a wall of posters, with Films, Series and their seasons, and a description when they open one.

Yonto Player does that for the video files you keep on a NAS, a USB drive or the device itself. This post covers the parser, the grouping, the order of artwork, and a lookup built so that no path or file name leaves the device.

The parser: decline to guess when the name is unclear

The parser is written from scratch in Kotlin. The idea is simple: split the name into tokens and find the first one that cannot be part of a title. That is where the title ends.

A marker that ends a title is a season or episode (S02E05, 2nd Season, 第3集), a date, a year, or a descriptive tag such as an edition. Here is the shape of it, as a simplified sketch with generic names, not the real file:

// Simplified sketch of the idea, not the real parser. fun parse(tokens: List<String>): Parsed { var titleEnd: Int? = null var year: Int? = null var season: Int? = null var episode: Int? = null fun cut(at: Int) { if (titleEnd == null) titleEnd = at } for ((i, token) in tokens.withIndex()) { val se = seasonAndEpisode(token) when { se != null -> { cut(i); season = se.season; episode = se.episode } isYear(token) && i > 0 -> { cut(i); year = token.toInt() } isReleaseTag(token) -> cut(i) } } val title = tokens.take(titleEnd ?: tokens.size).joinToString(" ") return Parsed(title, year, season, episode) } 

The real code has far more cases; the telling ones are where it declines to read a marker.

  • A year is 1900 to 2030, and never the first word. 1917 and 2012 are titles. Mars 2049 is a title with no year, and Mars 2049 (2017) finds 2017. Of a run of years, the last one is the year.
  • A bare number is an episode only where the structure says it is a series. Garden Notes - 3.mkv is a film. In a name with a hyphen and a number, the number alone is not enough; a file inside a season folder is.
  • Words that are also words stay words. Space Saga Episode 4 keeps its number in the title.

All three come from one decision: where a name gives no clear signal, a wrong guess is worse than none. A film called an episode moves into Series. So a name that says nothing, such as a camera counter or a timestamp, has no title, and the video stays under Other videos.

Names are normalised first (NFKC). English season and episode markers are read, and so are the Chinese (第二季, 第3集) and Spanish (Temporada 1, Capítulo 2) ones, which are rewritten to the same tokens first.

From parsed names to Films and Series

The grouping step reads each file together with the folders above it.

  • The nearest folder with a season in its name (Season 01, 第一季, Temporada 2) numbers a file that has no number of its own.
  • The nearest folder with a real title (not a container such as Movies) names a file that has none.
  • A file's own title wins over a folder's, so a flat folder of many shows stays many shows.

A series needs an episode number or a date, and a title from the file or from a show folder. Anything short of that stays under Other videos.

A rescan is incremental: it lists every folder that has subfolders, and skips a leaf folder whose modified time has not changed. Skipping only leaves is deliberate: a directory's time changes when something is added directly in it, not two levels down, and the leaves are most of a NAS. A scan runs when you open the source and every half hour, and Rescan everything reads all folders again.

Artwork has an order

Each title gets its poster and description from three places, in this order:

  1. Your own files. Posters and backdrops named the way Kodi, Jellyfin and Emby name them (poster.jpg, folder.jpg, <video name>-poster.jpg, fanart.jpg) and the .nfo files those tools write. A picture named for a folder counts only where the folder holds one title's videos, because a poster.jpg in a folder of thirty films belongs to none of them.
  2. An online lookup, for what is still missing. It fills gaps and never replaces what your files say.
  3. A frame from the video. A title with neither shows a picture of its video, a thumbnail or a frame from a little way in.

The merge is small and explicit: each field takes your file's value first and the match's only when yours is empty. A title with both a poster and a description of its own is not looked up at all.

What leaves the device

The lookup is asked with the title and year as read from the file and folder names (a file with no title of its own takes the nearest folder's), the kind (film or series), the app's language, any ids found in a .nfo or in the name, and, for two series of the same name, an episode number to tell them apart. It is not asked with a path or the server's address.

The query type has no field for a path:

// Simplified sketch of the idea, not the real file. data class TitleQuery( val title: String, // parsed from the name val kind: TitleKind, // FILM or SERIES val year: Int?, val ids: ExternalIds = ExternalIds(), val episode: EpisodeProbe? = null, ) 

Your own artwork and .nfo files are not sent. Each files source has a switch, Look up posters and descriptions online, and with it off nothing is sent for that source. If the service cannot be reached, the library shows what it has and retries later.

Scoring the answers on the device

The service hands back every title that fits a search, with every name each has. It does not choose. The app chooses, in the matcher.

  1. If the .nfo or the file name carries an id ({tmdb-603}, [imdbid-tt0133093]), the title is found by that id.
  2. Otherwise the app searches by name, and each result is scored.

The scoring idea, simplified:

// Simplified sketch of the idea, not the real matcher. fun score(result: Result, wanted: String, year: Int?, kind: Kind): Int? { if (result.kind != kind) return null var score = when { wanted in listOf(result.title, result.originalTitle).map(::fold) -> 3 result.aliases.any { fold(it) == wanted } -> 2 else -> return null // not this title at all } if (year != null) { val off = abs((result.year ?: return null) - year) if (off > 1) return null // a year is allowed to be one off score += if (off == 0) 2 else 1 } return score } 

Names are compared after a fold that drops case, accents, punctuation, spaces and a leading "the", and turns Traditional characters into Simplified.

The app takes a result only when it is alone at the top. Two results with the same score are not a match, because a poster for the wrong show is worse than none. For series that tie, the app asks whether each has the files' episode, and then whether its title matches, for up to a few candidates. If that does not settle it, the title stays unmatched.

When the match is wrong

A match can be wrong, so the viewer has the last word. On a title's page, Wrong title? opens a search the viewer can edit, lists what it finds with posters and years, and offers None of these: use the file names. The choice is kept, and no later rescan or lookup changes it.

Takeaways

  • Let a parser decline to guess where the name gives no clear signal.
  • Make the privacy rule visible in the types: the query type has no field for a path.
  • Score candidates on the device, with a "must be alone at the top" rule, and give the viewer an override.

Read more