### Basic Docker Installation for Pinchflat

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This command demonstrates the basic Docker run command to start Pinchflat. It maps ports, mounts volumes for configuration and downloads, and sets the timezone.

```bash
docker run \
  -e TZ=America/New_York \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Full Environment Variable Configuration Example for Pinchflat

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This Docker run command showcases a comprehensive example of configuring Pinchflat using various environment variables. It covers logging, authentication, networking, performance tuning, and persistent storage.

```bash
docker run \
  -e TZ=America/New_York \
  -e LOG_LEVEL=debug \
  -e UMASK=022 \
  -e BASIC_AUTH_USERNAME=admin \
  -e BASIC_AUTH_PASSWORD=mypassword \
  -e EXPOSE_FEED_ENDPOINTS=yes \
  -e ENABLE_IPV6=true \
  -e JOURNAL_MODE=wal \
  -e BASE_ROUTE_PATH=/ \
  -e YT_DLP_WORKER_CONCURRENCY=2 \
  -e ENABLE_PROMETHEUS=true \
  -p 8945:8945 \
  -v /data/pinchflat/config:/config \
  -v /data/pinchflat/downloads:/downloads \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Docker Configuration for RSS Podcast Feeds

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This example shows how to configure Docker for Pinchflat to generate RSS feeds, including setting up basic authentication and exposing feed endpoints. It also provides the URL format for RSS feeds and an example NGINX configuration for reverse proxying.

```bash
docker run \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  -e BASIC_AUTH_USERNAME=admin \
  -e BASIC_AUTH_PASSWORD=CHANGEME \
  -e EXPOSE_FEED_ENDPOINTS=yes \
  ghcr.io/kieraneglin/pinchflat:latest

# RSS feed URL format (use UUID, not numeric ID):
# https://your-domain.com/sources/{uuid}/feed

# Example NGINX location block for reverse proxy (protect app, expose feeds):
# location ~* (^/sources/[^/]+/feed(_image)?|^/media/[^/]+/(stream|episode_image))(\\.[a-zA-Z0-9]+)?$ {
#     proxy_pass $forward_scheme://$server:$port;
# }

# Get OPML feed of all sources:
# GET /sources/opml (requires token if EXPOSE_FEED_ENDPOINTS is not set)
```

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

### Pinchflat Media Profile Output Path Templates

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

These examples show how to configure custom output path templates for organizing downloaded media using Liquid-style syntax. They translate to yt-dlp format options and include available template variables.

```text
# Default template for general use
/{{ source_custom_name }}/{{ upload_yyyy_mm_dd }} {{ title }}/{{ title }} [{{ id }}].{{ ext }}

# Media Center preset (Plex/Jellyfin/Kodi compatible)
/shows/{{ source_custom_name }}/{{ season_by_year__episode_by_date_and_index }} - {{ title }} [{{ id }}].{{ ext }}

# Available custom template variables:
# {{ upload_year }}                    -> %(upload_date>%Y)S
# {{ upload_month }}                   -> %(upload_date>%m)S
# {{ upload_day }}                     -> %(upload_date>%d)S
# {{ upload_yyyy_mm_dd }}              -> %(upload_date>%Y-%m-%d)S
# {{ season_from_date }}               -> %(upload_date>%Y)S
# {{ season_episode_from_date }}       -> s%(upload_date>%Y)Se%(upload_date>%m%d)S
# {{ artist_name }}                    -> %(artist,creator,uploader,uploader_id)S
# {{ season_by_year__episode_by_date }} -> Season %(upload_date>%Y)S/s%(upload_date>%Y)Se%(upload_date>%m%d)S

# Any yt-dlp single-word option can be used directly:
# {{ title }}, {{ id }}, {{ ext }}, {{ channel }}, {{ playlist }}, etc.
```

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

### GET /sources

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Retrieve a list of all configured YouTube sources.

```APIDOC
## GET /sources

### Description
Returns a list of all YouTube channels or playlists currently being tracked.

### Method
GET

### Endpoint
/sources

### Response
#### Success Response (200)
- **sources** (array) - List of source objects

#### Response Example
[
  { "id": "src_1", "url": "https://youtube.com/@channel" }
]
```

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

