Upload-Assistant

Streamline media preparation and uploads across private trackers & usenet indexers.

---

---

Table of Contents

• Fork Features & Differences from Upstream (Audionut/Upload-Assistant)
  • 1. New Media Category Support
  • 2. Audio Stream Spectrogram Generation
  • 3. Upload Order & qBittorrent Bandwidth Control
  • 4. Argument-Embedded Text Queue
  • 5. Usenet & Indexer Posting
  • 6. Interactive Screenshot Review Workflow
  • 7. Persistent TTL-Based Metadata Cache
  • 8. Modern Web UI & Real-Time Engine
• Supported Sites
• Setup Guide
  • Install
  • Configure the Assistant
• Updating
• CLI Usage
• Shell Completions
• Docker Usage
• Seedbox / Linux Install
• Attributions
• Contributors

Fork Features & Differences from Upstream (Audionut/Upload-Assistant)

This branch introduces new media categories and automation features not present in the upstream Audionut repository:

1. New Media Category Support

• Ebook & Audiobook (BOOK Category):
  • Automatic Type Detection: Classifies uploads into Ebooks (PDF, EPUB, MOBI), Comics/Manga (CBR, CBZ), Newspapers, or Audiobooks.
  • Local Metadata Extraction: Reads metadata from OPF files in EPUB/MOBI, ComicInfo.xml in CBR/CBZ, parses tags via Mutagen for audiobooks, and uses PyMuPDF (fitz) with checksum-validated regex to extract ISBNs from PDFs.
  • API Integrations: Queries MyAnonamouse (MAM) API, Google Books API, and OpenLibrary API for automated metadata lookup.
  • Artwork & Screenshot Generation: Renders gallery screenshots from PDF/EPUB pages, extracts cover artwork, and auto-generates POSTER.png.
  • Smart Duplicate Checking: Custom rules distinguishing formats (e.g., EPUB vs PDF) and audiobooks vs ebooks, with tracker-specific overrides.
