Upload workflow

upbrr separates source preparation, tracker decisions, media work, payload review, submission, and post-upload effects. Each stage consumes the exact prepared state approved by earlier stages.

1. Select the source

Provide a release folder or file. upbrr resolves the source layout, finds reusable torrent-client data when enabled, and creates a prepared release generation.

One input can be active per database, shared by the Web UI and CLI. Tabs in the same browser session resume that input. Another session or process receives a busy result while it is owned. Close the active input before handing it to another session. Closing retains history and reusable images.

Switching during local preparation cancels that work and waits for cleanup. A submission or uncertain remote outcome must finish or be reconciled before switching. Closing a browser tab does not release the input.

After upgrading an existing database, an earlier interrupted external effect can require reconciliation before normal input work resumes. Inspect the remote result, then choose Confirmed not completed; allow a fresh exact attempt only when that outcome is known. This process never repeats a submission automatically. Resolve every listed workflow before opening a new input.

Every explicit open, history restore, or refresh checks the source path and inventory and hashes at most the first 1 MiB of each file. File sizes and modification times are checked before and after sampling. This is a lightweight identity check, not verification of every source byte. Torrent creation still performs its required piece hashing. A plain page reload reads the current state without starting another verification.

A fresh application start leaves the previous idle input closed while retaining its History and saved corrections. Open it explicitly to continue. Work waiting for API feedback or external-outcome reconciliation remains available through explicit continuation or recovery; startup does not automatically resume it.

Folder handling matters. --keep-folder preserves a supplied folder instead of processing only a selected video file.

Multi-disc DVD and Blu-ray folders

Select the collection parent when every disc belongs to one release. Supported collections contain extracted folders of one disc format:

Example DVD Collection/
├── Disc 1/VIDEO_TS/...
└── Disc 2/VIDEO_TS/...

Example BDMV Collection/
├── Disc 1/BDMV/...
└── Disc 2/BDMV/...

upbrr prepares one release and creates one torrent rooted at the selected collection, preserving every disc folder. For BDMV, select at least one playlist for every disc. Duplicate playlist names such as 00001.MPLS remain separate because upbrr tracks their disc identity.

2. Review canonical metadata

Metadata providers and local media inspection produce shared release facts. Review at least:

• title and year;
• movie, TV, anime, or other category;
• release type, source, and resolution;
• season, episode, edition, service, distributor, region, and group;
• external IDs;
• generated release name.

Overrides change the prepared generation. Later operations must use that exact generation rather than silently rebuilding it.

Refresh obtains current provider facts and withdraws earlier duplicate decisions and upload approval. It preserves compatible screenshot content and hosted links. Reset requests a new preparation of the source; source or capture changes can make earlier images incompatible. A provider failure is reported rather than presenting old provider data as fresh.

Input readiness evaluates missing release facts and selected tracker metadata before tracker assessment. Correct missing source, type, genre, or languages on Input. A tracker-specific requirement affects that tracker; global missing facts prevent advancement.

Explicit corrections win over history and provider metadata. Auto removes a correction, while an empty list, a zero manual year, or explicit false retains manual authority. Provider failures preserve accepted edits. A changed content identity can require confirmation of saved corrections.

If a provider fails or selects the wrong title, supply a correct ID or clear that provider. Clearing suppresses its ID and metadata for this source, including later reloads. Other providers remain available, but trackers that require the cleared provider may be blocked.

3. Resolve tracker names and eligibility

Each tracker can project its own upload and duplicate-search names from the reviewed source facts. upbrr resolves those names before duplicate checks so the search evidence and eventual payload refer to the same reviewed identity.

Tracker group policies are evaluated separately for each selected tracker and travel with that tracker's reviewed projection. Changing a tracker's group lists invalidates the affected reviewed projection and duplicate decision so they are rebuilt from the new policy. A matching personal-release group supplies the default only while Personal Release is Auto; an explicit Yes or No remains authoritative through upload and restart.

Tracker rules and constructibility checks can mark a lane ready, blocked, skipped, or requiring manual review. A tracker-specific block need not stop other eligible trackers.

For warnings that permit an override, use Upload anyway on the tracker's Dupe Check card or answer the CLI prompt. Approval covers the current warnings; changed warnings require renewed approval. Strict failures cannot be overridden. See tracker warning approval for unattended and debug behavior.

4. Review duplicate evidence

