usage.md

Setup and configuration

magnetowid exposes two APIs for Sonarr and Radarr:

• Newznab at /{provider}/api for catalogue searches.
• SABnzbd at /api for downloads, progress, and completed MP4 files.

Supported sites: TVP VOD (tvp) and BBC iPlayer (bbc). See the TVP VOD notes and the BBC iPlayer notes. Sites limit their streams to their own country; Region-locked sites shows how to use them from elsewhere.

Install and run

Docker Compose

Follow the quick start to download the Compose configuration and create .env from the example. The image is ghcr.io/combor/magnetowid:latest and includes ffmpeg.

The Compose example reads these settings from .env:

Setting	Default	Description
MAGNETOWID_API_KEY	required	A long, random key shared by both APIs.
MAGNETOWID_DOWNLOAD_PATH	./downloads	Host folder mounted at /downloads inside magnetowid.
MAGNETOWID_UID	1000	User ID for the container process.
MAGNETOWID_GID	1000	Group ID for the container process.

Create the download folder before starting. On Linux, use its owner's user and group IDs; id -u and id -g show your current account's IDs. Give magnetowid and Sonarr/Radarr write access to the shared folder. See Docker networking and shared downloads.

Run docker compose up -d to start or apply .env changes. To update:

docker compose pull
docker compose up -d

Linux service

The magnetowid-bin AUR package, and the .deb and .rpm packages on the releases page, install magnetowid as a systemd service. Set MAGNETOWID_API_KEY in /etc/magnetowid/magnetowid.env, then start magnetowid and enable it at boot:

sudo systemctl enable --now magnetowid

The service runs as magnetowid:media, matching the group used by Arch's Sonarr and Radarr packages. Downloads default to /var/lib/magnetowid/downloads. An alternative MAGNETOWID_DOWNLOAD_DIR must be writable by media and outside /home.

If Sonarr/Radarr share a different group, run sudo systemctl edit magnetowid and add:

[Service]
Group=yourgroup

Run sudo systemctl restart magnetowid after changing settings.

The packages also install magnetowid-vpn@.service, which stays unused until you set up a VPN exit for a region-locked site.

Build from source

Requires Go 1.27.2+ and ffmpeg.

git clone https://github.com/combor/magnetowid.git
cd magnetowid
go build -o magnetowid ./cmd/magnetowid
./magnetowid -api-key YOUR_API_KEY -download-dir ./downloads

Replace YOUR_API_KEY with a long, random key and use it for both connections in Sonarr/Radarr.

Configuration

Set these environment variables or pass the equivalent command-line flags. Flags take precedence. For Docker, add any extra variables to the environment section in compose.yaml. For the Linux service, set them in /etc/magnetowid/magnetowid.env.

Flag	Env	Default	Description
-listen	MAGNETOWID_LISTEN	:8484	listen address
-api-key	MAGNETOWID_API_KEY		required; used by both APIs
-download-dir	MAGNETOWID_DOWNLOAD_DIR		required; downloads go to <dir>/<category>/<release>/; state is stored in <dir>/.magnetowid-jobs.db
-categories	MAGNETOWID_CATEGORIES	tv,movies	download categories to offer
-ffmpeg	MAGNETOWID_FFMPEG	ffmpeg	ffmpeg binary
-log-level	MAGNETOWID_LOG_LEVEL	info	debug, info, warn, or error; debug includes requests and RSS activity
-tvp-proxy	MAGNETOWID_TVP_PROXY		TVP VOD's HTTP proxy, e.g. http://127.0.0.1:8888, or direct; see Region-locked sites
-bbc-proxy	MAGNETOWID_BBC_PROXY		BBC iPlayer's HTTP proxy, or direct; see Region-locked sites

GET /health returns OK without an API key. The container health check runs magnetowid -healthcheck, which queries MAGNETOWID_LISTEN and exits with 0 on success. Set a container's listen address through MAGNETOWID_LISTEN: the health check cannot read the server's command-line flags.

