===============
LIBRARY RULES
===============
From library maintainers:
- Maintain legal framing: AniBridge is a compatibility/automation shim, not a real torrent/P2P client.

### Docker Compose: Minimal AniBridge Setup

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/quickstart.md

This configuration sets up AniBridge using Docker Compose with minimal settings. It maps port 8000 and sets a download path. Verification is done using `docker compose up -d` and `curl`.

```yaml
services:
  anibridge:
    image: ghcr.io/zzackllack/anibridge:latest
    container_name: anibridge
    ports:
      - "8000:8000"   # host:container
    environment:
      - QBIT_PUBLIC_SAVE_PATH=/downloads
    volumes:
      - ./downloads:/data/downloads   # host path → container path
      - ./data:/data                        # DB, logs
```

```bash
docker compose up -d
curl -sS http://localhost:8000/health
# {"status":"ok"}
```

--------------------------------

### Search Suggest API Endpoint Sample (JSON)

Source: https://github.com/zzackllack/anibridge/blob/main/specs/007-sto-v2-support/findings.md

An example of the GET request and JSON response for the `/api/search/suggest` endpoint, used for fast lookup of shows, people, and genres.

```json
GET https://s.to/api/search/suggest?term=9-1-1
{
  "shows": [
    {"name": "9-1-1", "url": "/serie/9-1-1"},
    {"name": "9-1-1: Lone Star", "url": "/serie/9-1-1-lone-star"}
  ],
  "people": [],
  "genres": []
}
```

--------------------------------

### Anibridge Example .env Configuration

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/configuration.md

An example .env file demonstrating common Anibridge configurations for catalog sites, download directories, base URLs, indexer settings, provider order, and concurrency.

```ini
CATALOG_SITES=aniworld.to,s.to,megakino
DOWNLOAD_DIR=./data/downloads/anime
DATA_DIR=./data
ANIWORLD_BASE_URL=https://aniworld.to
STO_BASE_URL=https://s.to
MEGAKINO_BASE_URL=https://megakino1.to
INDEXER_NAME="AniBridge Torznab"
TORZNAB_RETURN_TEST_RESULT=true
PROVIDER_ORDER=VOE,Filemoon,Streamtape,Vidmoly,SpeedFiles,Doodstream,LoadX,Luluvdo,Vidoza
SOURCE_TAG=WEB
RELEASE_GROUP=aniworld
RELEASE_GROUP_STO=sto
MAX_CONCURRENCY=3
```

--------------------------------

### Install uv on Linux/macOS using a script

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/contributing.md

Installs the uv package manager on Linux and macOS by downloading and executing an installation script. This is a recommended method for setting up the development environment.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Sonarr Docker Volume Mapping Example

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/integrations/clients/sonarr.md

This example demonstrates the required Docker volume mappings for both AniBridge and Sonarr containers to ensure they share the same download directory. It also shows how to set the QBIT_PUBLIC_SAVE_PATH environment variable for AniBridge.

```bash
# Example using host path /path/to/downloads/anime
# AniBridge container mapping
-v /path/to/downloads/anime:/data/downloads/anime

# Sonarr container mapping
-v /path/to/downloads/anime:/downloads

# AniBridge environment variable
QBIT_PUBLIC_SAVE_PATH=/downloads
```

--------------------------------

### Add Magnet to qBittorrent Shim

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/testing-with-curl.md

Submits a magnet URI to the qBittorrent shim API to initiate a download. It includes parameters for category, skipping checks, and starting paused. The response is saved for verification. Requires a magnet URL to be found previously.

```zsh
if [ -z "$MAGNET" ]; then
  echo "No magnet found; aborting add."
  exit 1
fi

curl -s -b /tmp/qb_cookies.txt -X POST "$QBIT/torrents/add" \
  -F "urls=$MAGNET" \
  -F "category=$CATEGORY" \
  -F "skip_checking=true" \
  -F "paused=false" \
  -F "root_folder=false" \
  -o /tmp/qbit_add_response.txt

cat /tmp/qbit_add_response.txt
```