### Docker Run Command with Exposed Feed Endpoints

Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds

This command extends the basic setup by adding the EXPOSE_FEED_ENDPOINTS environment variable, which makes the RSS feed, cover image, and media streaming endpoints accessible without authentication.

```bash
docker run \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  -e BASIC_AUTH_USERNAME=admin \
  -e BASIC_AUTH_PASSWORD=CHANGEME \
  -e EXPOSE_FEED_ENDPOINTS=yes \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### GET /media_profiles

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Retrieve a list of all configured media profiles.

```APIDOC
## GET /media_profiles

### Description
Returns a list of all media profiles configured in the system.

### Method
GET

### Endpoint
/media_profiles

### Response
#### Success Response (200)
- **profiles** (array) - List of media profile objects

#### Response Example
[
  { "id": "1", "name": "Default Profile" }
]
```

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

### YouTube Cookies Setup for Private/Age-Restricted Content

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Instructions for setting up YouTube cookies in Pinchflat to download private or age-restricted content. This involves exporting cookies from a browser, placing the `cookies.txt` file in the config directory, and configuring cookie behavior per source.

```bash
# 1. Export cookies from your browser using yt-dlp or browser extension
# On your personal computer (not the container):
yt-dlp --cookies-from-browser chrome --cookies cookies.txt "https://www.youtube.com"

# 2. Copy the cookies.txt content to Pinchflat's config directory
# Via container shell:
docker exec -it pinchflat bash
nano /config/extras/cookies.txt
# Paste your cookies content and save

# 3. Cookie Behaviour options per source:
# - Disabled: Never use cookies
# - When Needed: Use for indexing and retry failed downloads with cookies
# - All Operations: Use cookies for all operations
```

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

### Example Lifecycle Event Payload

Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts

A sample JSON structure representing the data passed to lifecycle scripts. This includes media details, source information, and profile configurations.

```json
{
  "id": 1,
  "description": "...",
  "title": "...",
  "source_id": 1,
  "media_filepath": "...",
  "upload_date": "2000-01-01",
  "original_url": "https://www.youtube.com/watch?v=abc123",
  "uuid": "0c496b24-e012-42d1-8f6d-bd2d59c2b1a3",
  "prevent_download": false,
  "prevent_culling": false,
  "inserted_at": "2000-01-01T00:00:00Z",
  "updated_at": "2000-01-01T00:00:00Z",
  "culled_at": null,
  "media_size_bytes": 40687134,
  "thumbnail_filepath": "..",
  "duration_seconds": 500,
  "nfo_filepath": "...",
  "livestream": false,
  "media_downloaded_at": "2000-01-01T00:00:00Z",
  "media_id": "abc123",
  "media_redownloaded_at": null,
  "metadata_filepath": null,
  "short_form_content": false,
  "subtitle_filepaths": [],
  "upload_date_index": 0,
  "source": {
    "id": 1,
    "description": "...",
    "custom_name": "...",
    "original_url": "https://www.youtube.com/playlist?list=321cba",
    "uuid": "bb645fa8-9f7b-4dbf-a8e2-0f6a7d55f4d5",
    "media_profile_id": 1,
    "index_frequency_minutes": -1,
    "fast_index": false,
    "download_media": true,
    "download_cutoff_date": null,
    "retention_period_days": null,
    "title_filter_regex": null,
    "output_path_template_override": null,
    "collection_type": "playlist",
    "collection_name": "...",
    "inserted_at": "2000-01-01T00:00:00Z",
    "updated_at": "2000-01-01T00:00:00Z",
    "banner_filepath": null,
    "collection_id": "321cba",
    "fanart_filepath": null,
    "last_indexed_at": "2000-01-01T00:00:00Z",
    "nfo_filepath": "...",
    "poster_filepath": null,
    "series_directory": "...",
    "media_profile": {
      "id": 1,
      "name": "...",
      "output_path_template": "...",
      "download_subs": true,
      "download_auto_subs": false,
      "embed_subs": true,
      "sub_langs": "en",
      "download_thumbnail": true,
      "embed_thumbnail": true,
      "download_metadata": false,
      "embed_metadata": true,
      "shorts_behaviour": "exclude",
      "livestream_behaviour": "exclude",
      "preferred_resolution": "1080p",
      "redownload_delay_days": 1,
      "download_nfo": true,
      "download_source_images": true,
      "sponsorblock_behaviour": "disabled",
      "sponsorblock_categories": [],
      "inserted_at": "2000-01-01T00:00:00Z",
      "updated_at": "2000-01-01T00:00:00Z"
    }
  }
}
```

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

### Utilize Health Check Endpoint

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Information on using the Pinchflat health check endpoint for monitoring and orchestration. Includes examples for direct curl commands, Docker run configurations, and Docker Compose service definitions.

```bash
# Health check endpoint (no authentication required)
curl http://localhost:8945/healthcheck