Sonarr/Radarr must be able to read the download directory. If they see it at a different path (e.g. in containers), add a Remote Path Mapping.

Sonarr / Radarr setup

The web interface's Setup page lists these values for your install.

1. Download client: Settings → Download Clients → SABnzbd.
   • Name: magnetowid.
   • Host and port: magnetowid's host and port.
   • API key: the one magnetowid was started with.
   • Category: tv (Sonarr) or movies (Radarr).
   • Priority: higher-priority jobs run first, one at a time. Paused queues the job without starting it. See Pausing downloads.
2. Indexer: Settings → Indexers → Newznab, one per site.
   • Name: e.g. "TVP VOD" or "BBC iPlayer".
   • URL: http://<host>:8484/tvp or http://<host>:8484/bbc, API path /api, the same API key.
   • Categories: 5000, 5040 (Sonarr) or 2000, 2040 (Radarr).
   • Download Client: select magnetowid to route its releases correctly.
3. Language (Radarr, TVP VOD): under Settings → Profiles, set Language to Any, or Polish for Polish audio only. The default, original language, rejects foreign films with TVP's Polish audio. Sonarr profiles have no language setting.

Test both connections. An empty feed produces a placeholder to pass the indexer test; it cannot be downloaded.

Sonarr can search for specials and, for daily series, episodes by air date. Releases always use TVDB's season and episode numbers, e.g. S00E01 or S2026E187, which Sonarr accepts for daily series too.

New episodes and films (RSS)

For sites with RSS support, magnetowid watches titles after Sonarr or Radarr searches for them. RSS sync, every 15 minutes by default, finds new episodes and newly available films.

• Add new titles with a search enabled.
• For existing wanted titles, use Search Monitored on each Sonarr series page, and Wanted → Missing → Search All in Radarr.
• Feeds cover episodes aired within 14 days and films among the site's newest. Search manually for older releases. See each site's notes for support and limits.

Subtitles

Subtitles are saved beside the video as SRT, with language and sdh labels (subtitles for the deaf and hard of hearing), e.g. <release>.pol.sdh.srt. To import them, enable Import Extra Files under Settings → Media Management → Show Advanced in both apps, with srt among the extensions (included by default). Subtitle failures log a warning and keep the video.

Pausing downloads

Pause or resume the queue or single jobs in the web interface or with SABnzbd API commands. Sonarr and Radarr show paused jobs but cannot pause them:

curl 'http://localhost:8484/api?mode=pause&apikey=YOUR_API_KEY'
curl 'http://localhost:8484/api?mode=resume&apikey=YOUR_API_KEY'
curl 'http://localhost:8484/api?mode=queue&name=resume&value=JOB_ID&apikey=YOUR_API_KEY'

mode=queue&apikey=YOUR_API_KEY lists job IDs (nzo_id). Use name=pause and comma-separated IDs in value to pause jobs. Pauses survive restarts, and resumed downloads continue where they stopped.

Web interface

Open http://<host>:8484/ in a browser and sign in with the API key.

Queue shows the running download's progress and time left, queued jobs in run order, and paused or retrying jobs with their last error. It refreshes every second. Pause or resume the queue or a job, or remove a job; removing an unfinished download deletes its partial files. Resumed downloads continue where they stopped.

History lists completed and failed downloads, newest first, and refreshes every five seconds. Records stay for 90 days after the download finishes, unless you remove them. When Sonarr or Radarr removes a download, its record stays here as Archived, with its original result.

Removing an archived record keeps the files. If an unarchived download has a folder, you can delete it too. Removing a record before Sonarr or Radarr imports the download prevents that import.

Overrides lists each site's overrides, with forms to add, change and remove them for series and films. A form that can't be saved says why beside the field at fault.