--------------------------------

### qBittorrent Shim Add Torrent

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/testing-with-curl.md

Adds a magnet link to the qBittorrent shim to initiate a download.

```APIDOC
## POST /api/v2/torrents/add

### Description
Submits a magnet URL to the qBittorrent shim, triggering the download of the specified torrent.

### Method
POST

### Endpoint
/api/v2/torrents/add

### Parameters
#### Request Body
- **urls** (string) - Required - The magnet URL or torrent file URL.
- **category** (string) - Optional - The category to assign to the torrent.
- **skip_checking** (boolean) - Optional - Whether to skip checking the torrent's integrity (default: true).
- **paused** (boolean) - Optional - Whether to start the torrent paused (default: false).
- **root_folder** (boolean) - Optional - Whether to use the root folder setting (default: false).

### Request Example
```bash
curl -s -b /tmp/qb_cookies.txt -X POST "$QBIT/torrents/add" \
  -F "urls=$MAGNET" \
  -F "category=$CATEGORY" \
  -F "skip_checking=true" \
  -F "paused=false" \
  -F "root_folder=false"
```

### Response
#### Success Response (200)
- **Plain Text** - Typically returns 'Ok.' on successful addition.

#### Response Example
```
Ok.
```
```

--------------------------------

### Sonarr Cannot Connect to qBittorrent

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/troubleshooting.md

Guidance on configuring Sonarr to connect to qBittorrent, including base URL, authentication, and category setup.

```APIDOC
## Sonarr Cannot Connect to qBittorrent

### Description
Steps to resolve connection issues between Sonarr and qBittorrent.

### Method
N/A (Configuration Checks)

### Endpoint
N/A (Sonarr Configuration)

### Configuration Details
- **Base URL**: Should be set to `http://host:8000/` (replace `host` with the actual hostname or IP address of the machine running qBittorrent).
- **Type**: Set to `qBittorrent`.
- **Authentication**: Authentication is currently stubbed, meaning any username and password combination will work.

### Related API Endpoint
- **/api/v2/torrents/categories**: Use this endpoint to retrieve available categories in qBittorrent.

### Response
N/A (This section describes configuration rather than API responses.)
```

--------------------------------

### S.to API Endpoint Examples (JavaScript)

Source: https://github.com/zzackllack/anibridge/blob/main/specs/007-sto-v2-support/github-issue.md

This snippet showcases various S.to API endpoints discovered for searching and retrieving data. It includes examples for instance search, text templates, series comments, content adjustments, and collection management. These endpoints are crucial for AniBridge's data discovery and indexing functionalities.

```javascript
http://s.to/api/text-templates/search?q=12324
https://s.to/api/collections/for-series/
, j = "episode" === m ? "/api/episodes/".concat(e, "/comments") : "/api/series/".concat(t, "/comments");
const {data: n} = await l.get("/api/content-adjustments/".concat(e, "/").concat(t, "/data"));

      `await l.post("/api/content-adjustments", o, {
                                headers: {
                                    "X-CSRF-TOKEN": a,
                                    "Content-Type": "multipart/form-data"
                                }
                            }),

            const n = await fetch("/api/collections/for-series/".concat(e), {
                credentials: "same-origin"
            })

/api/collections/my?term=
/api/collections/for-series/
/api/collections/attach
```

--------------------------------

### qBittorrent Shim Torrents Info

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/testing-with-curl.md

Retrieves a list of torrents currently managed by the qBittorrent shim, optionally filtered by category.

