Merge pull request #54 from Unpackerr/docs/whisparr-as-radarr

Document Unpackerr v1 upgrades

Author: davidnewhall

docs/install/choosemethod.md

@@ -4,6 +4,9 @@ title: Choose Install Method
 description: Choose an Unpackerr install method.
 ---
 
+Coming from 0.16 or earlier? Read [Upgrading to v1](/docs/install/upgrading) before you
+pull a new image or package.
+
 We recommend installing Unpackerr the same way you installed your
 Starr or download apps. If your existing infrastructure exists in Docker,
 then Unpackerr should probably live in Docker too.

docs/install/compose.md

@@ -54,6 +54,21 @@ And if you're trying to watch a folder, add this `environment:` variable with _y
       - UN_FOLDER_0_PATH=/downloads/autoxtract
 ```
 
+On Docker, filesystem events are often missing. Add a poll interval on that
+same key if nothing shows in the queue:
+
+```yaml
+      - UN_FOLDER_0_INTERVAL=1s
+```
+
+Incomplete downloads can wait on a suffix instead of polling:
+
+```yaml
+      - UN_FOLDER_0_WAIT_EXTENSION_0=.part
+```
+
+See [Folder Watcher](docker#folder-watcher).
+
 ## Data Mount
 
 <DataMount />

docs/install/configuration.md

@@ -14,52 +14,65 @@ Expand the blue sections to see excerpts from the
 [example docker-compose.yml](https://github.com/Unpackerr/unpackerr/blob/main/examples/docker-compose.yml)
 and [example config](https://github.com/Unpackerr/unpackerr/blob/main/examples/unpackerr.conf.example) files.
 
+## Web UI
+
+:::danger[Web UI]
+
+- Added in v1.0.0 (October 2026).
+
+Most users should use the Web UI to configure Unpackerr.
+While you can use this page for reference, you should avoid editing the config file.
+
+- See [Web UI page](web-ui).
+
+:::
+
+Unpackerr has a built in Web UI where you can configure all the settings using a validated form.
+The Web UI also makes it easy to see what Unpackerr is doing live and to view the extraction history.
+This page exists from a time when configuration required editing a file. Now it's for power users.
+
+**Use the web interface. Don't edit the config file.**
+
 ## Config
 
 - Setting a log file is strongly recommended. This makes it much easier to troubleshoot problems.
 - To use a config file in Docker, mount `/config` to the container and Unpackerr will write a config file.
   - Update the new file at `/config/unpackerr.conf` and restart the container.
-- When using a config file you must uncomment at minimum the `[[header]]` <font color="gray">
-  ex. `[[radarr]]`</font>, `url` and `api_key`.
+- When using a config file you must uncomment at minimum the `[header.key]` <font color="gray">
+  ex. `[radarr.radarr]`</font>, `url` and `api_key`.
 - Uncomment means remove the hash `#` at the beginning of the line.
 - The config file format is [TOML](https://toml.io).
   - Indentation is not important like YAML files, but it's used for ease of readability.
   - You may use `"` or `'` or `'''` or `"""` to wrap strings. Recommend `'` for paths.
 
-### Generator
-
-[Notifiarr](https://notifiarr.com) hosts a configuration file maker.
-Simply fill in a web form, and click a button to get a working config file.
-
-- **Access the generator here: https://notifiarr.com/unpackerr**
-
 ### Two+ Instances
 
-When adding a second (or third+) instance to the __config file__, you just
-add another `[[header]]` <font color="gray">ex. `[[sonarr]]`</font> and the
-`url`/`api_key`/etc under it. When adding a second instance to the __environment
-variables__, you must increment the `0` to a `1`. And to a `2` if you have 3
-instances. There is no limit to the number of supported instances. This notation
-works for all Starr apps, folders, command hooks, and webhooks.
+When adding a second (or third+) instance to the __config file__, use another
+named table <font color="gray">ex. `[sonarr.0]`, `[sonarr.uhd]`</font> and the
+`url`/`api_key`/etc under it. Environment variables use that same key:
+`UN_SONARR_0_URL` or `UN_SONARR_uhd_URL`. Array rows from older configs load as
+keys `0`, `1`, …. There is no limit to the number of supported instances. This
+notation works for all Starr apps, folders, command hooks, and webhooks.
 
 <details>
   <summary>Config examples with multiple instances.</summary>
 
 - Config File example with two Radarrs and two Folders.
 
-```yaml
-[[radarr]]
+```toml
+[radarr.0]
  url = "http://radarr"
  api_key = "32characters"
 
-[[radarr]]
+[radarr.uhd]
+ name = "4K"
  url = "http://radarr4k"
  api_key = "32morecharacters"
 
-[[folder]]
+[folder.0]
  path = "/data/downloads/software/"
 
-[[folder]]
+[folder.games]
  path = "/data/downloads/games/"
 ```
 
@@ -68,16 +81,80 @@ works for all Starr apps, folders, command hooks, and webhooks.
 ```shell
 UN_RADARR_0_URL=http://radarr
 UN_RADARR_0_API_KEY=32characters
-UN_RADARR_1_URL=http://radarr4k
-UN_RADARR_1_API_KEY=32morecharacters
+UN_RADARR_uhd_URL=http://radarr4k
+UN_RADARR_uhd_API_KEY=32morecharacters
 UN_FOLDER_0_PATH=/data/downloads/software/
-UN_FOLDER_1_PATH=/data/downloads/games/
+UN_FOLDER_games_PATH=/data/downloads/games/
 ```
 
 </details>
 
-Anything that [has a header](https://github.com/Unpackerr/unpackerr/blob/main/examples/unpackerr.conf.example#L99)
-with double brackets `[[..]]` can be repeated as many times as you'd like.
+Anything that has a header like `[sonarr.0]` or `[folder.software]` can be repeated with a unique key.
+
+### Whisparr
+
+- Changed in v1.0.0 (October 2026).
+
+Whisparr uses the Radarr API. Configure it as `[radarr.whisparr]` (env `UN_RADARR_whisparr_*`).
+Set `name = "Whisparr"` if logs and hooks should keep that label.
+
+### Named instances
+
+- Added in v1.0.0 (October 2026).
+
+Starr apps, folders, webhooks, and command hooks are identified by a short key, not by list position.
+In the config file use `[sonarr.uhd]`, `[folder.software]`, `[webhook.discord]`; in env use `UN_SONARR_uhd_URL`,
+`UN_FOLDER_software_PATH`, `UN_WEBHOOK_discord_URL`. The optional `name` on Starr and hooks is only a label
+(`name = "Starrs & Stripes"`). Existing `[[sonarr]]` / `[[folder]]` / `[[webhook]]` tables still load as keys
+`0`, `1`, …. Open that section in the web UI and click Save: Unpackerr rewrites the file to named tables automatically.
+
+### Watch folders
+
+- Changed in v1.0.0 (October 2026).
+
+Folder watch is not Starr. Each `[folder.<key>]` is a path Unpackerr extracts
+on its own. The generated tables below list every option.
+
+**Poll interval** is per folder (`interval`, env `UN_FOLDER_<key>_INTERVAL`).
+Default `0s` uses filesystem events. Set `1s` (or similar) on Docker and CIFS
+when new archives never show in the queue. Global `folders.interval` /
+`UN_FOLDERS_INTERVAL` is gone; leftover `[folders] interval` is ignored.
+Details: [Docker Folder Watcher](docker#folder-watcher).
+
+**After a restart**, recent folder history returns to the live queue the same
+way Starr items do: EXTRACTED still waiting on `delete_after`, EXTRACTFAILED
+retries, interrupted EXTRACTING, QUEUED, and WAITING after a retry. A path
+you removed from config is not restored. Windows matches watch paths without
+regard to drive-letter case.
+
+**Incomplete downloads:** `wait_extensions` keeps the item WAITING while a
+matching file exists in that item's top folder (`.part`, `.crdownload`, …).
+Nested paths are not scanned. The queue shows the blocking filename.
+Recheck is every 5s and does not enable the poller.
+Env: `UN_FOLDER_<key>_WAIT_EXTENSION_0=.part`.
+
+**Empty folders:** `skip_empty` (env `UN_FOLDER_<key>_SKIP_EMPTY`) drops
+archive-free folders after `start_delay` with no history row and no webhook.
+
+### Lidarr cue sheets
+
+Lidarr only. `split_flac` splits a completed download that has a CUE sheet.
+It splits both FLAC and APE images into one file per track, then asks Lidarr
+to import those tracks. Sonarr, Radarr, and Readarr ignore this setting.
+
+When the image is APE, `ape_format` chooses the files those tracks become:
+
+- `ape` keeps Monkey's Audio. This is the default, and an empty value means the same.
+- `wav` and `flac` decode the audio. FLAC cannot store 32-bit or float PCM.
+
+`ape_compression` applies only when the format is APE. The choices are `1000`,
+`2000`, `3000`, `4000`, and `5000`. A default of `0` is set to `2000` (normal).
+WAV and FLAC ignore compression.
+
+A lone `.ape` file that has no cue sheet is left for Lidarr to import as-is.
+
+Environment variables use the instance key: `UN_LIDARR_<key>_SPLIT_FLAC`,
+`UN_LIDARR_<key>_APE_FORMAT`, and `UN_LIDARR_<key>_APE_COMPRESSION`.
 
 {/* The Global content is generated from here: https://github.com/Unpackerr/unpackerr/tree/main/init/config */}
 <Global />
@@ -97,8 +174,8 @@ by setting the value to `filepath:/path/to/file.txt`. In other words, if you wan
 your Radarr API key to be read from a separate file, instead of storing it directly
 in the config file or environment variables you can do this:
 
-```json
-[[radarr]]
+```toml
+[radarr.0]
   url = "https://some.url/radarr"
   api_key = "filepath:/etc/secrets/radarr.txt"
 ```

docs/install/docker.md

@@ -106,16 +106,28 @@ docker run -e PUID=1000 -e PGID=100 -d -v /mnt/data:/data -v /mnt/config:/config
 
 ## Folder Watcher
 
-Watching folders in Docker will cause Unpackerr to constantly poll the
-watched-folder for changes at a default rate of `1s` (1 second).
+The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to notice new
+archives. Each watch path has its own `interval`. The default is `0s`, which
+means filesystem events only — Unpackerr does **not** poll.
 
-The Folder Watch feature uses `inotify` (a.k.a. `fsnotify`) to identify changes to the
-watched folder. A folder-poller is automatically started when run in Docker because
-`inotify` is unreliable. Disable the folder poller (and rely on `inotify` only) by
-setting `folders.interval` (`UN_FOLDERS_INTERVAL`) to `1ms`.
+Docker bind mounts and CIFS often drop or delay those events, so items never
+appear in the queue. Turn polling on for that path:
 
-If Unpackerr has trouble determining when downloads are finished, set
-`start_delay` high enough to avoid beginning extracting files that are
-still being transferred.
+- Web UI: **Settings → Folders** → **Poll interval** (try `1s`).
+- Config: `interval = "1s"` under `[folder.downloads]`.
+- Env: `UN_FOLDER_downloads_INTERVAL=1s` (same key as the table).
+
+Leave `interval` at `0s` when native fsnotify works. Polling increases disk
+reads. A folder with a poll interval uses the poller only; other folders keep
+fsnotify.
+
+v0.x Docker installs auto-polled every 1s via global `folders.interval`
+(`UN_FOLDERS_INTERVAL`). That setting is gone. An old `[folders] interval`
+line in the file is ignored.
+
+If Unpackerr starts extracting files that are still downloading, raise
+`start_delay`, or set `wait_extensions` (for example `.part`, `.crdownload`)
+on that folder. Waiting items are rechecked every 5 seconds without turning
+the poller on. See [Watch folders](configuration#watch-folders).
 
 **Alternatively, run Unpackerr as a native service instead of in Docker.**

docs/install/unraid.md

@@ -6,31 +6,32 @@ description: Install Unpackerr on your unRAID server!
 
 # unRAID Install
 
-Unpackerr is available in the
-[Community Applications](https://github.com/selfhosters/unRAID-CA-templates/blob/main/templates/unpackerr.xml)
-on unRAID. Install it from the `Apps` page; see screenshot that follows.
+Unpackerr is available in
+[Community Applications](https://github.com/selfhosters/unRAID-CA-templates/blob/master/templates/unpackerr.xml)
+on unRAID. Install it from the **Apps** page.
 
-![Community Applications Unpackerr install](/img/screenshots/unraid/install1.png "install")
+The golift template mounts **appdata** at `/config`, publishes port **5656** for
+the web UI, and runs as `--user 99:100`. Configure Sonarr, Radarr, Lidarr, and
+the rest in the browser after install. Do not put Starr URLs and API keys back
+into environment variables unless you want those fields locked in the UI.
 
-On the install screen, fill in the `URL` and `API_KEY` for one or more of the Starr apps.
+Upgrading an existing 0.x container? See [Upgrading to v1](/docs/install/upgrading#unraid).
 
-:::note[Multiple Instances]
-If you have, for instance, two Radarrs, you can simply add two new variables:
-`UN_RADARR_1_URL` and `UN_RADARR_1_API_KEY`. If you have 3, then increase
-the `1` to a `2` and so on. This works for all Starr apps, folders, webhooks and command
-hooks. There is no limit to how many you may configure.
-:::
+![Community Applications Unpackerr install](/img/screenshots/unraid/install1.png "install")
 
-It's also recommended that you set a log file.
-Put it in your downloads location; an example follows.
+On the install screen, set **Downloads Location** so it matches your Starr apps
+(next section). Leave **appdata** at `/mnt/user/appdata/unpackerr/` unless you
+prefer another folder. Apply, then open the WebUI.
 
-![Bind volume for Unpackerr log file](/img/screenshots/unraid/bindvolume.png "bind volume")
+First login is user `admin`. The password is printed once in the container log
+(`Generated temporary UI password`). Change it in Settings.
 
 :::tip[Download Location]
-The most common misconfiguration on unRAID, by far, and it's not even a close second, is
-having the correct path mounted for your download location. As you see in the screenshot above,
-it's set to `host:/mnt/user/downloads` and `container:/downloads`. This is almost certainly
-not what you want. **Do this:**
+The most common misconfiguration on unRAID, by far, and it's not even a close
+second, is having the correct path mounted for your download location. As you
+see in the screenshot below, a host path of `/mnt/user/downloads` with a
+container path of `/downloads` is almost certainly not what you want.
+**Do this:**
 
 1. Go into Unraid.
 1. Click on Docker.
@@ -43,31 +44,38 @@ not what you want. **Do this:**
 
 ![Starr app volume mounts](/img/screenshots/unraid/starrmounts.png "starr mounts")
 
-If the highlighted portions above are not identical to the one below, then things are bound to work poorly.
-In other words, if Unpackerr has `/downloads <-> /mnt/user/downloads` and Sonarr has
-`/data <-> /mnt/user/downloads`, Unpackerr will not be able to find your files. In this hypothetical, you
-must edit the Unpackerr `/downloads` mount, and change the _Container Path_ to `/data` so it matches Sonarr.
+If the highlighted portions above are not identical to the one below, then
+things are bound to work poorly. In other words, if Unpackerr has
+`/downloads <-> /mnt/user/downloads` and Sonarr has
+`/data <-> /mnt/user/downloads`, Unpackerr will not be able to find your files.
+In this hypothetical, you must edit the Unpackerr `/downloads` mount, and
+change the _Container Path_ to `/data` so it matches Sonarr.
 
 ![Unpackerr volume mount](/img/screenshots/unraid/unpackerrmount.png "unpackerr mount")
 :::
 
 ## Permissions
 
-Set the UID and GID by adding `--user uid:gid` to the `Extra Parameters`
-section of the unraid template after enabling the `Advanced` view.
-![Enable Docker advanced view](/img/screenshots/unraid/advancedview.png "advanced view")
-You must make these match your Starr app so hard links work correctly.
-**Other containers, use env variables such as `PUID` and `PGID`, but the
-Go Lift unpackerr container does not use these.**
-e.g. If Sonarr has `PUID` of `99` and `PGID` of `100`, then you must
-add **`--user 99:100`** to `Extra Parameters` as shown below.
+The template Extra Parameters already include `--user 99:100` (unRAID
+`nobody:users`), which matches typical linuxserver Starr containers. Change it
+if your Sonarr/Radarr uid:gid is different. **Other containers use `PUID` and
+`PGID`; the golift image does not.**
 
 ![Unpackerr Extra Parameters UID and GID](/img/screenshots/unraid/extraparameters.png "extra parameters")
 
+The appdata folder and the config file inside it must be writable by that
+same user, or the UI cannot Save. If needed:
+
+```bash
+chown -R 99:100 /mnt/user/appdata/unpackerr
+```
+
 ## Video Guide
 
 This guide is provided by a community member, [@Celsian](https://www.youtube.com/@Celsian),
-consider giving him a sub and a like.
+consider giving him a sub and a like. It was recorded against the old env-var
+template; ignore the Sonarr/Radarr variable fields and use the web UI instead.
+The download-path matching still applies.
 
 <iframe height="500" width="100%" src="https://www.youtube.com/embed/FfJqgm69ydA"
 frameborder="0" allowfullscreen title="UnRAID Video Guide"