### Backend Setup: Install Python Dependencies

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Installs Python project dependencies using uv, creating a virtual environment and installing packages from pyproject.toml. It also supports installing development dependencies separately.

```bash
cd ytptube
uv sync
uv sync --group dev
```

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

### Frontend Setup: Install Node.js Dependencies

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Installs Node.js project dependencies using pnpm. Requires a .env file to be created based on .env.example for API configuration.

```bash
cd ui
pnpm install
```

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

### Backend Setup: Run Development Server

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Starts the backend development server using uv, making the API available at http://localhost:8081.

```bash
uv run app/main.py
```

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

### Frontend Setup: Run Development Server

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Starts the frontend development server using pnpm, making the UI available at http://localhost:8082 or the specified port.

```bash
pnpm dev
```

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

### Create Directories and Start ytptube Container

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Command to set up the necessary directory structure and start the ytptube Docker container using Docker Compose. This is a prerequisite for the Docker Compose configuration.

```bash
mkdir -p ./config && mkdir -p ./downloads/{tmp,files} && docker compose -f compose.yaml up -d

```

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

### Backend Testing: Pytest Example

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

An example of how to write backend tests using pytest in Python. It demonstrates testing a class method and an asynchronous function, including setup for singleton classes.

```python
import pytest
from app.library.YourModule import YourClass

class TestYourClass:
    def test_feature_name(self):
        """Test description."""
        # Arrange
        instance = YourClass()
        
        # Act
        result = instance.method()
        
        # Assert
        assert result == expected_value
    
    @pytest.mark.asyncio
    async def test_async_feature(self):
        """Test async functionality."""
        result = await async_function()
        assert result is not None

from app.library.Presets import Presets

class TestPresets:
    def setup_method(self):
        """Reset singleton before each test."""
        Presets._reset_singleton()
    
    def teardown_method(self):
        """Reset singleton after each test."""
        Presets._reset_singleton()
```

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

### Manage Download Presets (GET and PUT)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Endpoints for managing download presets. GET /api/presets lists all configured presets, while PUT /api/presets allows creating or updating preset configurations.

```bash
# Get all presets
curl http://localhost:8081/api/presets
```

```bash
# Create/update presets
curl -X PUT http://localhost:8081/api/presets \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "4K Quality",
      "description": "Best quality up to 4K resolution",
      "folder": "4K Videos",
      "template": "% (title)s [%(id)s].%(ext)s",
      "cli": "--format \"bv*[height<=2160]+ba/b\" --merge-output-format mkv"
    },
    {
      "name": "Audio Podcast",
      "description": "Extract audio with chapter markers",
      "folder": "Podcasts",
      "cli": "--extract-audio --audio-format mp3 --audio-quality 0 --add-chapters --embed-thumbnail"
    }
  ]'
```

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

### Get Pip Package Versions (GET /api/dev/pip)

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Development-only endpoint that returns the installed versions of configured pip packages. The response is a JSON object mapping package names to their versions or null if not installed.

```json
{ "package": "version-or-null", "...": null }
```

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

### TypeScript/Vue Code Style: Component Setup

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Illustrates TypeScript and Vue code style conventions, emphasizing type safety, explicit imports, and component structure using `<script setup lang="ts">`. It defines props and emits for a Vue component.

```vue
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import type { DownloadItem } from '~/types/download'

const props = defineProps<{ 
    items: Array<DownloadItem>
    
}()>

const emit = defineEmits<{ 
    (e: 'itemSelected', item: DownloadItem): void
    
}()>

const selectedItem = ref<DownloadItem | null>(null)
</script>
```

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

### Get yt-dlp CLI Options (GET /api/yt-dlp/options)

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves the current configuration of yt-dlp command-line options used by the application. The response is a JSON array where each object describes an option, its flags, group, and whether it's ignored by ytptube.

```json
[
  {
    "description": "Description of the option",
    "flags":[ "--option", "-o" ],
    "group": "Option Group",
    "ignored": false
  },
  ...
]
```

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

### Gitea CI Setup Variables

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Configuration steps for setting up CI on Gitea. Requires creating a `GIT_TOKEN` secret with your Gitea personal access token and a `REGISTRY` variable pointing to your Docker registry.

```yaml
secrets:
  GIT_TOKEN: # Your Gitea personal access token

variables:
  REGISTRY: gitea.domain.org # Your Docker registry
```

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