# Docker health check configuration
docker run \
  --health-cmd="curl -f http://localhost:8945/healthcheck || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  ghcr.io/kieraneglin/pinchflat:latest

# Docker Compose health check
services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8945/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 3
```

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

### Custom yt-dlp Configuration Files

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Demonstrates how to apply custom yt-dlp options using configuration files at different scopes: base, media profile, source, and media item. The precedence order ensures specific configurations override general ones.

```text
# Configuration files location: /config/extras/yt-dlp-configs/

# Base config applied to ALL downloads
# File: base-config.txt
--concurrent-fragments 4
--retries 10
--fragment-retries 10

# Media Profile specific config
# File: media-profile-{id}-config.txt
--format bestvideo[height<=1080]+bestaudio/best[height<=1080]
--merge-output-format mp4

# Source specific config
# File: source-{id}-config.txt
--match-filter duration>60
--download-archive /config/archive.txt

# Media Item specific config
# File: media-item-{id}-config.txt
--format bestaudio[ext=m4a]

# Precedence order (highest to lowest):
# Media Item > Source > Media Profile > Base Config
```

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

### Podman Deployment for Pinchflat (Rootless)

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This command illustrates how to run Pinchflat using Podman with user namespace support for rootless execution. It includes security options, user mapping, environment variables, port mapping, and volume mounts.

```bash
podman run \
  --security-opt label=disable \
  --userns=keep-id --user=$UID \
  -e TZ=America/Los_Angeles \
  -p 8945:8945 \
  -v /host/path/to/config:/config:rw \
  -v /host/path/to/downloads:/downloads:rw \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Docker Run Command for Pinchflat

Source: https://github.com/kieraneglin/pinchflat/blob/master/README.md

This command demonstrates how to run the Pinchflat Docker container directly. It includes setting the timezone, mapping ports, and mounting volumes for persistent storage of configuration and downloaded media.

```bash
# Be sure to replace /host/path/to/config and /host/path/to/downloads below with
# the paths to the directories you created in step 1
# Be sure to replace America/New_York with your local timezone
docker run \
  -e TZ=America/New_York \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Podman Run Command for Pinchflat

Source: https://github.com/kieraneglin/pinchflat/blob/master/README.md

This command shows how to run Pinchflat using Podman, with specific security options for user namespace management. It maps ports and volumes, ensuring file access uses the current user's UID/GID.

```bash
podman run \
  --security-opt label=disable \
  --userns=keep-id --user=$UID \
  -e TZ=America/Los_Angeles \
  -p 8945:8945 \
  -v /host/path/to/config:/config:rw \
  -v /host/path/to/downloads/:/downloads:rw \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Custom Lifecycle Scripts for Media Events (Bash)

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This Bash script demonstrates how to execute custom logic at various media event triggers within Pinchflat, such as application initialization, pre-download checks, post-download actions, and media deletion. It uses `jq` to parse event data.

```bash
#!/bin/bash
# File: /config/extras/user-scripts/lifecycle

EVENT_TYPE=$1
EVENT_DATA=$2

case $EVENT_TYPE in
  "app_init")
    echo "Application started"
    # Install yt-dlp plugins or perform setup tasks
    ;;
  "media_pre_download")
    # Return non-zero to prevent download
    TITLE=$(echo $EVENT_DATA | jq -r '.title')
    if [[ "$TITLE" == *"blocked"* ]]; then
      echo "Blocking download of: $TITLE"
      exit 1  # Prevents download
    fi
    exit 0
    ;;
  "media_downloaded")
    FILEPATH=$(echo $EVENT_DATA | jq -r '.media_filepath')
    TITLE=$(echo $EVENT_DATA | jq -r '.title')
    echo "Downloaded: $TITLE to $FILEPATH"
    # Notify external services, move files, etc.
    ;;
  "media_deleted")
    ID=$(echo $EVENT_DATA | jq -r '.id')
    echo "Media item deleted: $ID"
    ;;
esac
```

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

