putioarr 0.6.12

put.io to sonarr/radarr/whisparr proxy
# putioarr

Proxy that allows put.io to be used as a download client for sonarr/radarr/whisparr. The proxy uses the Transmission protocol.

## Installation

There are a few ways to install putioarr:

### Cargo
Make sure you have a [proper rust installation](https://www.rust-lang.org/tools/install)
`cargo install putioarr`

#### Usage

First, generate a config using `putioarr generate-config`. This will generate a config file in `~/.config/putioarr/config.toml`. Use `-c` to override the configuration file location.

Edit the configuration file and make sure you configure the username and password, as well as the sonarr/radarr/whisparr details.

- Run the proxy:`putioarr run`
- Configure the Transmission download client in sonarr/radarr/whisparr:
    - Url Base: /transmission
    - Username: <configured username>
    - Password: <configured password>


### Docker

Docker images are based on [linuxserver.io](https://linuxserver.io) images.

#### Usage

The first time you run your docker container, run it without the `-d` option, since you'll need a put.io API key. When no configuration is found, it will present you a link and a code that will generate an API key. After the key is generated, putioarr will write a default config in your config volume (see `docker compose` and `docker cli` below). Modify the config (like username, password and sonarr/radarr/whisparr configuration) in order to properly use putioarr.

#### Supported Architectures

We utilise the docker manifest for multi-platform awareness.

Simply pulling `ghcr.io/wouterdebie/putioarr:latest` should retrieve the correct image for your arch (amd64 or arm64).

#### docker-compose (recommended, [click here for more info]https://docs.linuxserver.io/general/docker-compose)
```yaml
---
version: "2.1"
services:
  putioarr:
    image: ghcr.io/wouterdebie/putioarr:latest
    container_name: putioarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /path/to/putioarr/config:/config
      - /path/to/your/downloads:/downloads
    ports:
      - 9091:9091
    restart: unless-stopped
```

#### docker cli ([click here for more info]https://docs.docker.com/engine/reference/commandline/cli/)

```bash
docker run -d \
  --name=putioarr \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 9091:9091 \
  -v /path/to/putioarr/config:/config \
  -v /path/to/your/downloads:/downloads \
  --restart unless-stopped \
  ghcr.io/wouterdebie/putioarr:latest

```
#### Parameters

Container images are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate `<external>:<internal>` respectively. For example, `-p 8080:80` would expose port `80` from inside the container to be accessible from the host's IP on port `8080` outside the container.

| Parameter | Function |
| :----: | --- |
| `-p 9091` | Port connecting to putioarr |
| `-e PUID=1000` | for UserID - see below for explanation |
| `-e PGID=1000` | for GroupID - see below for explanation |
| `-e TZ=Etc/UTC` | specify a timezone to use, see this [list]https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List. |
| `-v /config` | putioarr configs |
| `-v /downloads` | torrent download directory |



## Behavior
The proxy will upload torrents or magnet links to put.io. It will then continue to monitor transfers. When a transfer is completed, all files belonging to the transfer will be downloaded to the specified download directory. The proxy will remove the files after sonarr/radarr/whisparr has imported them and put.io is done seeding. The proxy will skip directories named "Sample".

## Configuration
A configuration file can be specified using `-c`, but the default configuration file location is:
- Linux: ~/.config/putioarr/config.toml
- MacOS: ~/Library/Application Support/nl.evenflow.putioarr

TOML is used as the configuration format:
```
# Required. Username and password that sonarr/radarr/whisparr use to connect to the proxy
username = "myusername"
password = "mypassword"

# Required. Directory where the proxy will download files to. This directory has to be readable by
# sonarr/radarr/whisparr in order to import downloads
download_directory = "/path/to/downloads"

# Optional bind address, default "0.0.0.0"
bind_address = "0.0.0.0"

# Optional TCP port, default 9091
port = 9091

# Optional log level, default "info"
loglevel = "info"

# Optional UID, default 1000. Change the owner of the downloaded files to this UID. Requires root.
uid = 1000

# Optional polling interval in secs, default 10.
polling_interval = 10

# Optional skip directories when downloding, default ["sample", "extras"]
skip_directories = ["sample", "extras"]

# Optional number of orchestration workers, default 10. Unless there are many changes coming from
# put.io, you shouldn't have to touch this number. 10 is already overkill.
orchestration_workers = 10

# Optional number of download workers, default 4. This controls how many downloads we run in parallel.
download_workers = 4

# Optional. When false (default), locally downloaded files are deleted after
# the *arr imports them. Set to true to keep them in download_directory instead
# (put.io transfers/files are still cleaned up).
keep_downloads = false

# Optional, default false. When true, archives (put.io type ARCHIVE: RAR parts,
# zip, 7z) are downloaded too, for an extractor such as Unpackerr pointed at
# download_directory -- see "Archives (Unpackerr integration)" below.
download_archives = false

[putio]
# Required. Putio API key. You can generate one using `putioarr get-token`
api_key =  "MYPUTIOKEY"

# Both [sonarr] and [radarr] are optional, but you'll need at least one of them
[sonarr]
url = "http://mysonarrhost:8989/sonarr"
# Can be found in Settings -> General
api_key = "MYSONARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/tv/)
# category = "tv"

[radarr]
url = "http://myradarrhost:7878/radarr"
# Can be found in Settings -> General
api_key = "MYRADARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/movies/)
# category = "movies"

[whisparr]
url = "http://mywhisparrhost:6969/whisparr"
# Can be found in Settings -> General
api_key = "MYWHISPARRAPIKEY"
# Optional: Download to a category-specific subdirectory (e.g., /downloads/adult/)
# category = "adult"
```

### Archives (Unpackerr integration)

By default, putioarr only downloads video and audio files. Archives (put.io type
`ARCHIVE`: multi-volume RAR releases with `.rar`/`.r00`/`.r01`/... parts, `.zip`,
`.7z`) are skipped. A transfer that contains only archives stays on put.io, and
putioarr logs a warning, since the \*arr has nothing to import.

Set `download_archives = true` to download archives like any other file and
leave them to an extractor, typically
[Unpackerr](https://github.com/Unpackerr/unpackerr), set up for the same
`download_directory`. putioarr considers an archive done once either:
- it is gone from disk (e.g. with Unpackerr's `delete_orig`), or
- the \*arr reports importing a file from inside the transfer's own folder (the
  extracted video).

A transfer that is a single archive file, not in a folder, only counts as done
once the archive is gone from disk.

Only enable this if you run an extractor pointed at the same download
directory; otherwise the archives sit there until `import_timeout_secs` is
reached.

### Category-based Download Directories

To prevent Sonarr/Radarr/Whisparr from seeing each other's downloads, you can configure separate download directories using categories:

1. **In putioarr's config.toml**, add a `category` field to each service:
   ```toml
   [sonarr]
   category = "tv"
   
   [radarr]
   category = "movies"
   ```

2. **In Sonarr/Radarr/Whisparr's download client settings**, set the same category in the Transmission configuration.

3. Downloads will then be organized into subdirectories:
   - Sonarr downloads → `/download_directory/tv/`
   - Radarr downloads → `/download_directory/movies/`
   - Whisparr downloads → `/download_directory/adult/`

This feature ensures each *arr application only sees and processes its own downloads.

## Connecting Sonarr/Radarr/Whisparr

putioarr pretends to be a Transmission client, so you add it in the \*arr just
like a real Transmission instance.

In **Settings → Download Clients → Add → Transmission**, set:

| Field | Value |
| --- | --- |
| Host | the host running putioarr (e.g. `putioarr` if on the same Docker network, or its IP) |
| Port | `9091` (or your configured `port`) |
| URL Base | `/transmission` |
| Username | the `username` from your config |
| Password | the `password` from your config |
| Category | the category for this \*arr, if you set one (e.g. `tv` for Sonarr, `movies` for Radarr) — must match the `category` in putioarr's config |

Click **Test**; it should turn green. Then **Save**.

Repeat for each \*arr, using that \*arr's category.

> **Important — same download path in both containers.** The \*arr imports a
> completed download by reading the files from disk itself, and putioarr only
> cleans up once it finds that import in the \*arr's history under its own
> path. So the \*arr must see the files putioarr downloaded **at the same
> path**: mount the *same* host directory into both containers at the same
> place (e.g. `/downloads` in putioarr and `/downloads` in Sonarr/Radarr), and
> set `download_directory` to that path. A **Remote Path Mapping** in the \*arr
> is not a substitute: the \*arr will import, but it records the import under
> its own path, so putioarr never sees it and never cleans up the local files
> or the put.io transfer.

## Troubleshooting

**Downloads finish, but nothing is imported and the files stay in
`download_directory`.**
This is almost always a path problem: the \*arr can't find the files putioarr
downloaded because it's looking at a different path (or doesn't have the volume
mounted at all). The \*arr's Activity → Queue usually shows a warning for the
download. Make sure the download directory is mounted into both containers at
the same path — see *Connecting Sonarr/Radarr/Whisparr* above — and confirm the
\*arr can list the files there. putioarr leaves the files alone until it sees
the import. After `import_timeout_secs` (2 hours by default) it logs "still not
imported … giving up watching" and stops checking that download.

**Downloads are imported, but the files stay in `download_directory` and on
put.io.**
putioarr didn't recognize the import. The usual cause is a Remote Path Mapping
or a different mount path in the \*arr, so the \*arr records the import under
a path putioarr doesn't know. Use the same path in both containers instead.

**The download client tests fine but grabs never appear on put.io.**
Check that the \*arr is sending grabs to putioarr (the Activity → Queue in the
\*arr) and watch putioarr's logs — every grab logs an "uploaded" line. Make sure
the `[putio] api_key` is valid (regenerate with `putioarr get-token`).

**Downloads go to the wrong folder / one \*arr imports another's downloads.**
Set a distinct `category` per \*arr in putioarr's config *and* the matching
Category in each \*arr's Transmission settings. See *Category-based Download
Directories* above.

**Nothing happens / no logs.** Raise the log level with `loglevel = "debug"` in
the config to see what putioarr is doing.

## TODO:
- Figure out a better way to map a transfer to a completed import. Since a transfer can contain multiple files (e.g. a whole season) we currently check if all video files have been imported. Most of the time this is fine, except when there are sample videos. sonarr/radarr/whisparr will not import samples, but will make no mention of the fact that the sample was skipped. Right now we check against the `skip_directories` list, which works, but might be tedious.
- Automatically pick the right putio proxy based on speed

## Thanks
Thanks to [davidchalifoux](https://github.com/davidchalifoux) for borrowed code from kaput-cli.