### Configure Notifications (GET, PUT, POST)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Endpoints for managing notification settings. GET /api/notifications retrieves current settings, PUT /api/notifications configures webhook notifications, and POST /api/notifications/test sends a test notification.

```bash
# Get notification configuration
curl http://localhost:8081/api/notifications
```

```bash
# Configure notifications
curl -X PUT http://localhost:8081/api/notifications \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Discord Webhook",
      "on": ["completed", "error"],
      "request": {
        "type": "json",
        "method": "POST",
        "url": "https://discord.com/api/webhooks/…",
        "headers": [
          {"key": "Content-Type", "value": "application/json"}
        ]
      }
    },
    {
      "name": "Apprise Notification",
      "on": [],
      "request": {
        "type": "form",
        "method": "POST",
        "url": "apprise://telegram/bot_token/chat_id",
        "headers": []
      }
    }
  ]'
```

```bash
# Test notifications
curl -X POST http://localhost:8081/api/notifications/test
```

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

### Autoload yt-dlp Plugins

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Instructions for automatically loading yt-dlp plugins in YTPTube. Create a 'yt-dlp' folder within the '/config' directory and follow yt-dlp's plugin installation documentation.

```bash
# Create the plugin directory
mkdir -p /config/yt-dlp

# Follow yt-dlp documentation for plugin installation within this directory.
# Example: cp /path/to/your/plugin.py /config/yt-dlp/
```

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

### GET /api/yt-dlp/options

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves the current yt-dlp command-line options configured for the application.

```APIDOC
## GET /api/yt-dlp/options

### Description
Get the current yt-dlp CLI options as a JSON object.

### Method
GET

### Endpoint
/api/yt-dlp/options

### Response
#### Success Response (200)
- **Options** (array) - An array of objects, each representing a yt-dlp option.
  - **description** (string) - A description of the option.
  - **flags** (array of strings) - The command-line flags for the option (e.g., "--option", "-o").
  - **group** (string) - The group to which the option belongs.
  - **ignored** (boolean) - Indicates if this option is ignored by ytptube (true) or not (false).

### Response Example
```json
[
  {
    "description": "Description of the option",
    "flags":[ "--option", "-o" ],
    "group": "Option Group",
    "ignored": false
  },
  ...
]
```
```

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

### GET /api/task_definitions/

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves a list of all available task definitions.

```APIDOC
## GET /api/task_definitions/

### Description
Fetches a list of all predefined task types and their configurations.

### Method
GET

### Endpoint
/api/task_definitions/

### Parameters
None

### Request Example
```
GET /api/task_definitions/
```

### Response
#### Success Response (200)
- **task_definitions** (array) - A list of task definition objects, each including identifier, description, and parameters.

#### Response Example
```json
{
  "task_definitions": [
    {
      "identifier": "download_video",
      "description": "Downloads a video from a given URL.",
      "parameters": [
        "url",
        "output_format"
      ]
    }
  ]
}
```
```

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

### GET /api/docs/{file}

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Serves documentation files from the GitHub repository. This endpoint allows clients to fetch documentation such as README, FAQ, and API specifications, as well as image assets.

```APIDOC
## GET /api/docs/{file}

### Description
Serve documentation files from the GitHub repository. This endpoint allows clients to fetch documentation such as README, FAQ, and API specifications, as well as image assets.

### Method
GET

### Endpoint
/api/docs/{file}

### Parameters
#### Path Parameters
- **file** (string) - Required - Documentation filename (e.g., `README.md`, `FAQ.md`, `API.md`, `sc_short.jpg`, `sc_simple.jpg`)

### Response
#### Success Response (200)
- **File content** (various) - Content of the requested documentation file with appropriate `Content-Type` header.
- **Cache-Control** (string) - `max-age=3600` (Cached for 1 hour)

#### Error Response (404 Not Found)
- **`{ "error": "Doc file not found." }`** - Returned if the file is not in the allowed list.

#### Error Response (500 Internal Server Error)
- **Error message** - Returned if fetching from GitHub fails.

> **Note**: This endpoint also responds to direct file paths like `/README.md`, `/FAQ.md`, etc. without the `/api/docs/` prefix.
```

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

### GET /api/presets

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Fetches all available download presets. Presets define configurations for downloading content, such as filename templates and additional yt-dlp options.