### Manage Pinchflat Docker Images and Containers

Source: https://github.com/kieraneglin/pinchflat/wiki/Installation

Commands for pulling the latest image, building locally, and executing the container via the Docker CLI.

```bash
docker pull ghcr.io/kieraneglin/pinchflat:latest
docker build . --file selfhosted.Dockerfile -t ghcr.io/kieraneglin/pinchflat:latest
docker run \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Docker Run Command with Basic Auth for Pinchflat

Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds

This command configures Pinchflat with HTTP Basic Authentication by setting the BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD environment variables. It maps ports and volumes for configuration and downloads.

```bash
docker run \
  -p 8945:8945 \
  -v /host/path/to/config:/config \
  -v /host/path/to/downloads:/downloads \
  -e BASIC_AUTH_USERNAME=admin \
  -e BASIC_AUTH_PASSWORD=CHANGEME \
  ghcr.io/kieraneglin/pinchflat:latest
```

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

### Configure Source Filtering Options

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Details on configuring various filters within Pinchflat to control which videos are downloaded from a source. This includes filtering by title regex, download cutoff date, duration, and behavior for shorts and livestreams.

```text
# Title Filter Regex (Advanced Mode)
# Only download videos with titles matching the regex
title_filter_regex: "(?i)(tutorial|guide|how.to)"

# Download Cutoff Date
# Only download videos uploaded after this date
download_cutoff_date: "2024-01-01"

# Duration Filters (Advanced Mode)
# Set minimum and maximum video duration in seconds
min_duration_seconds: 60      # Skip videos under 1 minute
max_duration_seconds: 3600    # Skip videos over 1 hour

# Shorts and Livestream Behaviour (in Media Profile)
# Options: include, exclude, only
shorts_behaviour: "exclude"      # Skip YouTube Shorts
livestream_behaviour: "include"  # Include livestreams

# Test filters before downloading:
# 1. Disable "Download Media" in Source settings
# 2. Wait for indexing to complete
# 3. Check "Pending Media" tab to verify filter results
# 4. Re-enable "Download Media" when satisfied
```

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

### POST /media_profiles

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Create a new media profile for organizing downloads.

```APIDOC
## POST /media_profiles

### Description
Creates a new media profile with custom output path templates.

### Method
POST

### Endpoint
/media_profiles

### Request Body
- **name** (string) - Required - Name of the profile
- **template** (string) - Required - Liquid-style output path template

### Request Example
{
  "name": "Plex Profile",
  "template": "/shows/{{ source_custom_name }}/{{ title }}.{{ ext }}"
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the created profile
```

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

### Deploy Pinchflat with Docker Compose

Source: https://github.com/kieraneglin/pinchflat/wiki/Installation

A standard Docker Compose configuration for running Pinchflat. It maps host directories for configuration and downloads to the container.

```yaml
version: '3'
services:
  pinchflat:
    image: keglin/pinchflat:latest
    ports:
      - '8945:8945'
    volumes:
      - /host/path/to/config:/config
      - /host/path/to/downloads:/downloads
```

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

### Pinchflat API Routes for Source and Media Management

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This section details the RESTful API endpoints provided by Pinchflat for managing media sources and individual media items. These include operations for downloading, re-downloading, indexing, refreshing metadata, syncing files, and performing actions on specific media items.

```http
POST   /sources/:source_id/force_download_pending   # Download all pending media
POST   /sources/:source_id/force_redownload         # Re-download existing media
POST   /sources/:source_id/force_index              # Force full re-index
POST   /sources/:source_id/force_metadata_refresh   # Refresh source metadata
POST   /sources/:source_id/sync_files_on_disk       # Sync database with files
GET    /sources/:source_id/media/:id           # Show media item
PUT    /sources/:source_id/media/:id           # Update media item
DELETE /sources/:source_id/media/:id           # Delete media item
POST   /sources/:source_id/media/:id/force_download  # Force download
```

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

### Upgrade Heroicons using Curl and Tar

Source: https://github.com/kieraneglin/pinchflat/blob/master/assets/vendor/heroicons/UPGRADE.md

This script downloads a specified version of Heroicons from GitHub using curl, then extracts the optimized icons using tar. It requires the HERO_VSN environment variable to be set to the desired version. The output is the optimized icons, ready for use.

```bash
export HERO_VSN="2.0.16" ; \
  curl -L "https://github.com/tailwindlabs/heroicons/archive/refs/tags/v${HERO_VSN}.tar.gz" | \
  tar -xvz --strip-components=1 heroicons-${HERO_VSN}/optimized
```

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

### Configure YouTube API Key

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Guidance on configuring a YouTube Data API key for Pinchflat to enhance Fast Indexing. It outlines the steps for creating and restricting an API key in Google Cloud and verifying its functionality through application logs.

```text
# 1. Create a Google Cloud project at https://console.cloud.google.com
# 2. Enable "YouTube Data API v3" for the project
# 3. Create an API key and restrict it to YouTube Data API v3
# 4. Add the key in Pinchflat Settings page

# API key supports approximately 65 sources with 10-minute polling interval
# Falls back to RSS if API quota is exceeded

# Verify API key works by checking logs for:
# "Fetching recent media IDs from YouTube API"
# If you see "Failed to fetch YouTube API", check your API key configuration
```

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

### Custom Lifecycle Scripts for Media Events (Python)

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This Python script serves as a placeholder for implementing custom logic to be executed during various media event triggers within Pinchflat. It can be used for tasks like pre-download validation, post-download processing, or handling media deletion events.

```python
#!/bin/python3

```

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

### Handle Pinchflat Lifecycle Events with Bash

Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts

A Bash script to process Pinchflat lifecycle events. It receives the event type and JSON data as arguments, allowing for custom actions based on the event. Requires 'jq' for JSON parsing.

```bash
#!/bin/bash

EVENT_TYPE=$1
EVENT_DATA=$2

echo "Script called with event type '$EVENT_TYPE' and a record ID #$(echo $EVENT_DATA | jq -r '.id')"
```

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

### Configure Media Retention Policy

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Instructions for setting up automatic deletion of downloaded media in Pinchflat based on a retention period. It details how to configure this setting per source and explains the behavior of the deletion process.

```text
# Set retention per Source in the web UI:
# Source Settings > Retention Period (days)

# Behavior:
# - Retention is relative to download date, not upload date
# - Deletion runs once daily
# - Individual media can be protected via "Prevent Automatic Deletion" flag

# To filter by upload date instead, use "Download Cutoff Date" source setting
# Format: YYYY-MM-DD (only downloads media uploaded after this date)
```

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

### Pinchflat Web Application RESTful Routes

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This outlines the core RESTful web routes exposed by Pinchflat for managing media profiles and sources. These routes are protected by basic authentication if configured.

```text
# Core Web Routes (protected by basic auth when configured)
GET    /                           # Home page
GET    /media_profiles             # List media profiles
POST   /media_profiles             # Create media profile
GET    /media_profiles/:id         # Show media profile
PUT    /media_profiles/:id         # Update media profile
DELETE /media_profiles/:id         # Delete media profile

GET    /sources                    # List sources
POST   /sources                    # Create source
GET    /sources/:id                # Show source details
PUT    /sources/:id                # Update source
DELETE /sources/:id                # Delete source (with optional file deletion)
```

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

### Handle Pinchflat Lifecycle Events with Python

Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts

A Python 3 script to handle Pinchflat lifecycle events. It parses the event type and JSON data passed as command-line arguments, enabling custom logic for different events. Uses the built-in 'json' library.

```python
#!/bin/python3

import sys
import json

event_type = sys.argv[1]
event_data = json.loads(sys.argv[2])

print("Script called with event type '{}' and an ID #{}".format(event_type, event_data["id"]))
```

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

### Test Lifecycle Script via CLI

Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts

Command to manually trigger the lifecycle script within the Pinchflat container using a previously captured JSON payload.

```bash
/app/tmp/extras/user-scripts/lifecycle media_downloaded "$(cat /tmp/example.json)"
```

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

### Docker Compose Configuration for Pinchflat

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This Docker Compose configuration defines the Pinchflat service, including its image, environment variables for authentication and feed exposure, port mapping, and volume mounts for persistent storage.

```yaml
version: '3' 
services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    environment:
      - TZ=America/New_York
      - BASIC_AUTH_USERNAME=admin
      - BASIC_AUTH_PASSWORD=secretpassword
      - EXPOSE_FEED_ENDPOINTS=yes
    ports:
      - '8945:8945'
    volumes:
      - /host/path/to/config:/config
      - /host/path/to/downloads:/downloads
```

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

### Manually update yt-dlp in Docker

Source: https://github.com/kieraneglin/pinchflat/wiki/Frequently-Asked-Questions

Commands to manually update the yt-dlp binary within the Pinchflat Docker container. This requires accessing the container shell as root and executing the update command.

```bash
docker exec -it --user root pinchflat bash
yt-dlp -U
```

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

### Handle Media Events with Python Script

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

A Python script to process media download events. It parses event type and data from command-line arguments, printing details for 'media_downloaded' events and enforcing duration limits for 'media_pre_download' events by exiting with a non-zero status code.

```python
import sys
import json

event_type = sys.argv[1]
event_data = json.loads(sys.argv[2])

if event_type == "media_downloaded":
    print(f"Downloaded: {event_data['title']}")
    print(f"File path: {event_data['media_filepath']}")
    print(f"Source: {event_data['source']['custom_name']}")
    print(f"Profile: {event_data['source']['media_profile']['name']}")
elif event_type == "media_pre_download":
    # Reject short videos
    if event_data.get('duration_seconds', 0) < 60:
        print("Rejecting video shorter than 60 seconds")
        sys.exit(1)  # Non-zero prevents download
```

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

### Source Actions API

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Endpoints for managing source media downloads, indexing, and metadata refresh.

```APIDOC
## POST /sources/:source_id/force_download_pending

### Description
Download all pending media for a given source.

### Method
POST

### Endpoint
/sources/:source_id/force_download_pending

### Parameters
#### Path Parameters
- **source_id** (string) - Required - The ID of the source.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Pending media download initiated."
}
```

## POST /sources/:source_id/force_redownload

### Description
Re-download existing media for a given source.

### Method
POST

### Endpoint
/sources/:source_id/force_redownload

### Parameters
#### Path Parameters
- **source_id** (string) - Required - The ID of the source.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Existing media re-download initiated."
}
```

## POST /sources/:source_id/force_index

### Description
Force a full re-index of a given source.

### Method
POST

### Endpoint
/sources/:source_id/force_index

### Parameters
#### Path Parameters
- **source_id** (string) - Required - The ID of the source.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Full re-index initiated."
}
```

## POST /sources/:source_id/force_metadata_refresh

### Description
Refresh the metadata for a given source.

### Method
POST

### Endpoint
/sources/:source_id/force_metadata_refresh

### Parameters
#### Path Parameters
- **source_id** (string) - Required - The ID of the source.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Metadata refresh initiated."
}
```

## POST /sources/:source_id/sync_files_on_disk

### Description
Sync the database with the files on disk for a given source.

### Method
POST

### Endpoint
/sources/:source_id/sync_files_on_disk

### Parameters
#### Path Parameters
- **source_id** (string) - Required - The ID of the source.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "File synchronization initiated."
}
```
```

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

### Configure Prometheus Metrics and Grafana

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Configuration for enabling Prometheus metrics collection in Pinchflat via Docker Compose and setting up Prometheus to scrape these metrics. It also lists available Grafana dashboard JSON files for import.

```yaml
# Enable Prometheus in Docker Compose
services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    environment:
      - ENABLE_PROMETHEUS=true
    ports:
      - '8945:8945'

# Prometheus scrape configuration (prometheus.yml)
scrape_configs:
  - job_name: pinchflat
    static_configs:
      - targets: ['pinchflat-server:8945']

# Available Grafana dashboards (import from priv/grafana/):
# - application.json     # Application metrics
# - beam.json           # Erlang VM metrics
# - phoenix.json        # Phoenix framework metrics
# - ecto.json           # Database metrics
# - oban.json           # Job queue metrics
# - phoenix_live_view.json  # LiveView metrics
```

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

### Utility Routes API

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

Endpoints for searching media, managing application settings, and retrieving application information.

```APIDOC
## GET /search

### Description
Search for media items.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term.

### Response
#### Success Response (200)
- **results** (array) - A list of matching media items.

#### Response Example
```json
{
  "results": [
    {
      "id": "media_id_123",
      "title": "Example Media"
    }
  ]
}
```

## GET /settings

### Description
Get the current application settings.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **settings** (object) - The application settings.

#### Response Example
```json
{
  "settings": {
    "download_directory": "/downloads"
  }
}
```

## PUT /settings

### Description
Update application settings.

### Method
PUT

### Endpoint
/settings

### Parameters
#### Request Body
- **settings** (object) - Required - The settings to update.

### Request Example
```json
{
  "settings": {
    "download_directory": "/new/downloads"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Settings updated successfully."
}
```

## GET /app_info

### Description
Get information about the application.

### Method
GET

### Endpoint
/app_info

### Response
#### Success Response (200)
- **app_info** (object) - Application information.

#### Response Example
```json
{
  "app_info": {
    "version": "1.0.0",
    "name": "Pinchflat"
  }
}
```

## GET /download_logs

### Description
Get the application download logs.

### Method
GET

### Endpoint
/download_logs

### Response
#### Success Response (200)
- **logs** (string) - The content of the download logs.

## GET /healthcheck

### Description
Health check endpoint for the application. No authentication required.

### Method
GET

### Endpoint
/healthcheck

### Response
#### Success Response (200)
- **status** (string) - The health status of the application.

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

## GET /dev/dashboard

### Description
Access the Phoenix LiveDashboard for development purposes.

### Method
GET

### Endpoint
/dev/dashboard

### Response
#### Success Response (200)
- **dashboard** (html) - The LiveDashboard interface.

```

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

### Pinchflat Public Feed and Utility API Routes

Source: https://context7.com/kieraneglin/pinchflat/llms.txt

This section covers API endpoints for accessing public feeds (RSS, OPML, images) and utility functions such as search, settings management, application information, log downloads, and health checks. Some feed endpoints can be optionally unprotected.

```http
GET    /sources/:uuid/feed         # RSS feed XML
GET    /sources/:uuid/feed_image   # Feed cover image
GET    /media/:uuid/stream         # Stream media file
GET    /media/:uuid/episode_image  # Episode thumbnail
GET    /sources/opml               # OPML feed list
GET    /search                     # Search media
GET    /settings                   # Application settings
PUT    /settings                   # Update settings
GET    /app_info                   # Application information
GET    /download_logs              # Download application logs
GET    /healthcheck                # Health check endpoint (no auth)
GET    /dev/dashboard              # Phoenix LiveDashboard
```

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

### NGINX Location Block for Feed Endpoints

Source: https://github.com/kieraneglin/pinchflat/wiki/Podcast-RSS-Feeds

This NGINX configuration block specifies which URL patterns should bypass authentication and be directly proxied to the Pinchflat server. It's designed to allow podcast apps to access feed XML, images, and media streams.

```nginx
location ~* (^/sources/[^/]+/feed(_image)?|^/media/[^/]+/(stream|episode_image))(\\.[a-zA-Z0-9]+)?$ {
    # You may want to add more here depending on your setup
    proxy_pass $forward_scheme://$server:$port;
}
```

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

### Capture Lifecycle Event Data to File

Source: https://github.com/kieraneglin/pinchflat/wiki/[Advanced]-Custom-lifecycle-scripts

A Bash script template used to capture event data passed to the lifecycle hook. It writes the event payload to a temporary JSON file for inspection and debugging.

```bash
#!/bin/bash

EVENT_TYPE=$1
EVENT_DATA=$2

echo $EVENT_DATA >/tmp/example.json
echo "Data for '$EVENT_TYPE' saved to /tmp/example.json"
```