```APIDOC
## GET /api/v2/torrents/info

### Description
Fetches information about the torrents being managed by the qBittorrent shim. Can be filtered by category.

### Method
GET

### Endpoint
/api/v2/torrents/info

### Query Parameters
- **category** (string) - Optional - Filters the torrent list by the specified category.

### Request Example
```bash
curl -s -G "$QBIT/torrents/info" --data-urlencode "category=$CATEGORY"
```

### Response
#### Success Response (200)
- **JSON Object** - An array of torrent objects, each containing details like hash, name, progress, and status.

#### Response Example
```json
[
  {
    "hash": "...",
    "name": "Example.Show.S01E04.1080p.WEB-DL",
    "size": 1234567890,
    "progress": 0.95,
    "state": "downloading",
    "category": "tv-sonarr",
    ...
  }
]
```
```

--------------------------------

### VitePress Setup with TypeScript and Data Hook

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/api/operations/[operationId].md

This script setup block configures a VitePress page using TypeScript. It imports the `useData` hook from 'vitepress' to access page parameters, specifically `params.operationId`, which is likely used for dynamic content generation.

```typescript
import { useData } from 'vitepress'

const { params } = useData()
```

--------------------------------

### GET /api/v2/sync/maindata

Source: https://github.com/zzackllack/anibridge/blob/main/specs/003-add-sto-support/contracts/qbittorrent-sync.md

Synchronizes main data with the qBittorrent client, including torrent information and categories. Supports incremental updates using the 'rid' parameter.

```APIDOC
## GET /api/v2/sync/maindata

### Description
Synchronizes main data with the qBittorrent client. This endpoint provides torrent information, download progress, state, and category mappings. It supports incremental synchronization via the `rid` query parameter.

### Method
GET

### Endpoint
/api/v2/sync/maindata

### Parameters
#### Query Parameters
- **rid** (integer) - Optional - An incremental sync token. If provided, the response will contain only changes since the last `rid`. If omitted or invalid, a full sync payload is returned.

#### Headers/Cookies
- **SID** (string) - Required - The session cookie `anibridge` for authentication.

### Request Example
```
GET /api/v2/sync/maindata?rid=12345 HTTP/1.1
Host: your-qbittorrent-host:port
Cookie: SID=anibridge
```

### Response
#### Success Response (200)
- **torrents** (object) - An object where keys are torrent hashes and values are torrent objects. Each torrent object includes `anibridge_source_site` (string enum `aniworld`/`sto`).
- **categories** (object) - A map of category names to category objects. May include site-aware defaults.
- Download metadata (name, progress, state, etc.) are unchanged from standard qBittorrent API.

#### Response Example
```json
{
  "rid": 12346,
  "torrents": {
    "torrent_hash_1": {
      "name": "Example Torrent",
      "size": 1000000000,
      "progress": 0.5,
      "state": "downloading",
      "anibridge_source_site": "aniworld"
    }
  },
  "categories": {
    "AniBridge": {
      "name": "AniBridge",
      "savePath": "/path/to/downloads"
    }
  }
}
```

#### Error Handling
- **403 Forbidden**: Returned for authentication failures. No response body.
- **Invalid `rid`**: Results in a full sync payload without additional error fields.
```

--------------------------------

### qBittorrent Shim Login

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/testing-with-curl.md

Logs into the qBittorrent shim to obtain a session cookie, which may be required for subsequent requests.

```APIDOC
## POST /api/v2/auth/login

### Description
Authenticates with the qBittorrent shim API to establish a session and retrieve cookies.

### Method
POST

### Endpoint
/api/v2/auth/login

### Parameters
#### Request Body
- **username** (string) - Optional - The username for authentication (often empty).
- **password** (string) - Optional - The password for authentication (often empty).
- **remember** (boolean) - Optional - Whether to remember the login session (default: false).

### Request Example
```bash
curl -i -s -c /tmp/qb_cookies.txt -X POST "$HOST/api/v2/auth/login" -d "username=&password=&remember=false"
```

### Response
#### Success Response (200)
- **Set-Cookie Header** - Contains the session cookie (e.g., SID).

#### Response Example
```
HTTP/1.1 200 OK
Server: AniBridge/1.0
Set-Cookie: SID=abcdef123456; Path=/; HttpOnly
Content-Type: text/plain; charset=utf-8
Content-Length: 2