Setup shows what to enter in Sonarr and Radarr: the download client's host, port and category, and each site's indexer URL, API path and categories. The addresses are the ones the page was opened with, so use another host if the apps reach magnetowid differently. It also shows the version, the download folder, and each site's state: working, or unreachable with the error and the time of the next attempt.

Signing in lasts 30 days. Changing MAGNETOWID_API_KEY signs every browser out. Search for titles in Sonarr/Radarr.

Correcting matches

If magnetowid misses a series or film, or pairs the wrong episodes, add an override on the web interface's Overrides page or through the overrides API. Changes apply to the next search, and RSS feeds rebuild with them at the next sync. Overrides are saved in .magnetowid-jobs.db.

The API takes the same API key, in an X-Api-Key header or an apikey parameter.

Request	Purpose
GET /overrides	List each site's overrides.
PUT /overrides/{site}/series/{tvdbid}	Set a series' override.
GET or DELETE /overrides/{site}/series/{tvdbid}	Show or remove it.
PUT /overrides/{site}/films/{year}/{title}	Set a film's override, using Radarr's title and year.
GET or DELETE /overrides/{site}/films/{year}/{title}	Show or remove it.

{site} is tvp or bbc. A series' TVDB ID is in its TVDB link in Sonarr. Escape / in film titles as %2F.

A series override has one or more of:

Field	Meaning
titles	The site's titles to search, instead of those magnetowid finds.
id	The site's series, among the search results for the titles, if several share a title.
seasons	Rules placing TVDB seasons in the site's numbering: TVDB's episode n is the site's episode n + offset in season site_season. site_season 0 accepts any season, if only one has that number.
episodes	Single TVDB episodes, such as S01E05 or the special S00E01, each with the site's episode ID. These win over seasons, and no other episode matches a pinned one.

The Overrides page calls these Titles to search, ID or page address, Season rules and Pinned episodes.

A film override has titles to search instead of Radarr's, an id, or both. The site's film with that id, found by searching the titles, is used even if its title or year differs from Radarr's, and no other film matches it.

IDs accept the site's page URLs. For example, Ranczo's second season continues TVP's numbering from 14:

curl -X PUT -H 'X-Api-Key: YOUR_API_KEY' http://localhost:8484/overrides/tvp/series/81970 -d '{
  "titles": ["Ranczo"],
  "id": "https://vod.tvp.pl/seriale,18/ranczo-odcinki,316445",
  "seasons": [{"season": 2, "site_season": 2, "offset": 13}]
}'

The response shows the override as saved, with IDs taken from the URLs. Invalid overrides are refused with an explanation.

An override replaces magnetowid's matching for everything it covers, including its checks. An episode it places where the site has none, or only a paid one, gets no release; other episodes are matched as before. Overrides apply to searches and RSS, including the title searches Sonarr makes when its TVDB ID search finds nothing. Season rules cover numbered seasons only; pin specials one by one, as S00E01. See each site's notes for its numbering.

Docker networking and shared downloads

Choose an address that Sonarr/Radarr can reach:

• If an app runs directly on the same host as magnetowid, use localhost and port 8484.
• If both containers share a Docker network, use the service name magnetowid and port 8484.
• For apps on another machine or a different Docker network, use the Docker host's reachable address and the published port 8484.

Inside a container, localhost refers to that container. Separate Compose projects do not share a network by default.

Mount the same host download folder into Sonarr/Radarr. The supplied Compose file mounts it at /downloads in magnetowid, so mounting it at /downloads in your apps gives them matching paths. magnetowid creates tv and movies subfolders for the default categories.

If an app sees the folder at a different path, add a Remote Path Mapping under Settings → Download Clients:

Field	Value
Host	The host entered for the magnetowid download client.
Remote Path	/downloads
Local Path	The same shared folder as seen by Sonarr/Radarr, for example /data/downloads.

Troubleshooting

Search for titles in Sonarr/Radarr. The web interface shows the queue and history, with the last error of each failed or retrying job.

