When a Filename Has to Become an Episode
Sonarr's parser faces a deceptively difficult question: when a release or local file contains a title and some numbers, what episode does it actually describe? This chapter examines the boundary between recognizing the shape of a name and proving its library identity. The reader should come away able to explain why daily dates, anime numbering, season packs, specials, and multi-episode releases need different interpretations—and why an uncertain match is safer to reject than to attach to the wrong episode.
A filename is not a canonical record. It is a message produced by an outside naming culture, and the message may use punctuation, abbreviations, release-group conventions, dates, or numbering that differ from Sonarr's stored model. The parser's job is to turn that message into structured evidence. A later stage can then compare that evidence with known series and episodes. Treating the first successful pattern match as final identity would confuse two different kinds of certainty.
A recognizable shape is not a confirmed identity
Imagine a release name that contains something resembling a season and episode marker. The parser can often identify the marker, separate the apparent series title from the release details, and extract quality or language information. That is useful, but it answers only a syntactic question: “What pieces of information appear to be encoded in this string?” It does not yet answer, “Which series in this library owns those episodes?”
Sonarr's parsed representation keeps this distinction visible. It can contain a release title and a series-title candidate, arrays of season and episode numbers, absolute episode numbers, an air date, flags for a full season or special, and tokens left over after the episode identifier. It can also carry quality, languages, release group, and release hash. These are separate fields because they have different meanings and different levels of reliability.
For example, a season number and an episode number can describe a standard series, but the same visible number can mean something else for an anime release that uses absolute numbering. A date can identify a daily program without a conventional season/episode marker. A “season” label can mean a complete season pack, a partial pack, or an extras package. The parser does not flatten these cases into one generic episode number. It records the interpretation that the naming pattern supports.
This separation also makes failure legible. If the parser cannot identify a series title, it has not produced a safe identity candidate. If it finds a season but no valid episode, the result may represent a season pack or a special rather than a single episode. If a name looks like a hash or another unusable generated token, Sonarr rejects it before trying to build a misleading match. The outcome is not “the parser failed to be clever.” It is “the available text did not provide enough trustworthy structure.”
The distinction between syntax and identity is the foundation for every later decision. A parser should be generous enough to understand real naming variation, but its output should remain explicit enough for the mapping stage to question it.
Why one universal numbering rule fails
Sonarr's parser handles several families of release shapes because episodic media is not named according to one global standard.
A standard series usually exposes a season and one or more episode numbers. A multi-episode release may repeat the marker, join several episode numbers, or use a range. The parser preserves the set of episodes rather than treating the range as a single opaque label. That matters when a file contains more than one episode: later import and policy logic must know the complete group.
A daily series may be identified by an air date instead of a season and episode. In that case, the date is not decorative text. It is the primary identity signal, and the parser validates dates rather than accepting every sequence of digits. Ambiguous day/month arrangements can be refused because choosing the wrong interpretation would shift the file to a different broadcast date.
Anime releases introduce another distinction: an absolute episode number can coexist with, or substitute for, season and episode numbering. The parser can record absolute numbers, season numbers, and multiple episodes separately. That gives downstream logic more than one possible identity signal without claiming they are interchangeable. A batch with a range of absolute episodes is different from a standard season pack, even if both contain many episodes.
Specials and season-zero conventions create another trap. A release may contain an episode marker that is really a special, or a title that has no normal episode number but carries enough information to be recognized as a special or full-season form. The parsed object includes flags for these cases so later logic does not mistake a special for an ordinary episode in a numbered season.
Season packs need similar care. A full season, a multi-season pack, a partial season, and a package of extras all have different consequences. A full season can be represented by a season-level fact rather than by an explicit list of episode numbers. A partial season must not be silently treated as complete. An extras package is not automatically a collection of regular episodes. The parser's job is to preserve those distinctions for the decision and import stages.
This is why pattern order and context matter. Sonarr preprocesses titles, removes file extensions and common noise, then tries an ordered collection of patterns. The patterns cover conventional names, dates, multi-part forms, anime styles, alternate languages, and other observed conventions. An ordered parser is practical because it can handle a large vocabulary, but it is also a boundary: an early pattern can shape how later text is interpreted. The source's tests therefore matter as evidence of intended behavior, while not proving that every possible real-world name is covered.
The same name carries several independent signals
Episode identity is only one thing Sonarr needs from a release or file. The parser separately extracts signals that later policy can use.
Quality parsing identifies source and resolution where the name provides them. The implementation recognizes categories such as broadcast, web, disc, remux, and other source forms, then combines them with resolution information. It also recognizes modifiers such as proper, repack, rerip, and version markers. A release can therefore be “the right episode” while still differing in quality or revision from another release. Keeping those values separate prevents a decision stage from treating episode identity as a proxy for media quality.
Language parsing is another independent signal. A title can indicate a language, several languages, or an uncertain language marker. The parsed object retains the language result rather than embedding it in the series title. Release group and release hash provide provenance: they help explain where the candidate came from and can help distinguish one release from another. These fields are not merely labels for display. They preserve information that may be needed when a later decision compares, imports, upgrades, or rejects the candidate.
The important design principle is that parsing produces a bundle of evidence, not one confidence score. A name might have strong quality evidence but weak episode evidence. It might clearly describe a multi-episode file but use a title that matches more than one series. It might have a recognizable anime absolute number but no conventional season marker. By keeping the signals separate, Sonarr allows later stages to apply the right rule to the right fact.
That approach also limits what the parser is allowed to claim. Finding a release group does not prove the group is trustworthy. Finding a quality token does not prove the media file contains that quality. Finding a season and episode marker does not prove the title belongs to the intended series. The parser reports what the text supports; it does not turn an unverified string into a durable library record.
A local path can add evidence without erasing uncertainty
Release names and local filenames do not always carry the same amount of information. A downloader may produce an opaque filename, while the containing folder retains a descriptive release name. A local library may use a season folder and a simple numbered filename. Sonarr's path parser can combine directory and filename context, and can use a meaningful folder to interpret an otherwise incomplete file name.
This is a useful form of evidence accumulation. Suppose a file name contains only an episode number, while its parent folder supplies a season label and the series title. Reading the two together can produce a structured episode candidate that neither part could provide alone. The same principle helps with files placed in a folder named after a release whose actual media files have been renamed by an external process.
But additional context is not the same as certainty. A folder can be misnamed, a file can be in the wrong folder, and an external process can place several releases together. Sonarr's parser can combine the signals, but the resulting candidate still needs to be compared with the canonical series and episode model. Context raises or lowers the quality of evidence; it does not bypass identity checks.
The sequence shows three separate transitions. Text becomes parsed evidence. Parsed evidence is compared with stored series and episode records. Quality and provenance are retained alongside that identity work rather than used to replace it. The final outcome can be mapped or rejected; there is no safe reason to force every string into an episode.
The source's path tests illustrate the practical value of this design. They cover ordinary season folders, special folders, multi-episode paths, numbered files, and opaque names nested under descriptive directories. These tests do not mean every directory arrangement is safe. They show that Sonarr treats the path as a structured input and protects the behavior with explicit cases instead of relying on one filename format.
Conservative failure is a useful result
A parser that returns something for every input may look successful while quietly damaging the library. A wrong mapping can attach a file to the wrong episode, cause an inappropriate upgrade, or make later searches believe an episode is already present. Undoing that mistake can be harder than explaining why a file was not imported automatically.
Sonarr's parser has several defensive boundaries. It rejects names that are obviously hash-like or otherwise unsuitable, filters common noise before matching, validates date interpretations, and returns no usable result when the pattern set cannot establish enough structure. That leaves later decision logic with an explicit absence rather than a guessed episode. The parser tests cover normalization, multiple titles, extension-based quality, languages, path context, and broad quality forms; they are regression evidence for intended behavior, not proof that every real-world name is covered.
That conservatism does not make the parser infallible. The pattern set is heuristic, naming conventions evolve, and external titles can contain misleading text. The repository's tests are regression evidence, not a guarantee of universal coverage. The correct operational response to an uncertain result is to preserve the original context and provide a path for manual interpretation, not to hide the uncertainty behind a guessed episode.
This boundary is especially important because parsing sits between outside systems and durable state. Before parsing, a release name is an external observation. After a successful mapping, it can influence search, download, or import. The parser should therefore maximize useful structure while leaving the final identity judgment visible to the stage that owns library state.
Sonarr's parser is best understood as a translator with a strict contract. It translates varied human and machine naming conventions into structured episode, quality, language, and provenance evidence. It does not by itself decide whether the series is monitored, whether the quality is wanted, or whether the candidate should be downloaded. Those questions belong to the next boundary: how Sonarr gathers candidates from many indexers and turns them into a normalized set that policy can evaluate.