Ok.
```
```

--------------------------------

### qBittorrent Shim Sync Maindata

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/testing-with-curl.md

Retrieves synchronization data, often used by applications like Sonarr to update their library status.

```APIDOC
## GET /api/v2/sync/maindata

### Description
Fetches main data synchronization information, which includes current torrent states and other relevant details for client applications.

### Method
GET

### Endpoint
/api/v2/sync/maindata

### Request Example
```bash
curl -s -G "$QBIT/sync/maindata"
```

### Response
#### Success Response (200)
- **JSON Object** - Contains various synchronization data, including lists of torrents and their statuses.

#### Response Example
```json
{
  "torrents": [
    {
      "hash": "...",
      "name": "Example.Show.S01E04.1080p.WEB-DL",
      "progress": 1.0,
      "state": "completed",
      ...
    }
  ],
  "server_state": {
    "download_rate": 1000000,
    "upload_rate": 500000,
    ...
  }
}
```
```

--------------------------------

### Download and Run AniBridge Binary (Bare Metal)

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/quickstart.md

This command downloads the latest AniBridge release for macOS (Apple Silicon) using `curl`, extracts the archive, makes the binary executable, and runs it. It assumes the user is on a compatible system.

```bash
# macOS (Apple Silicon example)
curl -L -o anibridge.tar.gz \
  "https://github.com/zzackllack/AniBridge/releases/latest/download/anibridge-macos-arm64.tar.gz"
tar -xzf anibridge.tar.gz && chmod +x anibridge
./anibridge
```

--------------------------------

### Run AniBridge from Source using uv

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/quickstart.md

This command uses `uv` to synchronize dependencies and then run the AniBridge application from its Python source code. It assumes the project has a `pyproject.toml` or similar configuration for `uv`.

```bash
uv sync --frozen
uv run python -m app.main
```

--------------------------------

### Access Site Data with useData() in Markdown (Vue)

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/api-examples.md

Demonstrates how to use the `useData()` hook from VitePress within a Vue script setup block in a Markdown file to access theme, page, and frontmatter data. This allows dynamic display of site content.

```vue
<script setup>
import { useData } from 'vitepress'

const { theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>
```

--------------------------------

### Access Site Data with useData() in Vue Component

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/api-examples.md

Shows how to import and utilize the `useData()` hook within a Vue component's script setup to retrieve and display site, theme, page, and frontmatter information. This is useful for building dynamic UI elements.

```vue
<script setup>
import { useData } from 'vitepress'

const { site, theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>
```

--------------------------------

### Radarr Download Client Configuration

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/integrations/clients/radarr.md

Instructions on how to configure Radarr's download client settings to point to AniBridge's qBittorrent-compatible API.

```APIDOC
## Radarr Download Client Configuration

### Description
Configure Radarr to use AniBridge as a download client by setting up a qBittorrent client in Radarr's settings.

### Method
Manual Configuration Steps

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Notes
- Host: `anibridge` (or `localhost`)
- Port: `8000`
- Username/Password: Any value (auth is stubbed)
- Category: `prowlarr` or a custom category created via API.
```

--------------------------------

### Install uv on Windows using winget

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/contributing.md

Installs the uv package manager on Windows using the winget package manager. This provides an alternative method for Windows users to install uv.

```powershell
winget install --id=astral-sh.uv  -e
```

--------------------------------

### Sync Play Media with SyncplayConsole/syncplay

Source: https://github.com/zzackllack/anibridge/blob/main/specs/005-megakino-support/megakino-downloader.md

Initiates a Syncplay session for media playback. It dynamically selects the Syncplay executable based on the operating system (Windows or other). It connects to a specified Syncplay host, uses the logged-in username, and sets the room name to the media title. Dependencies include getpass, platform, subprocess, and common utility functions.