```APIDOC
## GET /api/presets

### Description
Retrieve all available download presets.

### Method
GET

### Endpoint
`/api/presets`

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Comma-separated list of fields to include in response.

### Response
#### Success Response (200)
- **Success**: An array of preset objects, where each object contains details like `id`, `name`, `description`, `folder`, `template`, `cookies`, and `cli` options. The `default` field indicates if it's the default preset.
```

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

### Condition Management (Bash)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Demonstrates how to manage conditional rules for yt-dlp. Includes examples for retrieving all conditions, creating or updating them with specific filters and CLI arguments, and testing a condition against a given URL.

```bash
# Get all conditions
curl http://localhost:8081/api/conditions

# Create/update conditions
curl -X PUT http://localhost:8081/api/conditions \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Use proxy for region-locked content",
      "filter": "availability = \"needs_auth\" & channel_id = \"UCxxxxxx\"",
      "cli": "--proxy http://proxy.example.com:8080"
    },
    {
      "name": "Skip short videos",
      "filter": "yt:duration < 60",
      "cli": "--reject \"duration<60\""
    }
  ]'

# Test condition against URL
curl -X POST http://localhost:8081/api/conditions/test \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "condition": "yt:duration > 180",
    "preset": "default"
  }'

# Response:
# {
#   "status": true,
#   "condition": "yt:duration > 180",
#   "data": {"duration": 212, "title": "..."}
# }

```

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

### GET /api/dev/loop

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Development-only endpoint to display details about the event loop and running tasks.

```APIDOC
## GET /api/dev/loop

### Description
Development-only. Show event loop details and running tasks.

### Method
GET

### Endpoint
/api/dev/loop

### Response
#### Success Response (200 OK)
- **total_tasks** (number) - The total number of tasks currently in the event loop.
- **loop** (string) - A representation of the event loop status.
- **tasks** (array) - An array of running tasks, each with its details and stack trace.
  - **task** (string) - Information about the task.
  - **stack** (array of strings) - The stack trace of the task.

#### Error Response (403 Forbidden)
Returned if the application is not in development mode.

### Response Example
```json
{ "total_tasks": 1, "loop": "...", "tasks": [ { "task": "...", "stack": ["..."] } ] }
```
```

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

### GET /api/dev/pip

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Development-only endpoint to retrieve the installed versions of configured pip packages.

```APIDOC
## GET /api/dev/pip

### Description
Development-only. Return installed versions for configured pip packages.

### Method
GET

### Endpoint
/api/dev/pip

### Response
#### Success Response (200 OK)
- **Packages** (object) - An object where keys are package names and values are their installed versions (or null if not installed or version not found).

### Response Example
```json
{ "package": "version-or-null", "...": null }
```
```

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

### Start YTPTube with Docker Compose

Source: https://github.com/arabcoders/ytptube/blob/master/README.md

This command uses Docker Compose to bring up the YTPTube service defined in the compose.yaml file. The `-d` flag ensures the container runs in detached mode. Access the WebUI at http://localhost:8081 after execution.

```bash
mkdir -p ./{config,downloads} && docker compose -f compose.yaml up -d
```

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

### GET /api/history/add

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Quickly add a single video URL to the download queue using a GET request with query parameters.

```APIDOC
## GET /api/history/add

### Description
Add a single URL to the download queue via GET request. This endpoint is a quick way to add a single item to the queue without needing to format a full JSON body. It is primarily for convenience and may not support all options available in the full POST `/api/history` endpoint.

### Method
GET

### Endpoint
/api/history/add

### Query Parameters
- **url** (string) - Required - The video URL to download.
- **preset** (string) - Optional - The preset name to use for the download.

### Response
#### Success Response (200 OK)
- **status** (boolean) - `true` if added to the queue, `false` otherwise.
- **message** (string) - A message indicating the result of the operation.

#### Response Example
```json
{
  "status": true,
  "message": "Video added to queue."
}
```

### Error Responses
- **400 Bad Request**: If the `url` parameter is missing.
  ```json
  {
    "status": false,
    "message": "URL is required."
  }
  ```
- **404 Not Found**: If the specified `preset` is not found.
  ```json
  {
    "status": false,
    "message": "Preset not found."
  }
  ```
```

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

### Get Notification Targets (GET /api/notifications)

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves the configured notification targets and the event types they are set to receive. The response includes a list of notification configurations and a list of all allowed event types.

