Fetcharr

Gets new media playable first, then cleans up, hunts missing, and enriches what you already have.

Fetcharr

Undo Log

Misfiled after Fetcharr? Undo through a run, or return files to [Stagging]. Expanding a run lists each domain grabber (0 files if none).

Loading Fetcharr runs…

Playlists

Episode slices only - not a full series, collection, or discography. Pushes to Emby / Jellyfin when keyed.

This week

Slice

Queue

Sitting Servarr Activity and downloader traffic for each Domain Grabber. Date bars share one window when linked. Lamps and speeds catch up in the background.

Wheel to move between grabbers.

Open Queue to load clients.

Metadata

Look up, strip embedded tags, sidecar census, and duplicate intelligence. Strip is remux-only. Dupes never delete.

Lookup

Align

Light profile rules: SxxExx + bare extensions. No full-name rewrite.

Align / lock

Versions

Repair

Look up by title, then path + health probe. No raw paths. Diagnose only - not a remux, not Review.

Check

Review

Current and Past media with issues - flagged releases plus Boxarr/Fetcharr parked items. Same flip-box ticks as Fetcharr step 0. Range chips match Queue.

Current Media with issues

Past Media with issues

Logs

Files is the browse home. Open a folder, or search. Purge old logs under Files. Live job output stays in the pane below.

Files

Loading…

Open a folder.

Purge logs

Help

How Fetcharr runs, the Boxarr commands, and the language this stack uses. Default = execute. Test Mode is plan only.

Fetcharr

Fetcharr is Boxarr’s Daily ingest. Play on the Fetcharr tab (or python boxarr.py --fetcharr) runs this sequence against completed downloads, then maintains what this run just touched. It does not replace Sonarr, Radarr, or the downloader. It claims files, names them, places them, and follows up on the parents those files belong to.

The numbers on the Daily face are step ids, not run order. Fetcharr always uses this order. The strip and each heading use the same step icons as the Fetcharr pipeline so you can match them. Default = execute: real moves and API calls. Test Mode (--testfirst / --test / --dryrun) is one global switch for the whole run - plan only, no per-step test flag. There is no --execute flag.

Normalize, Validate, and Rotate stay off until you turn them on in Autorun. They exist in the sequence so the purpose names are stable; skipped is honest, not a hidden success.

#00 Review flagged media

Opens every Fetcharr run so the GUI is not silent while reports tick. Local only: it does not hunt Servarr and it does not start new grabs.

Replays retryable actions from the last run (stale “running” rows become failed).
Loads the Flag list. A flagged release is Do Not Download Again for that exact version - Fetcharr will not claim it on scout, and Analyze will not retry the same bad file.
Ticks open reports without firing a Servarr search. Extra steps from those reports can be appended; they do not reorder the plan.

#01 Scout newly recieved media

Walks downloader Complete drop folders only (QB-File-Complete leaves), not library Shares and not Cache\QB as a whole. Loose files at the Complete root count, as do packages under category buckets such as [sonarr] / [liveaction]. Listing uses Windows long paths so names with [] on UNC shares are visible.

Ensures each library’s [Stagging] folder exists before the next step claims into it. The spelling is intentional.
Skips dotfiles, configured skip names, and flagged releases.
Accepts video files and non-bracket folders. Pure […] folders are buckets to descend into, never a title to claim.
Does not move anything. Staging claim is the next step.

#02 Move new media to stagging

Lands everything in untyped [Stagging] first, then lanes from the catalogue. Grabber and downloader paths are not identity. Catalogue is source of truth for type, forma, and library home. IMDb fills a miss, then Boxarr writes the catalogue and trusts it going forward.

Holding pass: filename SxxEyy vs year only - series vs movies parent, never the grabber.
Catalogue pass: typed + forma claim lane ([series]\[liveaction], [movies], …). Cross-lane moves are refused.
A leftover already in [Stagging] is claimed; a duplicate still sitting in Complete is dropped.
Unknown / unclassifiable packages stay in untyped [Stagging] rather than being forced into Live Action.

