initial publish commit

README.md

@@ -0,0 +1,96 @@
+# Tdarr - Auto-Requeue Script
+
+Automatically refills the Tdarr **staging section** whenever the number of
+actively processed files drops below a configurable threshold.
+
+## Features
+
+| Feature                     | What it does                                                                                       |
+| --------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Staging guard**           | Checks how many files are currently being processed.                                               |
+| **Smart picker**            | Pulls up to `BATCH_SIZE` items from Status ▪ **Processed** (`table2`) whose **New Size** is `"-"`. |
+| **GUI-identical requeue**   | Re-queues the files with **one** `bulk-update-files` call (same payload the web UI sends).         |
+| **Retry + back-off**        | Network errors or timeouts are retried with exponential back-off.                                  |
+| **Timeout-resilient**       | If `bulk-update-files` times out, the script checks if the operation succeeded anyway.             |
+| **Internal scheduler**      | No cron needed – the script runs continuously and checks every `TDARR_INTERVAL_MIN`.               |
+| **JSON / pretty logging**   | Toggle pretty output with `LOG_PRETTY=1`.                                                          |
+| **All settings via `.env`** | No hard-coded values; perfect for CI or Docker.                                                    |
+
+## File Selection Criteria
+
+The script selects files based on the following logic:
+
+* It queries the internal `table2` (equivalent to the **Status ▪ Processed** tab in the Tdarr UI).
+* It filters for files that have the **“New Size” field set to `"-"`**, meaning:
+
+  * The file was either skipped by a plugin decision or
+  * The file was marked as “Transcode Success / Not Required”
+  * And **no new output file** was produced (Tdarr left the file untouched).
+* The top `BATCH_SIZE` of these files (sorted by Tdarr’s internal logic) are requeued.
+
+This selection ensures that:
+
+* You don’t accidentally requeue already optimized/transcoded files
+* Only skipped or pass-through candidates get another chance (e.g., after plugin changes)
+
+## Requirements
+
+* Tdarr Server ≥ 2.40 (the `bulk-update-files` endpoint exists since 2024)
+* Node 18+ (ESM support)
+
+## Installation
+
+```bash
+git clone https://github.com/your-org/tdarr-auto-requeue.git
+cd tdarr-auto-requeue
+npm i axios, pino, minimist, dotenv
+```
+
+## Configuration
+
+Create a `.env` file in the project root (or set the variables in your CI /
+container manager):
+
+```dotenv
+# Tdarr connection
+TDARR_URL=https://encode.computerliebe.org/api/v2
+TDARR_API_KEY=tapi_XXXXXXXXXXXX
+
+# Behaviour
+TDARR_STAGING_LIMIT=50        # refill if staging count < 50
+TDARR_BATCH_SIZE=50           # requeue at most 50 files per cycle
+TDARR_INTERVAL_MIN=60         # how often the script runs (minutes)
+TDARR_RETRIES=4               # API retries
+TDARR_BACKOFF_MS=2000         # initial back-off in ms
+BULK_TIMEOUT_MS=120000        # max wait time for bulk-update-files in ms
+
+# Logging
+LOG_LEVEL=info                # or debug / warn / error
+LOG_PRETTY=1                  # pretty-printed logs
+```
+
+> **Tip:** create a dedicated API key in *Tdarr ▪ Tools ▪ API keys* with **Server
+> write** permissions only.
+
+## Usage
+
+```bash
+node tdarr_requeue.mjs            # runs once, or in interval mode if TDARR_INTERVAL_MIN is set
+```
+
+The script will automatically re-run every `TDARR_INTERVAL_MIN` minutes.
+No cron, systemd, or external timers needed.
+
+## Troubleshooting
+
+| Symptom                         | Fix                                                                                             |
+| ------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `401 Unauthorized`              | API key wrong or missing.                                                                       |
+| `FST_ERR_VALIDATION`            | Your server expects a different payload – update Tdarr or open an issue with the error JSON.    |
+| Files not visible after requeue | Refresh the **Status ▪ Queued / Staging** view; workers may take a few seconds to pick them up. |
+| `ECONNABORTED` timeout          | This is handled gracefully. If the staging count increased, the script proceeds.                |
+| “Too many open files”           | Increase `ulimit -n` on the host; Tdarr can be I/O intensive.                                   |
+
+---
+
+**Happy transcoding!**