```json
{
  "notifications": [
    {
      "id": "uuid",
      "name": "...",
      "on": ["completed", "error",...],
      "request":{
        "type": "json|form",
        "method": "POST|PUT",
        "url": "https://...",
        "headers":[
          {"key": "...", "value": "..."},
          ...
        ]
      }
    }
  ],
  "allowedTypes": ["added", "completed", "error", "cancelled", "cleared", "log_info", "log_success", "log_warning", "log_error", "test"]
}
```

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

### POST /api/yt-dlp/command/

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Constructs a complete yt-dlp CLI command by merging user input, presets, and default configurations.

```APIDOC
## POST /api/yt-dlp/command/

### Description
Build a complete yt-dlp CLI command string with priority-based argument merging from user input, presets, and defaults.

### Method
POST

### Endpoint
/api/yt-dlp/command/

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the item to download.
- **preset** (string) - Optional - The name of the preset to apply.
- **folder** (string) - Optional - The output subfolder (relative to `download_path`).
- **template** (string) - Optional - The output filename template.
- **cli** (string) - Optional - Additional yt-dlp CLI arguments.
- **cookies** (string) - Optional - Authentication cookies as a string.

### Request Example
```json
{
  "url": "https://example.com/video",
  "preset": "preset_name",
  "folder": "subfolder",
  "template": "% (title)s.%(ext)s",
  "cli": "--write-sub --embed-subs",
  "cookies": "cookie_string"
}
```

**Note**: If cookies are provided, they will be saved to a temporary file, and `--cookies <file>` will be added to the command.

**Priority System**: User inputs > Preset configurations > Default settings.

### Response
#### Success Response (200)
- **command** (string) - The fully constructed yt-dlp CLI command.

#### Response Example
```json
{
  "command": "--output-path /downloads/subfolder --output %(title)s.%(ext)s --write-sub --embed-subs https://example.com/video"
}
```

#### Error Responses
- `403 Forbidden`: If the console is disabled (`YTP_CONSOLE_ENABLED=false`).
- `400 Bad Request`: If the request body is invalid JSON or fails item format validation.
- `400 Bad Request`: If there's an error building the CLI command.
```

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

### Schedule Automated Downloads (PUT and GET)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Endpoints for scheduling automated downloads. PUT /api/tasks configures scheduled tasks with cron expressions, and GET /api/tasks retrieves all scheduled tasks.

```bash
# Create scheduled tasks
curl -X PUT http://localhost:8081/api/tasks \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "a2ae3f18-4428-4e32-9d4c-0cc45af8bb48",
      "name": "Daily News Channel",
      "url": "https://youtube.com/@news_channel",
      "timer": "0 8 * * *",
      "preset": "1080p",
      "folder": "News/Daily",
      "auto_start": true,
      "handler_enabled": true,
      "enabled": true
    },
    {
      "name": "Podcast Feed",
      "url": "https://youtube.com/playlist?list=PLxxxxxx",
      "timer": "*/15 * * * *",
      "preset": "Audio Only",
      "folder": "Podcasts",
      "cli": "--dateafter now-7d"
    }
  ]'
```

```bash
# Get all scheduled tasks
curl http://localhost:8081/api/tasks
```

```bash
# Toggle task enabled status
curl -X POST http://localhost:8081/api/tasks/a2ae3f18-4428-4e32-9d4c-0cc45af8bb48/toggle
```

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

### Enable Hardware Acceleration in compose.yaml

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

This snippet shows how to modify your `compose.yaml` file to mount necessary devices for hardware acceleration (VAAPI on x86_64 systems). It includes mounting DRI devices and adding the correct group IDs for GPU access. Ensure group IDs match your system's configuration.

```yaml
services:
 ytptube:
    ........ # see above for the rest of the configuration
    devices:
      # mount the dri devices to the container if you only have one gpu you can simply do the following
      - /dev/dri:/dev/dri                       
      # Otherwise, selectively mount the devices you need.
      - /dev/dri/card0      # Intel GPU device
      - /dev/dri/renderD128 # Intel GPU render node
    group_add:
      # Add the necessary groups to the container to access the gpu devices.
      - 44   # it might be different on your system.                                 
      - 105  # it might be different on your system.
```

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

### Docker Compose for YTPTube with External Storage

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Docker Compose configuration for YTPTube, demonstrating how to mount local directories, NFS shares, and SMB shares as download targets. Includes user ID/GID configuration and volume definitions.