• Video Game (GAME Category):
  • Game Directory Parsing: Priority scans for executables (.exe), disc images (.iso), or archives (.rar, .zip, etc.) in the upload path.
  • GazelleGames, IGDB & Steam Metadata APIs: Uses exact GazelleGames torrent comments or a guarded title search for game metadata, then fills missing fields and artwork through Twitch/IGDB and Steam.
  • Platform Detection: Identifies systems (PC, PS5, Switch, Xbox Series X|S, etc.) and enforces platform-group duplicate checks (so Switch uploads aren't blocked by PC dupes).
  • Platform-specific Prompts: Attended prompts for console TV standard (NTSC/PAL) and region codes (USA/EUR/JPN) for trackers like BJSHARE.
• Music (MUSIC Category):
  • Local Tag & Metadata Extraction: Parses audio tags, cue sheets, and rip logs (EAC, XLD, etc.) using Mutagen to extract tracklists, artists, and audio metadata.
  • Discogs & MusicBrainz APIs: Optionally queries external APIs (Discogs via release/master ID or URL, and MusicBrainz) for metadata enrichment.
  • Artwork & Cover Extraction: Automatically searches for local cover images or extracts embedded artwork from FLAC/MP3/M4A tags to upload to image hosts.
  • Preflight & Rule Validation: Enforces mechanical validation for audio formats, sample/bit rates, track counts, and hybrid setups before uploading.
• Adult Video (XXX Category):
  • Automatic Detection & Metadata: Recognizes supported adult-platform release names, extracts common title, studio, and date fields, and builds descriptive keywords.
  • Contact Sheets & Artwork: Generates one configurable contact sheet per video and creates a fallback cover from the source when artwork is not supplied.
  • Workflow Guide: See the dedicated XXX category upload guide for naming, overrides, WebUI usage, and supported destinations.

2. Audio Stream Spectrogram Generation

• Spectrogram Extraction & Plotting: Use -as / --audio-spectrogram to automatically extract audio streams from MKVs, Blu-ray BDInfo, music tracks, or audiobook chapters using FFmpeg and plot frequency/time graphs (inferno theme) via librosa and matplotlib. Music and audiobook processing is capped by audio_spectrogram_max_files.
• Dynamic HDR Metadata Plots: Use --dynamic-hdr-plot to create and upload separate Dolby Vision and HDR10+ metadata plots. The required dovi_tool and hdr10plus_tool binaries are downloaded automatically for the current platform on first use.
• Automated Upload: Automatically uploads generated spectrograms along with your screenshots for release verification.
• Stream Selection: Supports targeting specific tracks using -ast / --audio-spectrogram-tracks (e.g., track indexes or all).

3. Upload Order & qBittorrent Bandwidth Control

Sequence Usenet and torrent tracker uploads while limiting contention with qBittorrent. See the dedicated upload order and bandwidth control guide for configuration and every supported workflow.

4. Argument-Embedded Text Queue

• Custom Parameter Queues: When running batch uploads with a .txt queue file, each line is treated as an independent execution command.
• shlex-Split Parsing: Allows specifying unique CLI arguments (e.g., different IMDB IDs, tags, or tracker targets) for each file/folder on its respective line.
• Resume Capability: Logs processed lines to prevent reprocessing completed uploads if a queue run is interrupted.

5. Usenet & Indexer Posting

• Usenet Upload Support: Automatically archives and splits files/folders (via 7z), generates parity recovery blocks (via par2), and uploads them to Usenet (via nyuu).
• Anonymity & Privacy: Generates randomized poster details and obfuscates post subject lines to protect privacy.
• Indexer Integration: Automatically uploads the generated .nzb file to configured Usenet indexers.

6. Interactive Screenshot Review Workflow

• Manual Screenshot Review: Inspect, add, delete, or replace/recapture individual frames before uploading through the interactive Web UI.

7. Persistent TTL-Based Metadata Cache

• Provider-Scoped API Caching: Disk-cached metadata for TMDb, IMDb, TVDB, TVmaze, OpenLibrary, IGDB, GazelleGames, Discogs, and MusicBrainz.
• Performance & Rate Limit Protection: Configurable TTL and negative caching reuse fetched metadata across runs, avoiding redundant API calls and preventing rate-limiting bans.

8. Modern Web UI & Real-Time Engine

• Full Parity Web UI: Modern interface providing full feature parity with CLI options (--webui).
• Private Local Statistics: A dedicated Stats workspace tracks daily upload outcomes, cache efficiency, logical API operations, torrent/NZB creation, destinations, and categories without storing media names, paths, external IDs, URLs, or credentials.
• Real-Time Execution & Presets: Live log streams, real-time preparation preview, preset saving, and interactive screenshot management.

Supported Sites

Click to view Supported Torrent Trackers

	Site	Usage	Supported Categories
	1PTBA	1PTBA	MOVIE, TV
	Aither	AITHER	MOVIE, TV
	AlphaRatio	ALPHARATIO	MOVIE, TV
	Anthelion	ANTHELION	MOVIE
	AsianCinema	ASIANCINEMA	MOVIE, TV, MUSIC
	AvistaZ	AVISTAZ	MOVIE, TV
	BeyondHD	BEYONDHD	MOVIE, TV
	BitHDTV	BITHDTV	MOVIE, TV
	BitPorn	BITPORN	XXX
	Blutopia	BLUTOPIA	MOVIE, TV
	BJ-Share	BJSHARE	MOVIE, TV, BOOK, GAME, XXX
	BrasilTracker	BRASILTRACKER	MOVIE, TV, BOOK, GAME
	BroadcasTheNet	BROADCASTHENET	TV
	CapybaraBR	CAPYBARABR	MOVIE, TV, BOOK, GAME
	Cathode-Ray.Tube	CATHODERAYTUBE	MOVIE, TV, GAME
	Cinematik	CINEMATIK	MOVIE, TV
	CinemaZ	CINEMAZ	MOVIE, TV
	DarkPeers	DARKPEERS	MOVIE, TV, BOOK, GAME, MUSIC
	DesiTorrents	DESITORRENTS	MOVIE, TV
	DigitalCore	DIGITALCORE	MOVIE, TV, BOOK, GAME, MUSIC
	DreadVault	DREADVAULT	MOVIE, TV
	eMuwarez	EMUWAREZ	MOVIE, TV
	FileList	FILELIST	MOVIE, TV
	Flood	FLOOD	MOVIE, TV
	FunFile	FUNFILE	MOVIE, TV
	Great Poster Wall	GREATPOSTERWALL	MOVIE
	hawke-uno	HAWKEUNO	MOVIE, TV
	HDBits	HDBITS	MOVIE, TV
	HD-Space	HDSPACE	MOVIE, TV
	HD-Torrents	HDTORRENTS	MOVIE, TV
	HomieHelpDesk	HOMIEHELPDESK	MOVIE, TV, BOOK, GAME, MUSIC
	ImmortalSeed	IMMORTALSEED	MOVIE, TV, BOOK, MUSIC, GAME
	InfinityHD	INFINITYHD	MOVIE, TV
	IPTorrents	IPTORRENTS	MOVIE, TV, BOOK, GAME, MUSIC
	ItaTorrents	ITATORRENTS	MOVIE, TV
	lajidui	LAJIDUI	MOVIE, TV
	LemonHD	LEMONHD	MOVIE, TV
	LastDigitalUnderground	LASTDIGITALUNDERGROUND	MOVIE, TV, BOOK
	Lat-Team	LATTEAM	MOVIE, TV, BOOK
	Locadora	LOCADORA	MOVIE, TV
	LongPT	LONGPT	MOVIE, TV
	LST	LST	MOVIE, TV, BOOK, MUSIC, XXX
	Luminarr	LUMINARR	MOVIE, TV
	MakingOff	MAKINGOFF	MOVIE
	MidnightScene	MIDNIGHTSCENE	MOVIE, TV, GAME, MUSIC
	M-Team	MTEAM	MOVIE, TV
	Nebulance	NEBULANCE	TV
	NordicQuality	NORDICQUALITY	MOVIE, TV, MUSIC, BOOK, GAME
	OldToonsWorld	OLDTOONSWORLD	MOVIE, TV
	OnlyEncodes+	ONLYENCODES	MOVIE, TV
	Orpheus	ORPHEUS	MUSIC
	PassThePopcorn	PASSTHEPOPCORN	MOVIE
	PeerGarden	PEERGARDEN	MOVIE, TV, GAME, BOOK, MUSIC
	Polish Torrent	POLISHTORRENT	MOVIE, TV
	Portugas	PORTUGAS	MOVIE, TV
	PrivateHD	PRIVATEHD	MOVIE, TV
	PT GTK	PTGTK	MOVIE, TV
	PTZone	PTZONE	MOVIE, TV
	PTCafe	PTCAFE	MOVIE, TV
	PTerClub	PTERCLUB	MOVIE, TV
	PTFans	PTFANS	MOVIE, TV
	PTSKIT	PTSKIT	MOVIE, TV
	Racing4Everyone	RACING4EVERYONE	MOVIE, TV
	RailgunPT	RAILGUNPT	MOVIE, TV
	Rastastugan	RASTASTUGAN	MOVIE, TV, BOOK, GAME, MUSIC
	ReelFLiX	REELFLIX	MOVIE
	RetroFlix	RETROFLIX	MOVIE, TV
	Retro Movies Club	RETROMOVIESCLUB	MOVIE
	RocketHD	ROCKETHD	MOVIE, TV
	Samaritano	SAMARITANO	MOVIE, TV, BOOK, GAME
	seedpool	SEEDPOOL	MOVIE, TV, BOOK, GAME, MUSIC
	ShareIsland	SHAREISLAND	MOVIE, TV
	SkipTheCommerials	SKIPTHECOMMERCIALS	MOVIE (Documentary only), TV
	SpeedApp	SPEEDAPP	MOVIE, TV, BOOK, GAME, MUSIC
	Swarmazon	SWARMAZON	MOVIE, TV
	The Leach Zone	THELEACHZONE	MOVIE, TV
	The Old School	THEOLDSCHOOL	MOVIE, TV
	Torrenteros	TORRENTEROS	MOVIE, TV
	TorrentHR	TORRENTHR	MOVIE, TV
	TorrentLeech	TORRENTLEECH	MOVIE, TV, BOOK, GAME, MUSIC
	ToTheGlory	TOTHEGLORY	MOVIE, TV
	TV Chaos UK	TVCHAOSUK	MOVIE, TV
	XingyungePT	XINGYUNGEPT	MOVIE, TV
	ULCX	ULCX	MOVIE, TV
	UTOPIA	UTOPIA	MOVIE, TV
	YUSCENE	YUSCENE	MOVIE, TV, BOOK, GAME, MUSIC
	Zenith	ZENITH	MOVIE, TV, BOOK, GAME, MUSIC

Click to view Supported Usenet Indexers

	Site	Usage	Supported Categories
	Curupira	CURUPIRA	MOVIE, TV, BOOK, GAME
	DrunkenSlug	DRUNKENSLUG	MOVIE, TV, BOOK, GAME
	NZBGeek	NZBGEEK	MOVIE, TV, BOOK, GAME, MUSIC
	NzbNest	NZBNEST	MOVIE, TV, BOOK, GAME, MUSIC

Setup Guide

These instructions cover Windows, Linux, and macOS.

Install

1. Install uv for your operating system.

2. Install Upload Assistant:

   uv tool install upload-assistant
   

uv creates an isolated environment and installs a compatible Python version (3.14 or newer) if needed. It makes the ua command available from any directory. If the command is not found, run uv tool update-shell and open a new terminal.

Linux and macOS: Install FFmpeg through your system's package manager (for example, sudo apt install ffmpeg on Debian/Ubuntu, sudo pacman -S ffmpeg on Arch, sudo dnf install ffmpeg on Fedora, or brew install ffmpeg on macOS). See the FFmpeg troubleshooting guide if needed.

To install the latest development version from GitHub instead of the published release, use:

uv tool install git+https://github.com/wastaken7/Upload-Assistant.git

Configure the Assistant

You need to add your API keys (like TMDb) and tracker credentials so the tool knows where to upload.

Method A: Use the Web UI (Easiest)

If you plan to use the Web UI, your configuration file will be generated automatically when you launch and configure it for the first time.

Method B: Use the CLI

On the first CLI upload command, Upload Assistant creates config.py from the bundled example and stops so you can configure it. The file is created in:

• Windows: %LOCALAPPDATA%\Upload-Assistant\data
• Linux / macOS: $XDG_DATA_HOME/Upload-Assistant/data (normally ~/.local/share/Upload-Assistant/data). If Upload-Assistant does not exist but the legacy upload-assistant directory does, use $XDG_DATA_HOME/upload-assistant/data (normally ~/.local/share/upload-assistant/data).
• Custom location: %UA_DATA_DIR%\data (Windows Command Prompt), $env:UA_DATA_DIR\data (PowerShell), or $UA_DATA_DIR/data (Linux/macOS) when UA_DATA_DIR is set

Open the generated config.py in a text editor (like Notepad++, VS Code, or TextEdit) and fill in your information, then run the upload command again.

• For detailed info on what each setting does, see Example Config Docs.
• Get a free TMDb API key from TheMovieDB API settings.

Additional Resources:

• Check out our Wiki Help Page.
• Need a no-root Linux or seedbox setup? See Seedbox / Linux Install.
• Found an issue or need help? Please open a GitHub Issue so we can track and resolve it. If you prefer not to create a GitHub account for privacy reasons, join our Signal group instead.

Updating:

Run uv tool upgrade upload-assistant to update the published installation. If you installed the development version from GitHub, run uv tool install --force git+https://github.com/wastaken7/Upload-Assistant.git to fetch it again. On the next start, Upload Assistant adds missing general settings from data/example_config.py without changing existing values. Tracker/client sections and optional cache-service/tag overrides are left untouched so omitted settings continue to inherit their defaults. Add new tracker/client options manually when needed. A timestamped backup is created beside config.py whenever this automatic update changes the file.

CLI Usage:

Run the assistant from any directory:

ua "/path/to/content" --args

Arguments are optional and normally follow the path. Input modes such as --paths-from-stdin may omit the positional path. For a list of all available arguments, pass --help. The file/folder path works best enclosed in double quotes.

• CLI arguments: docs/cli-args.md
• Usenet uploading: docs/usenet.md
• Upload order and bandwidth control: docs/upload-order-and-bandwidth-control.md

Docker Usage:

Visit our wonderful docker usage

Also see this excellent video put together by a community member https://videos.badkitty.zone/ua

Web UI setup (Docker GUI / Unraid): docs/docker-gui.md Web UI docs: docs/web-ui.md

Attributions:

Built with autobrr/go-bdinfo

Features automated binary managers for:

• nyuu
• par2cmdline-turbo
• pesto
• 7-Zip

Contributors: