From a Show Idea to Durable Episode Intent
Sonarr's first hard problem is not matching a release to a filename. It is deciding what a correct library record means before any release is considered. This chapter focuses on how Sonarr adds and refreshes a series, connects metadata to seasons, episodes, and files, and turns monitoring and quality choices into durable intent. The result is a practical test: when Sonarr calls an episode “missing,” what exactly is missing, and which facts or choices could change that judgment?
That question matters because an automated media system cannot safely begin with whatever an outside feed happens to report. It needs a stable reference for the show a person wants, the episodes that belong to it, the local place where those episodes should live, and the quality preference attached to that library. Sonarr's source code makes this reference explicit in its data model and in the services that add, refresh, and store it.
A series record is an agreement between facts and choices
When a reader adds a series, Sonarr does not simply save the title typed into a form. The add service requests a series and its episode information from a metadata provider. That response can include external identifiers, title forms, dates, status, runtime, genres, images, actors, seasons, and episodes. These are facts supplied by an outside catalog. They give Sonarr a way to say which program and which episode a later release might refer to.
The add operation then combines those facts with the reader's choices. The selected seasons can be retained, monitoring can be set according to the requested options, a quality profile can be assigned, and a path can be supplied or built beneath a chosen root folder. Sonarr also derives normalized and sortable title forms and validates the resulting series before inserting it. In other words, the stored series is neither a raw metadata response nor a copy of the user's form. It is a composed object: external facts plus local intent, checked against the application's rules.
That composition is important when titles are not unique. A title alone may identify several programs, while an external identifier can distinguish them. Sonarr's series model therefore carries several identifiers rather than relying on one display name. The title helps a person recognize the show; normalized forms help internal matching; external identifiers give the system a more stable anchor when names vary.
The same distinction applies to the local path. A path is not a property of the show in the abstract. It is a local decision about where this installation will keep the show's files. Sonarr can derive a path when the reader supplies a root folder but not a complete series path, and it validates the result before persisting the series. That validation matters because later scanning and importing depend on the service being able to reach the path under the running environment.
The quality profile has a similar role. It is attached to the series as a local configuration reference, not presented as an intrinsic fact about the show. The metadata provider may describe runtime, dates, or status, but it does not decide which quality preference belongs to this library. Sonarr stores the association so later parts of the application have a durable place to consult that local choice.
A useful way to summarize the add operation is:
- metadata says what the series and episodes are;
- the reader says which parts are in scope and how they should be kept;
- validation checks whether the combined state can be stored and used.
If those categories are blurred, refresh becomes dangerous. A metadata refresh should update changing facts, but it should not silently erase local intent merely because the upstream representation changed.
Why episode records are more than a numbered list
A series can be displayed as a title and a poster, but Sonarr operates on episode-level records. An episode belongs to a series and carries season and episode numbers, possible absolute numbering, air dates, monitoring, and an optional link to an episode file. An episode file is a different kind of object. It describes observed media: its relative path, size, quality, languages, release information, and other file-level facts.
This separation gives the system a precise vocabulary for the library's condition. A series can be known without any episodes being present locally. An episode can be known but have no linked file. Several episodes can be represented by one multi-episode file. A file can exist on disk while its relationship to an episode has not yet been established. These situations are operationally different even if a person looking at a folder sees “some video files.”
The database mapping preserves those distinctions. Series records point to their quality profiles. Episode records point to episode files. Files can load their associated episodes when needed. The application also persists the surrounding objects that make the model actionable, including pending releases, provider definitions, profiles, commands, and history. The result is a durable graph of intent and observation rather than a flat list of names.
Within this model, “missing” has a limited and useful meaning: Sonarr knows the episode belongs to the series, but the episode does not currently have the expected file relationship in its stored library state. That does not mean the episode has never been downloaded, that no file exists anywhere, or that the metadata provider is infallible. It means the current reconciliation view has not connected a suitable local file to that episode.
That qualification prevents a common mistake. If a reader drops a file into a folder, the file's existence alone does not complete the library state. Sonarr still needs to scan the path, interpret the file, identify the series and episode, and record the relationship. Conversely, if the database says an episode has a file but the file later disappears, the durable record and the filesystem observation can temporarily disagree. The system needs refresh and scanning precisely because the two sides can drift.
The model also explains why quality belongs on the file as well as in the profile. The profile is a local reference for what the reader wants; the episode file records what the library currently has. Keeping both distinctions available allows later stages to compare a new observation with the existing library state instead of treating a release's quality as an isolated label.
The diagram shows ownership without pretending that every relationship is a physical folder relationship. A series defines the scope for its seasons and episodes. An episode may point to a file, while one file may serve more than one episode in a multi-episode release. The quality profile describes an allowed or preferred policy, whereas the file describes an observed result. Monitoring appears on the desired-state side because it answers whether Sonarr should pursue or maintain an episode.
Refresh changes facts without discarding intent
Metadata is not a one-time setup step. Series information changes: new episodes appear, air dates are corrected, titles or identifiers can be replaced, and a program can move into a different status. Sonarr's refresh service retrieves current series and episode information, updates the stored records, and refreshes episode details. If the remote provider reports that a series no longer exists, Sonarr can mark the local series as deleted rather than treating the absence as an ordinary empty response.
The important behavior is selective replacement. Refresh updates facts such as title, year, external identifiers, overview, dates, runtime, status, images, ratings, genres, and seasons. At the same time, existing season monitoring choices are preserved. This is a small but consequential design decision: current metadata can describe what exists, but it does not automatically tell Sonarr what the reader wants the library to maintain.
Episode refresh follows the same principle. Existing episode records are updated with current numbers, titles, air dates, overviews, runtime, ratings, and images, while new episode records are incorporated into the series' current set. Existing episode objects remain recognizable to the rest of the application, including any link to a file. The model can also carry absolute episode numbers, which gives later matching logic an additional identity signal when season and episode numbering differ.
This creates a controlled tension between synchronization and preservation. If Sonarr preserved every old metadata value, the library would gradually lose contact with the catalog. If it replaced every local value whenever the catalog changed, readers could lose their monitoring decisions or see their paths altered unexpectedly. The refresh service therefore treats remote metadata as a source of changing facts and local settings as state that must be carried through the update deliberately.
Refreshing can also lead to a local rescan, depending on configuration and the trigger that initiated the operation. That sequence matters. New metadata can change the set of episodes Sonarr knows about, while a disk scan can change the set of files it knows about. Running the two concerns together lets the application reconcile both sides, but it does not make them the same operation. Metadata says what should be recognized; scanning checks what is actually present and interpretable on the local path.
The boundary becomes especially visible when an episode is newly added for a show that already exists. The episode may be present in the catalog and have no file link yet. It is part of the desired model, not proof that a download has already happened. Likewise, an episode that is present in the database but outside the current monitoring choice remains known without automatically changing the library.
Monitoring turns a catalog into intent
A catalog describes a program. Monitoring expresses a maintenance decision. Sonarr's series and episode records carry monitoring state so the application can distinguish “known to exist” from “currently wanted.” That distinction lets a reader keep a series in the library without asking Sonarr to pursue every known change.
Monitoring is also layered because the reader's intent may be broad at the series level and narrow at the episode level. A series can be part of the library while particular episodes are outside the current acquisition scope. The code carries monitoring choices through add and refresh rather than leaving the application to infer intent from whether a file happens to be present.
This is why file presence and monitoring cannot be used as substitutes. An existing file does not necessarily mean that an episode should be changed. A missing file does not necessarily mean that every possible action should happen immediately. Sonarr needs both the observation and the policy: what is on disk, and what the reader has asked the system to maintain.
The quality-profile association adds another layer of intent. Monitoring answers whether an episode is in scope, while the profile gives later processing a durable local quality reference. A monitored episode without a file can be missing; an episode with a file has a different observed state; an episode outside the current monitoring choice remains known without automatically changing the library. Later decision stages can use these distinctions rather than treating all gaps or all files alike.
The practical lesson is that a series add should be judged by the state it establishes, not only by whether it starts a search. After the add, Sonarr has a canonical identity, a set of episode records, a local path, a monitoring policy, and a quality reference. Those objects are the context against which future release strings will be interpreted.
The durable model prepares the identity problem
Suppose an outside release contains a familiar title and a season-and-episode marker. Before Sonarr can decide whether to download it, the marker must be connected to one of the episode records just described. That connection may depend on the external identifiers, normalized title, year, series type, air date, or absolute numbering held in the durable model. The more precise the model, the more meaningful a later match can be.
But precision does not eliminate uncertainty. Metadata can be incomplete or change over time. A title can be shared by different series. Episode numbering can differ between the catalog and release communities. A file can be named with information that is useful but not sufficient. The correct response is not to make the model less detailed; it is to keep the facts separate so the next stage can weigh them and refuse an unsafe mapping when necessary.
Sonarr's desired episode state is therefore a prerequisite, not the conclusion. It tells the application what it is trying to maintain and gives every later observation a canonical destination. The next question is how Sonarr turns the unstable text attached to a release or local file into that destination without mistaking a plausible number for the right episode.