```yaml
services:
  ytptube:
    user: "${UID:-1000}:${UID:-1000}" # change this to your user id and group id, for example: "1000:1000"
    image: ghcr.io/arabcoders/ytptube:latest
    container_name: ytptube
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      # Config must be mounted locally as read-write sqlite doesn't support network mounts.
      - ./config:/config:rw
      # Mount a local directory
      - ./downloads:/downloads/local:rw
      # Mount the NFS share
      - nfs-data:/downloads/nfs:rw
      # Mount the SMB share
      - smb-data:/downloads/smb:rw
    tmpfs:
      - /tmp

volumes:
  nfs-data:
    driver: local
    driver_opts:
      type: nfs
      o: addr=10.0.0.3,rw,nfsvers=4 # <--- Change server IP and options
      device: ":/exported/path" # <--- Remote NFS path
  
  smb-data:
    driver: local
    driver_opts:
      type: cifs
      o: username=my_username,password=my_password,vers=3.0,uid=1000,gid=1000,file_mode=0777,dir_mode=0777 # <--- Change options to fit your needs
      device: "//10.0.0.3/public" # <--- Remote SMB path

```

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

### Enable Basic Authentication for YTPTube

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Instructions to enable basic HTTP authentication for YTPTube by setting environment variables `YTP_AUTH_USERNAME` and `YTP_AUTH_PASSWORD`. After setting these variables, the container needs to be restarted. A URL format is provided for browsers that may not display the prompt directly.

```bash
# Set environment variables in your shell or docker-compose.yml
export YTP_AUTH_USERNAME="your_username"
export YTP_AUTH_PASSWORD="your_password"

# Then restart your YTPTube container/application
```

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

### Docker Compose for YTPTube with POT Token Provider

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

This YAML configuration sets up two services: 'ytptube' for the main application and 'bgutil_provider' for generating POT tokens. It maps volumes for configuration and downloads, and sets up networking for the services.

```yaml
services:
  ytptube:
    user: "${UID:-1000}:${UID:-1000}" # change this to your user id and group id, for example: "1000:1000"
    image: ghcr.io/arabcoders/ytptube:latest
    container_name: ytptube
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - ./config:/config:rw
      - ./downloads:/downloads:rw
    tmpfs:
      - /tmp
    depends_on:
      - bgutil_provider
  bgutil_provider:
    init: true
    image: brainicism/bgutil-ytdlp-pot-provider:latest
    container_name: bgutil_provider
    restart: unless-stopped
```

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

### Get Event Loop Details (GET /api/dev/loop)

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Development-only endpoint to display event loop details and running tasks. Returns detailed information about the event loop and its tasks, including stack traces. Returns a 403 Forbidden if not in development mode.

```json
{ "total_tasks": 1, "loop": "...", "tasks": [ { "task": "...", "stack": ["..."] } ] }
```

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

### Manage Download Presets

Source: https://context7.com/arabcoders/ytptube/llms.txt

Endpoints for listing, creating, and updating download presets.

```APIDOC
## GET /api/presets

### Description
Retrieves a list of all configured download presets.

### Method
GET

### Endpoint
/api/presets

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the preset.
- **name** (string) - The name of the preset.
- **description** (string) - A description of the preset's purpose.
- **default** (boolean) - Indicates if this is the default preset.
- **cli** (string) - The command-line arguments associated with the preset.

### Response Example
```json
[
  {
    "id": "3e163c6c-64eb-4448-924f-814b629b3810",
    "name": "default",
    "description": "Default preset for yt-dlp",
    "default": true,
    "cli": "--socket-timeout 30 --download-archive %(config_path)s/archive.log"
  },
  {
    "id": "441675ed-b739-40f0-a0b0-1ecfcb9dc48d",
    "name": "Mobile",
    "cli": "--socket-timeout 30 -t mp4 --merge-output-format mp4",
    "description": "Optimized for mobile devices"
  }
]
```
```

```APIDOC
## PUT /api/presets

### Description
Creates or updates download preset configurations. This endpoint accepts an array of preset objects.

### Method
PUT

### Endpoint
/api/presets

### Request Body
- **name** (string) - Required - The name of the preset.
- **description** (string) - Optional - A description of the preset.
- **folder** (string) - Optional - The default download folder for this preset.
- **template** (string) - Optional - Filename template for downloads.
- **cli** (string) - Required - The command-line arguments for yt-dlp.

### Request Example
```bash
curl -X PUT http://localhost:8081/api/presets \
  -H "Content-Type: application/json" \
  -d "[
    {
      "name": "4K Quality",
      "description": "Best quality up to 4K resolution",
      "folder": "4K Videos",
      "template": \"%(title)s [%(id)s].%(ext)s\",
      "cli": "--format \"bv*[height<=2160]+ba/b\" --merge-output-format mkv"
    },
    {
      "name": "Audio Podcast",
      "description": "Extract audio with chapter markers",
      "folder": "Podcasts",
      "cli": "--extract-audio --audio-format mp3 --audio-quality 0 --add-chapters --embed-thumbnail"
    }
  ]"
```
```

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

### GET /api/tasks

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves a list of all tasks.

```APIDOC
## GET /api/tasks

### Description
Fetches a list of all tasks currently being processed or queued.

### Method
GET

### Endpoint
/api/tasks

### Parameters
None

### Request Example
```
GET /api/tasks
```

### Response
#### Success Response (200)
- **tasks** (array) - A list of task objects, each containing details like task_id, status, type, etc.

#### Response Example
```json
{
  "tasks": [
    {
      "task_id": "a1b2c3d4",
      "status": "running",
      "type": "download",
      "progress": 50
    },
    {
      "task_id": "e5f6g7h8",
      "status": "queued",
      "type": "conversion"
    }
  ]
}
```
```

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

### Manage Download Archive (GET, POST, DELETE)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Endpoints for managing the download archive. GET /api/archiver reads archive entries, POST /api/archiver adds items to prevent re-downloads, and DELETE /api/archiver removes items to allow re-downloads.

```bash
# Read archive for a preset
curl "http://localhost:8081/api/archiver?preset=default"
```

```bash
# Add items to archive (prevent re-download)
curl -X POST http://localhost:8081/api/archiver \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "default",
    "items": ["youtube XYZ789", "vimeo 123456"],
    "skip_check": false
  }'
```

```bash
# Remove from archive (allow re-download)
curl -X DELETE http://localhost:8081/api/archiver \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "default",
    "items": ["youtube XYZ789"]
  }'
```

```bash
# Remove specific item from archive by history ID
curl -X DELETE http://localhost:8081/api/history/abc123/archive
```

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

### iOS Shortcut Configuration for YTPTube

Source: https://github.com/arabcoders/ytptube/blob/master/FAQ.md

Instructions for configuring an iOS shortcut to send links to a YTPTube instance. Users need to replace a placeholder URL with their YTPTube instance URL and provide authentication credentials if required. The shortcut allows dynamic preset selection from the instance.

```sh
# Example placeholder configuration within the shortcut's script
# Replace 'https://ytp.example.org' with your YTPTube instance URL
# Replace 'username:password' with your credentials or leave empty if no authentication
YTPTUBE_INSTANCE_URL="https://ytp.example.org"
AUTH_CREDENTIALS="username:password"
```

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

### Prepare ZIP Download

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Prepares a ZIP download of selected files (including detected sidecars). Returns a short-lived token.

```APIDOC
## POST /api/file/download

### Description
Prepare a ZIP download of selected files (and detected sidecars). Returns a short-lived token.

### Method
POST

### Endpoint
/api/file/download

### Parameters
#### Request Body
```json
[ "relative/path/file1.ext", "relative/path/file2.ext" ]
```

### Response
#### Success Response (200)
```json
{ "token": "<uuid>", "files": ["relative/path/file1.ext", "..."] }
```

#### Error Response
- `400 Bad Request` if the body is not a JSON array or contains no valid files.

```

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

### Build yt-dlp Command String

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

The /api/yt-dlp/command/ endpoint constructs a complete yt-dlp command line string. It merges user-provided arguments, presets, and defaults with a defined priority system (User > Preset > Default). This endpoint requires the console to be enabled via the YTP_CONSOLE_ENABLED environment variable.

```json
{
  "url": "https://example.com/video",// required - item url
  "preset": "preset_name",           // optional - preset name to apply
  "folder": "subfolder",             // optional - output folder (relative to download_path)
  "template": "% (title)s.%(ext)s",   // optional - output filename template
  "cli": "--write-sub --embed-subs", // optional - additional yt-dlp CLI arguments
  "cookies": "cookie_string"         // optional - authentication cookies as string
}
```

```json
{
  "command": "--output-path /downloads/subfolder --output %(title)s.%(ext)s --write-sub --embed-subs https://example.com/video"
}
```

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

### GET /api/history

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves all download history entries.

```APIDOC
## GET /api/history

### Description
Retrieves all records from the download history.

### Method
GET

### Endpoint
/api/history

### Parameters
None

### Request Example
```
GET /api/history
```

### Response
#### Success Response (200)
- **history** (array) - A list of all history entries.

#### Response Example
```json
{
  "history": [
    {
      "id": 15,
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "filename": "rick_astley_never_gonna_give_you_up.mp4",
      "title": "Never Gonna Give You Up",
      "date_added": "2023-10-27T10:00:00Z"
    },
    {
      "id": 16,
      "url": "https://www.youtube.com/watch?v=example2",
      "filename": "another_video.mp4",
      "title": "Another Example Video",
      "date_added": "2023-10-26T15:30:00Z"
    }
  ]
}
```
```

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

### Python Code Style: Process Download Item

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Demonstrates Python code style guidelines including line length, indentation, quotes, type hints, absolute imports, and Yoda comparisons. This snippet processes a download item and handles potential exceptions.

```python
from app.library.Download import Download
from app.library.ItemDTO import ItemDTO

async def process_download(item: ItemDTO) -> bool:
    """Process a download item."""
    try:
        if "pending" == item.status:  # Yoda comparison
            result = await Download.start(item)
            return result.success
    except Exception as e:
        LOG.error(f"Download failed: {e}")
        return False
```

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

### GET /api/history/add

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Adds an entry to the download history.

```APIDOC
## GET /api/history/add

### Description
Records a completed download item into the user's history.

### Method
GET

### Endpoint
/api/history/add

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the downloaded content.
- **filename** (string) - Required - The name of the downloaded file.
- **title** (string) - Optional - The title of the video or content.

### Request Example
```
GET /api/history/add?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ&filename=rick_astley_never_gonna_give_you_up.mp4&title=Never%20Gonna%20Give%20You%20Up
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **id** (integer) - The ID of the newly added history entry.

#### Response Example
```json
{
  "message": "History entry added successfully",
  "id": 15
}
```
```

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

### Frontend Testing: Running Vitest

Source: https://github.com/arabcoders/ytptube/blob/master/CONTRIBUTING.md

Commands to execute frontend tests using Vitest. Supports running all tests and running tests in watch mode.

```bash
cd ui
pnpm test
pnpm test:watch
```

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

### GET /api/ping

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Checks if the API is alive and responsive.

```APIDOC
## GET /api/ping

### Description
This endpoint is used to check the health and responsiveness of the API.

### Method
GET

### Endpoint
/api/ping

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the API is working.

#### Response Example
{
  "message": "pong"
}
```

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

### GET /api/ping

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

A health-check endpoint to verify if the API is running.

```APIDOC
## GET /api/ping

### Description
Health-check endpoint.

### Method
GET

### Endpoint
/api/ping

### Response
#### Success Response (200)
- **status** (string) - Indicates the API is responsive ('pong').

#### Response Example
```json
{
  "status": "pong"
}
```
```

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

### File Browser and Download Operations (Bash)

Source: https://context7.com/arabcoders/ytptube/llms.txt

Provides examples for browsing downloaded files, performing file operations like rename, move, create directory, and delete, and preparing/downloading ZIP archives. It uses `curl` to interact with the API endpoints.

```bash
# Browse root directory
curl http://localhost:8081/api/file/browser/

# Response:
# {
#   "path": "/",
#   "contents": [
#     {
#       "type": "dir",
#       "content_type": "dir",
#       "name": "Music Videos",
#       "path": "/Music Videos",
#       "is_dir": true,
#       "mtime": "2024-01-15T10:30:00Z"
#     },
#     {
#       "type": "file",
#       "content_type": "video",
#       "name": "video.mp4",
#       "path": "/video.mp4",
#       "size": 52428800,
#       "mimetype": "video/mp4",
#       "is_file": true
#     }
#   ]
# }

# File operations
curl -X POST http://localhost:8081/api/file/actions \
  -H "Content-Type: application/json" \
  -d '[
    {"action": "rename", "path": "old_name.mp4", "new_name": "new_name.mp4"},
    {"action": "move", "path": "video.mp4", "new_path": "Archive/"},
    {"action": "directory", "path": "", "new_dir": "New Folder"},
    {"action": "delete", "path": "unwanted.mp4"}
  ]'

# Prepare ZIP download
curl -X POST http://localhost:8081/api/file/download \
  -H "Content-Type: application/json" \
  -d '["video1.mp4", "video2.mkv"]'

# Response: {"token": "uuid-token", "files": ["video1.mp4", "video2.mkv"]}

# Download ZIP file
curl -O http://localhost:8081/api/file/download/uuid-token

```

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

### Add Videos to Download Queue (REST API)

Source: https://context7.com/arabcoders/ytptube/llms.txt

This endpoint allows users to add single or multiple videos to the download queue. It supports customizable download options such as presets, output folders, filename templates, and yt-dlp command-line arguments. A quick add option via GET is also available for bookmarklet integration.

```bash
curl -X POST http://localhost:8081/api/history \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "preset": "1080p",
    "folder": "Music Videos/Rick Astley",
    "template": "% (title)s - %(uploader)s.%(ext)s",
    "cli": "--write-subs --embed-subs --write-thumbnail",
    "cookies": "# Netscape HTTP Cookie File format...",
    "auto_start": true
  }'

# Response:
# [{"status": "queued"}]

# Add multiple videos in one request
curl -X POST http://localhost:8081/api/history \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://youtube.com/watch?v=video1",
      "preset": "default"
    },
    {
      "url": "https://youtube.com/watch?v=video2",
      "preset": "Audio Only",
      "folder": "Podcasts"
    }
  ]'

# Quick add via GET (bookmarklet-friendly)
curl "http://localhost:8081/api/history/add?url=https://youtube.com/watch?v=dQw4w9WgXcQ&preset=1080p"

# Response:
# {"status": true, "message": "Added to queue"}
```

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

### GET /api/archiver

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves all archived download history entries.

```APIDOC
## GET /api/archiver

### Description
Fetches all entries that have been moved to the archive.

### Method
GET

### Endpoint
/api/archiver

### Parameters
None

### Request Example
```
GET /api/archiver
```

### Response
#### Success Response (200)
- **archived_items** (array) - A list of archived history entries.

#### Response Example
```json
{
  "archived_items": [
    {
      "id": 10,
      "url": "https://www.youtube.com/watch?v=example0",
      "filename": "archived_video.mp4",
      "title": "Archived Video",
      "date_added": "2023-10-20T09:00:00Z"
    }
  ]
}
```
```

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

### GET /api/task_definitions/{identifier}

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves a specific task definition by its identifier.

```APIDOC
## GET /api/task_definitions/{identifier}

### Description
Fetches the details of a single task definition based on its unique identifier.

### Method
GET

### Endpoint
/api/task_definitions/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the task definition.

### Request Example
```
GET /api/task_definitions/download_video
```

### Response
#### Success Response (200)
- **task_definition** (object) - An object containing the details of the specified task definition.

#### Response Example
```json
{
  "task_definition": {
    "identifier": "download_video",
    "description": "Downloads a video from a given URL.",
    "parameters": [
      "url",
      "output_format"
    ]
  }
}
```
```

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

### GET /api/history/{id}

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves a single history entry by its ID.

```APIDOC
## GET /api/history/{id}

### Description
Fetches a specific download history entry using its unique identifier.

### Method
GET

### Endpoint
/api/history/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the history entry to retrieve.

### Request Example
```
GET /api/history/15
```

### Response
#### Success Response (200)
- **history_entry** (object) - An object containing the details of the history entry (url, filename, title, date_added, favorite).

#### Response Example
```json
{
  "history_entry": {
    "id": 15,
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "filename": "rick_astley_never_gonna_give_you_up.mp4",
    "title": "Never Gonna Give You Up",
    "date_added": "2023-10-27T10:00:00Z",
    "favorite": true
  }
}
```
```

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

### GET /api/yt-dlp/url/info

Source: https://github.com/arabcoders/ytptube/blob/master/API.md

Retrieves information about a YouTube video or playlist URL.

```APIDOC
## GET /api/yt-dlp/url/info

### Description
Fetches metadata and available formats for a given YouTube URL.

### Method
GET

### Endpoint
/api/yt-dlp/url/info

### Parameters
#### Query Parameters
- **url** (string) - Required - The YouTube URL to get information for.

### Request Example
```
GET /api/yt-dlp/url/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

### Response
#### Success Response (200)
- **info** (object) - An object containing detailed information about the URL, including title, formats, thumbnails, etc.

#### Response Example
```json
{
  "info": {
    "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
    "formats": [
      { "format_id": "22", "ext": "mp4", "resolution": "1280x720" },
      { "format_id": "137", "ext": "mp4", "resolution": "1920x1080" }
    ],
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  }
}
```
```