Duplicate search results are evidence, not an automatic upload decision. Review candidate names, metadata, and tracker warnings. Where approval is required, select an explicit non-empty tracker subset after the duplicate stage.

Before searching, upbrr excludes trackers with a confirmed upload of the same verified submitted content. These appear as Already uploaded. Remaining trackers receive fresh duplicate checks; if every selected tracker is excluded, the operation completes successfully without another approval or upload. Changing metadata or a screenshot playlist does not make a full-disc upload new content. A different actual file subset can be different submitted content.

A complete structured group is preferred for group-policy decisions. When a tracker omits that field, only one unambiguous normalized release-name suffix can prove different-group ownership; conflicting, missing, or multi-group text keeps the normal duplicate review.

5. Prepare media and descriptions

Depending on the source and trackers, upbrr can:

• inspect MediaInfo, BDInfo, DVD, or other prepared technical data;
• optionally generate local waveform and spectrogram PNGs from prepared audio tracks;
• select Blu-ray playlists;
• generate screenshots at chosen frames;
• capture compatible DVD menus or import disc-menu images;
• upload selected images to allowed hosts;
• build tracker-specific BBCode descriptions.

Automatic screenshot plans distribute the requested images across all prepared discs, with at least one planned image per disc. Manual frame numbers apply to every disc. Screenshot previews, captures, and DVD menu images remain grouped by disc; DVD menu capture can warn about partial coverage when its collection-wide safety cap or the available menus leave a disc uncovered.

Inspect image ordering, host URLs, technical blocks, headers, and rendered BBCode.

Compatible images retain their selection and order across refresh. Deleted images stay removed. upbrr verifies local image bytes before reuse and reuses hosted links only for a compatible host account and purpose. A hosted link can remain usable when its local preview is missing. Changed capture settings or stricter tracker requirements can require additional images.

Audio analysis is a separate, optional operation. It streams decoded samples from FFmpeg into Go without writing a full decoded-audio file. Its PNGs are retained for preview and download. When descriptions are generated from a completed analysis, upbrr hosts the graphs for each tracker and adds them with the statistics to the default description.

6. Preview immutable tracker operations

Tracker preparation captures an immutable operation. Payload preview and live submission use that captured state rather than regenerating names, rereading mutable prepared input, or uploading images again.

• Description preview prepares only the description.
• Dry run and upload review can prepare a preview but cannot submit it.
• Upload consumes the approved operation once.

Short-lived remote tokens can still be acquired at submission time when required by a tracker.

7. Submit and retain registered torrents

After confirmed tracker success, upbrr records the tracker result and attempts to retain the tracker-registered torrent. Client injection consumes that registered artifact, not the pre-upload torrent.

A failure to download or persist the registered torrent does not turn a confirmed remote upload into a failed upload. Review the warning and recover the torrent manually when needed.

Deleting a release from History removes its associated local workflow, effect, and submission records along with generated artifacts. This also removes local repeat-submission protection for that release. It does not undo remote uploads or delete source media. Retained unknown outcomes require reconciliation and are never treated as confirmed success.

8. Inject into clients

Client injection is enabled by default when configured. Disable it explicitly with CLI --no-seed or the corresponding Web UI upload option.

Check save path, category, tags, automatic management, staging mode, and source-file access. Hardlink, reflink, and symlink staging have filesystem-specific requirements.

Debug and unattended modes

Mode	Submission	Prompts	Client injection
Normal	allowed after review	allowed	enabled when configured
--debug	suppressed	allowed	enabled unless --no-seed
--unattended	allowed when all required decisions exist	never	enabled when configured
--unattended_confirm	allowed when confirmed	required prompts allowed	enabled when configured

Debug mode is not a non-mutating dry run. It can perform screenshots, image uploads, remote searches, tracker preparation, and later workflow effects. Add --no-seed when testing without client injection.

Final review checklist

Before submission, verify:

• release name matches current tracker rules;
• category and type are correct for every tracker;
• movie, TV, disc, remux, encode, WEB, HDTV, pack, season, and episode handling are correct;
• source, resolution, edition, service, distributor, region, language, tag, and group are correct;
• screenshots are valid, ordered, and hosted on allowed hosts;
• description BBCode renders correctly;
• torrent contents, piece settings, and announce behavior are expected;
• client category, tags, save path, and injection target are correct;
• duplicate results, rule warnings, and manual prerequisites have been read.

When any item is uncertain, stop before upload and resolve it manually.