Problem	What to check
A connection test cannot reach magnetowid	Check the container is running, port 8484 is reachable, and the host is correct for your network setup.
A connection reports an invalid API key	Use the same key for the indexer, download client and MAGNETOWID_API_KEY. Run docker compose up -d after changing .env.
The container cannot find or write to the download folder	Create MAGNETOWID_DOWNLOAD_PATH before starting and check that MAGNETOWID_UID and MAGNETOWID_GID have write access.
Downloads finish but are not imported	Mount the shared folder into Sonarr/Radarr, check file permissions and add a Remote Path Mapping if the paths differ.
A magnetowid release is sent to another download client	Set the indexer's Download Client to magnetowid.
Downloads stay queued with provider unreachable in the log	Check the network, DNS, and VPN. Jobs resume automatically when the site becomes reachable, without consuming retries.
One site finds nothing, or the log shows its results as unavailable	The site refuses streams outside its country. See Region-locked sites.
A series or film is missing, or its episodes are wrong	Check that the site has it for free, then add an override.

To inspect recent container messages:

docker compose logs --tail 100 magnetowid

For the Linux service, use journalctl -u magnetowid -n 100. Set MAGNETOWID_LOG_LEVEL=debug for request and RSS details.

For bugs or feature requests, open an issue. Include the steps to reproduce and any relevant error message, with API keys removed.

Limitations

• Titles: Radarr searches local and original film titles. Sonarr sends its series title, often English; a different site title requires TVDB ID support. See each site's notes, or add an override.
• Episode numbers: differences from TVDB require provider-specific mapping. This applies to both search and RSS; TVP's soap mapping and BBC's matching by title and air date have their own limits. Overrides correct the rest.
• Availability: DRM, paid, region-blocked, and unreadable streams are omitted from results. Availability can still change between search and download.
• Streams: release names use the selected stream's resolution, codecs, and known audio language. Probes run during search and are cached for a day. Downloads keep one audio track; subtitle conversion supports TTML only.
• Restarts: .magnetowid-jobs.db stores the queue, history, and watch lists. Download history expires after 90 days. The download filesystem must support file locks; only one magnetowid instance can use it at a time.
• Partial downloads: magnetowid fetches HLS segments, four at a time, into .incomplete/<job id> in the download folder, then remuxes them with ffmpeg. Paused, interrupted and retried downloads continue from their last complete segment, unless the site now serves a different stream. Other streams, such as live or encrypted HLS, go straight to ffmpeg and start over. Partial files stay until the job finishes or is removed, and finishing needs free space for about twice the video's size.

Adding a site

Implement provider.Provider (internal/provider/provider.go) in a new package under internal/provider/ and add it to the registry in cmd/magnetowid/main.go. The provider:

• searches its catalogue and maps Sonarr/Radarr numbering onto its own;
• resolves an ID to a stream URL ffmpeg can open, at download time, and may amend an HLS master playlist, e.g. to add variants the site omits;
• optionally implements provider.TVDBSearcher to find series by TVDB ID, if Sonarr's titles don't match the site's;
• optionally implements provider.RecentLister to offer new releases to RSS sync;
• optionally implements provider.Overridable to apply the user's overrides in its searches and feeds;
• documents the site's own behaviour and limits in a README.md in its package.

Development

Command	Checks	Requirements
make test	Formatting, vet, race tests	ffmpeg with libx264 for download tests
make docker-smoke	Image build, startup, both APIs	Docker
make package-smoke	Install, run, upgrade, and remove packages on Debian, Fedora, and Arch	Docker, GoReleaser
make integration	Sonarr/Radarr search, RSS grabs, video and subtitle imports against fake VOD sites	Linux, Docker, ffmpeg with libx264, access to the apps' metadata servers
make live	Live TVP, BBC iPlayer, Skyhook, and Wikidata APIs; also runs daily in CI	Network access; BBC streams need a UK connection

License

BSD-3-Clause.