#06 Clean residuals

After new media has moved, this sweeps encoder junk left in the Complete / download roots. It is not a library cleaner and it does not delete third-party files in Shares.

Default junk is the same encoder debris staging already strips (nfo/txt samples, Sample dirs, and the extras in configuration/residuals.json when present).
Empty leftover folders under Complete can go. Marker files (.emby, .ignore, .split) are not junk.
Keep-vs-remove for ambiguous leftovers stays conservative: media packages are not residuals.

#12 Stop related downloads

Confirms the grabber and the downloader have stopped for packages this run already claimed into [Stagging]. It lists those packages - not “pause every client.”

Pauses matching downloader jobs (seed/upload states count as settled; active download states get paused).
Pulls matching Servarr queue rows with removeFromClient=false so the grabber is not still importing a file Boxarr already holds.
Unrelated downloads stay up. A dead downloader is reported, not a reason to skip the rest of the run.

#13 Analyze media

Purpose name: does Boxarr understand what it received? The step is not called FFprobe or FFmpeg. A vendored health probe answers “does this file open.” Languages come from MediaInfo CLI, not the health probe.

If the health probe is missing, this step is an error and Fetcharr will not pretend analysis passed.
Unknown / unsupported types park in Review and drop out of the run. That is a human decision, not a repair.
A known type that will not open is flagged Do Not Download Again and drops out of this run. Hunt a different version from Flag (max priority) - not Review, and not a generic Repair stage.
Books, comics, manga, magazines, ROMs, and cards skip the video/audio probe; they still need a known type.

#14 Normalize media

Purpose name for getting media into library form: drop unwanted languages/streams per policy, expected container. FFmpeg may be underneath; the step is not named after the tool.

Off by default (daily.json normalize=false). Autorun in Settings turns it on.
When off, the step is skipped - not a fake OK.
The paid remux/transcode path is what actually rewrites streams. This slot is in the sequence so that path has a home.

#15 Validate output

Optional gate after any rewrite (normalize, remux, or transcode): confirm the new file before promoting it or replacing the original.

Off by default (daily.json validate_output=false).
When on, a failed probe parks the result in Review instead of promoting a bad rewrite.
Leave it off if you do not want the extra pass. The step exists because some operators will.

#03 Rename new media

Inbound rename in [Stagging] to Boxarr naming. This is not library --align. Inbound stays conventional, not a beautifier.

Fixes broken extensions (video mkv → .mkv).
Series: Show Name [Year] [tt…]\Season XX\Show Name - SxxExx[ - Episode Title].mkv.
Movies: Title [Year] [tt…]\Title [Year] [tt…].mkv.
Canonical tags such as [1080p] [h265] [4k] mark a file Boxarr owns. Kaizen later maintains those.

#04 Remove completed jobs

Despite the face name, this is place-into-library: move the renamed package from [Stagging] to its live home. The catalogue index is the home. If that home moved since the last place, the old folder relocates first.

Ingest priority (Settings → Autorun): if transcode is ahead of viewable, files stay in [Stagging] instead of going live.
Unclear forma is asked - Fetcharr does not dump unknown series into Live Action.
Incoming extras are discarded. The copy already in the library stays unless an explicit upgrade/replace policy says otherwise.
Placement is recorded so later runs and Stepback know what Boxarr created.

#05 Mark media recieved

After files have landed, clear matching grabber / Jellyseerr junk so the stack stops treating this episode as outstanding.

Removes Servarr queue rows that match this run’s titles (strict title / SxxEyy) or that are truly completed / imported.
Does not clear active downloads for unrelated shows.
Unmonitors the grabbed episode/movie on the grabber so it is not hunted again. Unlock / Stepback can restore that when you pull a title back.

#07 Review libraries for missing recent media

Foot-traffic on the library floors this run just dropped into. Each series home is counted have/expected for that season. Missing aired episodes are queued for search. Downloader job cleanup is not this face.

