Skip to content

Configuration Differences

Jump to bottom
o51r15 edited this page Jun 18, 2026 · 1 revision

This page covers the differences between Pinchfork and the upstream Pinchflat project. If you're running upstream Pinchflat and considering a migration, or if you're referencing the upstream wiki for documentation on base features, this is what's changed.

Base features — sources, media profiles, Jellyfin/Plex/Kodi integration, SponsorBlock, RSS feeds, Apprise, lifecycle scripts, custom yt-dlp options — are unchanged. Only the backend infrastructure and the fork-specific additions documented here differ.

Environment variables

Added

Variable Default Notes
DATABASE_URL — Required. Postgres connection string: ecto://user:pass@host/db. Replaces the upstream DATABASE_PATH.
POOL_SIZE 10 Postgres connection pool size.
YT_DLP_VERSION stable Controls yt-dlp update behavior: stable, nightly, master, pinned/none to disable updates, or a specific version string like 2025.12.08.
LOCALTEMP — Set to true to enable local temp staging for network-mount downloads. See Local Temp Staging.

Removed

Variable Reason
DATABASE_PATH SQLite-only. Replaced by DATABASE_URL.
JOURNAL_MODE SQLite WAL workaround for network shares. Not applicable — use LOCALTEMP instead.

Database backend

Upstream Pinchflat uses SQLite with Oban.Engines.Lite. Pinchfork replaces both:

  • SQLite → PostgreSQL. Requires a Postgres sidecar container (see Installation).
  • Oban.Engines.Lite → Oban.Engines.Basic. The Postgres-native Oban engine resolves write contention and crash loops that occur under load with the SQLite engine.

All SQLite-specific query syntax has been rewritten for Postgres (IFNULL → COALESCE, DATETIME() → interval arithmetic, regexp_like → ~, etc.). Full-text search is migrated from SQLite FTS5 to a Postgres tsvector column with a GIN index and trigger-maintained updates.

Oban Lifeline plugin

The Oban.Plugins.Lifeline plugin is enabled with a 30-minute rescue window. Any job that gets stuck in executing state after a crash or container restart is automatically moved back to retryable and re-queued. Upstream Pinchflat does not include this plugin.

Source configuration additions

Each source has two new fields not present in upstream:

  • Download public videos (default: on) — controls whether videos with availability: public are downloaded.
  • Download members-only videos (default: off) — controls whether subscriber_only, premium_only, and needs_auth videos are downloaded. Requires cookies to be configured for the source.

Unlisted and private videos are always skipped regardless of these settings.

A new Video Client dropdown controls which yt-dlp player client is used per source. Cookie-incompatible client choices are blocked at save time if the source also has cookies or members-only downloads enabled. See SABR Bypass and PO Tokens.

Media item fields additions

Three new fields on media items not present in upstream:

  • availability — captured from yt-dlp at index time. Values: public, unlisted, subscriber_only, premium_only, needs_auth, private.
  • error_type — set during download failures. Values: transient (will retry), permanent (sets prevent_download: true, stops retrying). Permanent failures include: video unavailable, removed, private, members-only, age-restricted, geo-blocked, and premium-only errors.
  • download_prevented_reason — records why a download was prevented: permanent_error, manual, user_script, or a policy reason (policy_public / policy_members / policy_other). Surfaced on the media-item page.

yt-dlp version management

The YT_DLP_VERSION environment variable controls how yt-dlp updates itself on container startup. Upstream Pinchflat always updates to the latest stable release. Pinchfork lets you pin to a specific version or disable updates entirely — useful for stability on production setups.

YouTube API key tester

The Settings page includes a one-click button to validate your YouTube API key against a known public playlist. The result (checkmark or error with reason) is shown inline for a few seconds. Upstream Pinchflat requires checking container logs to verify an API key works.

PO Token support

The bgutil POT provider yt-dlp plugin is baked into the Pinchfork image. Adding the bgutil sidecar container is all that's required for PO tokens to work — no manual plugin download or volume mount. See SABR Bypass and PO Tokens.

Clone this wiki locally