```python
import getpass
import platform
import subprocess

def syncplay(direct_links, titles):
    counter = 0
    for link in direct_links:
        title = titles[counter]
        executable = "SyncplayConsole" if platform.system() == "Windows" else "syncplay"
        syncplay_username = getpass.getuser()
        syncplay_hostname = "syncplay.pl:8997"

        command = [
            executable,
            "--no-gui",
            "--no-store",
            "--host", syncplay_hostname,
            "--name", syncplay_username,
            "--room", title,
            "--player", "mpv",
            link,
            "--",
            "--profile=fast",
            "--hwdec=auto-safe",
            "--fs",
            "--video-sync=display-resample",
            f"--force-media-title={title}"
        ]
        counter += 1
        subprocess.run(command)
```

--------------------------------

### Downloads Fail Immediately

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/guide/troubleshooting.md

Troubleshooting steps for downloads that fail immediately after being initiated. This involves checking provider order, language availability, and file renaming tools.

```APIDOC
## Downloads Fail Immediately

### Description
Diagnose and resolve issues where downloads are failing immediately upon initiation.

### Method
N/A (Configuration and Environment Checks)

### Troubleshooting Steps
1. **Check `PROVIDER_ORDER`**: Ensure the order of download providers is correctly configured and that the preferred providers are listed first.
2. **Verify Language Availability**: Confirm that the desired language for the content is available through the configured providers.
3. **Validate ffmpeg/ffprobe**: Ensure that `ffmpeg` and `ffprobe` are installed and accessible in the system's PATH. These tools are crucial for proper renaming and metadata handling.
4. **Inspect Logs**: Examine the logs located in `app/core/downloader.py` for any specific exceptions or error messages related to provider interactions or download processing.

### Response
N/A (This section describes troubleshooting steps rather than API responses.)
```

--------------------------------

### Install uv on Windows using PowerShell

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/contributing.md

Installs the uv package manager on Windows using PowerShell. This command bypasses execution policy restrictions to download and run the installation script.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Install uv on macOS using Homebrew

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/contributing.md

Installs the uv package manager on macOS using the Homebrew package manager. This is a prerequisite for setting up the development environment.

```bash
brew install uv
```

--------------------------------

### Set up AniBridge development environment

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/contributing.md

Clones the AniBridge repository, navigates into the directory, and synchronizes dependencies using uv. This prepares the local environment for development.

```bash
git clone https://github.com/zzackllack/AniBridge.git
cd AniBridge
uv sync --frozen
```

--------------------------------

### Start Dev Server (Python)

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/developer/running.md

Starts the AniBridge development server using Python. Auto-reloads on code changes. To force reload, set the ANIBRIDGE_RELOAD environment variable to 1.

```bash
python -m app.main
```

--------------------------------

### Install Dependencies (uv)

Source: https://github.com/zzackllack/anibridge/blob/main/specs/001-absolute-episode-numbers/quickstart.md

Installs project dependencies using 'uv sync --frozen'. Assumes a Python 3.12 environment. This command ensures all necessary packages are available for the project.

```bash
uv sync --frozen
```

--------------------------------

### qBittorrent API Shim - App

Source: https://github.com/zzackllack/anibridge/blob/main/docs/src/api/qbittorrent.md

Endpoints for application-level information and settings.

```APIDOC
## qBittorrent App Endpoints

### Description
Provides endpoints for retrieving application-level information, such as version and build information.

### Method
GET

### Endpoint
/api/v2/app/version

### Response
#### Success Response (200)
- **version** (string) - The version of the qBittorrent application.

#### Response Example
```json
{
  "version": "4.5.0"
}
```

---

### Method
GET

### Endpoint
/api/v2/app/buildInfo

### Response
#### Success Response (200)
- **build_info** (string) - Detailed build information for the application.

#### Response Example
```json
{
  "build_info": "Build: 20230101-abcdef12345"
}
```
```