Only parents this run touched - not a whole-library Missing* sweep.
Reports look like "Show" S04 - 07/10 --- 3 Episodes Missing plus which episodes are being grabbed.

#08 Search missing recent media

Notes offset holes in the series this run handled (S01E01 + S01E03 in hand ⇒ E02 is a hole). When Kaizen (#10) is on, this step skips: note-missing is Kaizen sub-step a, so the work is not done twice.

Writes the missing-offsets report under logs/fetcharr/.
Does not fire global MissingEpisodeSearch / MissingMoviesSearch.

#09 Push scheduled items

Looks at the Servarr calendar for the current window (today through the next two weeks) and searches items that are still monitored and have no file.

Hammer: sitting Activity (queued / delay / warning / dead client) is not HAVE. Grab, else kick the parent onto the downloader.
Downloading is left alone.
Never a global Missing* command. Same rule as --seek: only the focus set.

#10 Kaizen recent media

Kaizen is Boxarr’s maintenance of what Boxarr owns. If Boxarr created it, Boxarr owns it. If Boxarr owns it, Kaizen maintains it. This step is not a CLI verb and it is not a whole-library sweeper.

Sub-step a: note missing members of the parent this run touched (show / volume / artist), not only today’s season.
Sub-step b: push acquisition for those gaps. Do not wait for the download.
Independent checks on owned files: language, quality, bitrate, container. Default on a violation is remove + queue a replacement; retain-until-replace is the other radio in Settings.
Never deletes third-party or user-managed files. Known problem + known policy stays in Kaizen. Unknown handling goes to Review.

#11 Refresh metadata

Late on purpose (before Rotate), fail-open, no ffmpeg. Prefer Metarr when a local record exists (sidecar metarr: true plus the record key). If Metarr has nothing, catalogue lookup. A miss is first priority the next time this step runs. Daily continues either way. Pulls are not merged into the catalogue.

Does not block placement. Files are already live (or held in [Stagging] by ingest priority).
Does not invent a metadata swarm here. Metarr owns gathering, tables, and mesh; this step consumes them.

#16 Rotate viewed media

Space-limited libraries: keep media until it has been watched, then remove it to free disk. Own verb --rotate as well as this Fetcharr tail step. Not Kaizen (quality of what we keep). Not Review. Not Flag.

Off by default (daily.json rotate=false). Autorun turns the Fetcharr step on. The verb runs on demand either way.
Viewed truth is the media server (played / percent watched), not the grabber and not “file exists.” That source is not wired this pass - execute will not delete yet.
Default scope is Boxarr-owned files only. Third-party / user-managed library files stay put unless you change scope to the whole library.
Holds: unwatched, in-progress, current season, specials, locked titles, Review-parked, and a protect list. Grace hours after viewed before a remove. Per-run count and GB caps. Optional “only when free space is below N%.”
After a remove: unmonitor on the grabber (default) so it is not immediately re-grabbed; reacquire allow vs hold is a policy radio. Empty season/show folders can prune.
Undo Log stays on Fetcharr. A future Review reports pane can confirm rotator actions; that move is not this pass.

Commands

Default = execute (real moves / API actions). Test Mode is plan only (--testfirst / --test; --dryrun aliases). No --execute flag.

Every Boxarr CLI verb and flag, from the live argparse parser. Each command is a short explanation, then an example (python boxarr.py --fetcharr or --verb --subverb), then aliases when the parser has extra option strings. Hidden aliases that --help omits stay omitted.

Glossary

Words Boxarr uses on the face, in Fetcharr, and around the Servarr stack. Face language is downloader. Product word is kaizen. Spell Boxarr and Fetcharr (two r’s).

Align: Library-tree rewrite per configuration/align.json. Yokoten: spread a known fix sideways. Not inbound rename, not Fetcharr #03.
Analyze: Fetcharr #13. Purpose name for “do we understand this file.” Health probe for open/read; MediaInfo for languages. Not a step named FFprobe.
[Audit]: Ops folder under Series. Dual copy of Boxarr spreadsheets. Emby/Plex ignore pure-bracket folder names as library titles.
Backlog: Seek focus set for older holes. Never a global Missing* search. Owned by --seek / Fetcharr’s calendar window, not a library wipe.
Bare Metal: Service host_kind face (with Docker / Proxmox). Comes from config, connect cache, or label markers such as (Bare Metal) / (Docker) - not a live Docker or host scan.
Boxarr: Library lifecycle layer for a Servarr / downloader / Emby-Jellyfin-Plex home stack. Owns what we have, what happens next, and the morning drain. Not a media server and not a grabber.
Bracket folders: The entire folder name is […]. Ops only - never a title. Examples: [Stagging], [sonarr], [liveaction], [movies].
Bracket tags: Square brackets inside a longer name: Show [2022] [tt12327578]. Metadata the media server can hide in the face title and still use for identity.
Bridge VPN: Path to the library. Tailscale, Headscale, or an OS configured VPN. Icon and (name) next to the IP are the last one used until a different Bridge is detected. Not Privacy VPN.
Cache: Downloader / Complete share ({cache}). Not the library. Scout reads Complete here; it does not treat Cache\QB as a library root.
Catalogue: Boxarr’s home truth for title, type, forma, IMDb, and library path. Grabber paths are not identity. Index lives under catalogue/ plus the Titles sheet.
Collection: A grouped library home (Star Trek Collection, Animation Domination). Catalogue path wins even when the show sits under a collection folder rather than the plain forma lane.
Connection: Sidebar card of addresses on this machine: LAN, Bridge, Privacy, I2P (Metarr Metadata DB Mesh dest face), Servarr, media server, and ISP of the current public path. Speed test is Cloudflare (no account, no ads) - not Ookla. Never a library path.
Complete: Downloader drop folder, usually QB-File-Complete. Fetcharr scouts these leaves, including loose files at the root and category buckets underneath.
Components: Third-party kits Boxarr ships and redistributes (FFmpeg, MediaInfo, NSSM, …). Versions are the copy on disk. Python is the bundled runtime, not a component row.
Connect: TCP + auth probe of Servarr, downloader, and media-server endpoints. Not VPN connect. Settings → Connect.
Core: Seek focus set for the shows you actually keep current. Do not implement --seek --core as a new syntax in this product this week.
Daily: Old verb for Fetcharr. --daily is an alias of --fetcharr. Same pipeline.
Do Not Download Again: Flag on an exact release. Scout skips it. Analyze flags a known-type probe failure this way so Fetcharr hunts a different version, never the same bad file.
Docker: Service host_kind face. Resolved from config / connect cache / label markers (see Bare Metal) - Boxarr does not probe the Docker daemon to decide the icon.
Downloader: Face word for the download client. Seed vs upload is a downloader state, not a Boxarr mode. Vendor names stay in Settings, not on this page.
Emby / Jellyfin / Plex: Media servers. Boxarr is not one. It can lock/unlock library items and refresh after place. Emby/Plex ignore [bracket] ops folders as titles.
Encoding: Codec / resolution as an index and catalogue fact ([h264], [1080p]). Not a folder Boxarr is still inventing. Align is moving collections toward parentheses.
Fetcharr: Boxarr’s Daily ingest function (this Help’s first section). Play on the Fetcharr tab or python boxarr.py --fetcharr (--daily is an alias). Not a separate product. Spell with two r’s.
Flag: Tab and store for Do Not Download Again, plus refetch-open items. Distinct from the Review pod (unknown handling) and from Kaizen (known policy).
Forma: Presentation form: Live Action, Animation, Anime, Adult Animation, Talk Shows, Sports, Documentaries. Not genre. Not media type. Unclear forma is asked, never dumped into Live Action.
Grabber: Servarr app that requested the file (Sonarr, Radarr, Lidarr, …). Boxarr does not trust grabber paths as the library home.
Hammer: Sitting Servarr Activity (queued / delay / warning / dead client) is not HAVE. Grab the id, else kick it onto the downloader. Never global Missing*.
Health probe: Vendored FFprobe under Components, used by Analyze and Validate. Operator copy names the job, not the tool.
Host: Never hardcoded. Lives in Settings networks (or BOXARR_HOST). Path tokens {host} {unc} {cache} {shares} expand after the profile is chosen. Bare Metal vs Docker icons use config/cache/label markers - not a live host scan (see Bare Metal / Docker).
IMDb: Title identity tt#######. Catalogue and library folders carry it in tags. IMDb fills a catalogue miss; it is not the grabber’s word.
Ingest priority: Viewable → transcode → metadata (Settings → Autorun). If transcode is ahead of viewable, Fetcharr leaves new files in [Stagging] instead of placing live.
Jellyseerr: Request front end in this stack. Fetcharr can clear matching request junk after a title has landed.
Job: The always-on pane at the bottom of the operator card. One Fetcharr (or other verb) at a time in the exclusive lane. Stop retires it; a finished Daily must go idle so Run works again.
Kaizen: If Boxarr created it, Boxarr owns it; Kaizen maintains it. Foot-traffic on floors this run entered. Independent checks: language, quality, bitrate, container. Not Review. Not a whole-library sweeper.
Kapowarr / Lidarr / Readarr / Whisparr: Grabbers for comics, music, books, and adult video. Same Complete → [Stagging] → live idea, different media type.
Keep mode: On a Kaizen violation of an owned file: replace_now (default - remove and queue a replacement) or retain_until_replace. Settings → Media Management.
Lane: Typed claim path under [Stagging] or a live forma folder (Live Action, Anime, …). Cross-lane moves are refused.
Library home: Canonical folder for a title. Catalogue path wins even if the folder is not on disk yet. Fetcharr #04 places into that home.
Live: The real library under Shares (Series, Movies, …), as opposed to Complete or [Stagging].
Lock / unlock: Yes/No topology confirm; disk read-only; media-server LockData; grabber unmonitor (restore on unlock if saved). Align skips a title-wide lock.
Media type: Series, Movies, Music, Books, Comics, Manga, Magazines, Roms, Cards, Private. Not forma. There is no MediaKind.
MediaInfo: Vendored CLI for languages and stream facts. Analyze uses it for language; the health probe is a different tool.
Mesh: See Metarr Metadata DB Mesh. Boxarr’s metadata platform over I2P. Records never include media, paths, or hosts.
Metarr: Boxarr function, not a separate product: metadata gathering and I2P mesh. Prefers a Metarr record when one exists; fail-open. Never media, paths, or hosts on the wire.
Metarr Metadata DB Mesh: The metadata platform card. Heading icon is always Metarr. (Metarr) next to the IP once the mesh has been seen; no parenthetical until then. If i2pd is missing, Install fetches the portable router. Then Connect / Reconnect / Disconnect attach or drop our SAM session (not the router). This node is a generated nym, not a hostname.
Missing*: MissingEpisodeSearch / MissingMoviesSearch. Boxarr never fires these globally. Seek only the focus set (core, year, backlog, or this-run parent).
Network profile: local / vpn / web / auto. Auto picks from adapters + TCP probe. Service URLs stay http://{host}:{port}.
Normalize: Fetcharr #14. Purpose name for library-form rewrite (streams + container). Off by default. Not an FFmpeg-named step.
Panic: Unboxarr’s teardown. Boxarr’s --panic today only pauses every downloader job. Do not grow it into uninstall here.
Playlist: Parked. Weekly / titled lists from catalogue and [Stagging]\daily.log. Not this Help pass.
Privacy VPN: Hides traffic. Icon and (name) next to the IP are the last Privacy VPN used (Proton, PIA, Mullvad, …) until a different one is detected. Blank means no parenthetical. Card shows IP, protocol, country, state. Not the library path.
Prowlarr: Indexer hub in the Servarr stack. Fetcharr is Boxarr’s ingest function, not a Prowlarr replacement, not Prowlarr admin, and not Boxarr --seek.
Queue: Operator tab: calendar / grabber activity / downloader rows. Grabbed vs ungrabbed is Servarr calendar by air/release, not Boxarr’s word for “we own it.”
Radarr / Sonarr: Movie and series grabbers. Boxarr marks received and hammers their Activity. It does not replace their libraries.
Repair: Operator tab for known broken files you choose to handle. Analyze does not send probe failures here. Known-type failure is a re-fetch; unknown type is Review.
Review: Formal pod for outstanding media automation has not figured out. Unknown / unsupported types park here. Distinct from Kaizen (known problem + known policy) and from Flag (do not download that version).
Romarr: ROM product in the Servarr stack, separate from Boxarr. Tab-based downloader work stays parked until Romarr acquisition is real.
Rotate: Keep-until-viewed space reclaim. Fetcharr #16 (off) and --rotate. Uses media-server watched state. Default Boxarr-owned only. Not Kaizen.
Scout: Fetcharr #01. List Complete; do not move yet.
Servarr: The Servarr family this stack operates: Sonarr, Radarr, Lidarr, Prowlarr, and the rest on the board. Boxarr is the lifecycle layer on top, not a replacement.
Shares: Library share ({shares}): Series, Movies, Music, … Live homes live here. Complete does not.
[Stagging]: Pipeline holding area under each library root. Spelling is intentional. Untyped parent first, then [movies] / [series] / forma children.
Stepback: Pull a misfiled title back into [Stagging] (through-a-run or one file). Original name, library name, where filed. Closed at the bottom of Fetcharr.
Test Mode: One global plan-only switch. User-facing word is Test. --testfirst / --test / --dryrun. Not per-step. Default remains execute.
Transcode / remux: Rewrite media toward library form. Purpose lives under Normalize + Validate. Paid path is not a full product this pass. Validation is the same idea after either rewrite.
Unboxarr: Separate CLI: apply / recover / Panic. Not a Boxarr tab. Do not start an Unboxarr UI here.
UNC: Windows share path. Explorer’s \\?\UNC\host\share\… is the long-path form so names with [] are visible. Boxarr stores host UNC (\\host\share\…) and uses the long form at the filesystem edge.
Undo Log: Operator log of Fetcharr / verb actions you can reverse. Empty grabbers are omitted. Stage-curtains mark on that pane.
Usarr: People and keys. Separate product. Do not build users or key rotation into Boxarr.
Validate: Fetcharr #15. Optional post-rewrite gate. Off by default. Failed output goes to Review, not live.
Viewable: Ingest priority: a file the media server can play now. When viewable is first, Fetcharr distributes to live immediately after rename.
Viewarr: Future watch hub, separate repo. Not this GUI.
VPN: Bridge VPN is the path. Privacy VPN is privacy. Metarr is not a VPN.
Year: Seek focus set for a calendar year of holes. Same never-global-Missing* rule.
Yokoten: Align’s job: take a known fix and spread it sideways across the tree. Kaizen is improve the thing we are already holding.

Bug

Parked. Use this tab when something in Boxarr is wrong and you want it written down.

Job

idle

Ready. Pick a tab and run a verb.

Fetcharr

Where does this belong?

Fetcharr

Autorun Options

Undo Log

Playlists

This week

Slice

Queue

Metadata

Lookup

Flag a problem

Flag a copy

Recent media

Align

Align / lock

Versions

Repair

Check

Review

Current Media with issues

Past Media with issues

Logs

Files

Purge logs

Help

Fetcharr

#00 Review flagged media

#01 Scout newly recieved media

#02 Move new media to stagging

#06 Clean residuals

#12 Stop related downloads

#13 Analyze media

#14 Normalize media

#15 Validate output

#03 Rename new media

#04 Remove completed jobs

#05 Mark media recieved

#07 Review libraries for missing recent media

#08 Search missing recent media

#09 Push scheduled items

#10 Kaizen recent media

#11 Refresh metadata

#16 Rotate viewed media

Commands

Glossary

Bug

Job