Pinchflat ngx Features

Pinchflat-ngx features

Pinchflat-ngx follows Pinchflat's core download model while adding controls for a more hands-on self-hosted workflow.

This page summarizes Pinchflat-ngx-specific behavior. Shared Pinchflat functionality remains documented in the Upstream Pinchflat wiki. How to install and operate the extra deployment options is in Installation, Environment Variables, Backups and Restore, and Diagnostics.

Sources

• Add one YouTube video as a source.
• Index playlists before choosing which items to download.
• Start, pause, stop, and delete sources from their management views.
• Route each source to a selected folder with template-aware paths.
• Create channel, playlist, and individual-video sources through the same source workflow.
• Choose Automatic, Channel, Playlist, or Video when creating a source. Automatic keeps existing URL detection. An explicit type is checked against the URL instead of being silently converted.
• Lock a source name or description so automated metadata refresh cannot overwrite it.
• Set a custom source poster from a local JPEG, PNG, or WebP upload or a public HTTP(S) URL.
• Configure source-specific media profiles, cookie behavior, YouTube player client, and download controls.
• Choose whether a source downloads public/unlisted media and members-only media. Private media is always blocked.
• Keep manually selected playlist items separate from automatically monitored media.

Source type

On Sources > New Source, set Source Type before the URL:

• Automatic inspects the URL the same way earlier Pinchflat-ngx releases did.
• Channel, Playlist, and Video require a URL that resolves to that type. A mismatch is rejected.
• Video sources are indexed once and Fast Indexing is disabled automatically.

The selected type is form state. The stored type is still the inspected collection type (channel, playlist, or video).

Metadata locks

On Edit Source, name and description refresh from fetched metadata unless you lock the field. A locked field can still be edited and saved on that form; the lock only blocks automated refreshes. Unlocking does not immediately restore the last fetched value.

Custom posters

On Edit Source, under Custom Source Poster:

• Upload a JPEG, PNG, or WebP file (decoded image, up to 10 MB), or
• Provide a public HTTP(S) URL. Redirects and private addresses are blocked.

The custom image is used in the source header and poster grid until you remove it. Fetched artwork returns after removal.

Availability policies

On Edit Source, under Downloading Options:

• Download Public and Unlisted Media applies to media yt-dlp reports as public or unlisted.
• Download Members-only Media applies to subscriber-only, premium-only, and media that requires authentication. Cookies are usually required; Pinchflat-ngx does not turn cookies on automatically.
• Private media is never downloaded.

Missing or unknown availability stays eligible so incomplete metadata does not stop indexing. Existing sources keep both policy toggles enabled unless you change them. Blocked items show as prevented by policy, not as ordinary download failures.

YouTube player client

YouTube Player Client on the source form overrides yt-dlp's player-client selection for that source. Default sends no override.

Some clients cannot be combined with cookies. The form warns when Web Creator needs All Operations cookies, and when Android, iOS, or TV Simply require cookies disabled. Save is rejected if that combination is invalid.

Source library views

On Sources, use Table or Poster grid. Filters, sort, and pagination stay shared. The grid choice is for the current page session; a full reload returns to the table.

Open a source to see counts for Downloaded, Pending, Failed, Prevented, and Skipped. Media lists on that page are grouped by upload year. The newest year starts expanded.

Interface

• Material 3 styling with an AMOLED base and shared semantic theme tokens.
• Responsive source, job, history, profile, and settings views.
• Collapsible desktop navigation and searchable settings.
• Live download-speed visibility in job and media tables.
• Home history tabs for pending, failed, active tasks, and downloaded media.
• Sort Home history by Upload Date, Indexed At, or Downloaded At. The active tab, filters, and pagination stay in place. The default order is unchanged until you pick a column.
• Paginated and sortable source management views, including the poster-grid layout above.
• Queue controls and diagnostics for inspecting active, scheduled, retryable, and failed work.
• Source and media status indicators for downloaded, pending, failed, unavailable, ignored, filtered, and policy-blocked items.

Channel Discovery

Find related channels from local metadata and existing subscriptions, then accept or dismiss them. Scanning is off until you enable it. See Channel Discovery.

Downloads

• Upload, paste, and inspect the shared cookies.txt file in Settings.
• Test a YouTube API key before using it for indexing.
• Distinguish unavailable, removed, ignored, filtered, and policy-blocked media.
• Review failed downloads and retry one item or a group.
• Keep a durable prevention or error reason: manual, policy, or error, plus whether a failure is transient or permanent.
• Use Retry Now for transient failures. Force Retry can attempt a permanent failure. On Home > Failed, filter by All, Transient, or Permanent failures.
• Treat YouTube rate limits and similar bot-challenge responses as transient, not as a permanent download block.
• Select stable, nightly, frozen-nightly, fallback, or pinned yt-dlp update policies.
• Maintain extra yt-dlp options through Settings.
• Configure source-specific cookie behavior where authentication requirements differ.
• Use media profiles for format, naming, subtitles, SponsorBlock, and related download choices.
• Preserve structured error text and queue state for diagnostics and retry workflows.
• Optionally complete downloads on local disk, then transfer finished files to the media library. See DOWNLOAD_STAGING_PATH in Environment Variables.
• Optionally send yt-dlp through a bgutil-compatible PO-token provider. See POT_PROVIDER_URL in Environment Variables and Diagnostics.

Operations and access

• Inspect, retry, cancel, and clear Oban jobs from queue diagnostics.
• Tune download, indexing, and metadata concurrency independently.
• Use structured logs for source creation, indexing, enqueueing, and skipped downloads.
• Protect browser routes with OIDC single sign-on.
• Use Basic Auth when configured for a self-hosted deployment without OIDC.
• Run published amd64 or arm64 images from ghcr.io/thebadfella/pinchflat-ngx.
• Use the SQLite latest image or the PostgreSQL latest-postgres image. See Installation.
• Create custom-format PostgreSQL dumps from Settings on the PostgreSQL image. See Backups and Restore.
• Review database, queue, source, storage, and PO-token provider health in Settings > Diagnostics.

Operational configuration is documented separately in Environment Variables, Diagnostics, Installation, and Upgrading and Rollback.

Database and deployment

The latest image uses SQLite and remains the default for existing installs. Keep /config on local disk when using SQLite.

The latest-postgres and <version>-postgres images use PostgreSQL. They create and migrate their own schema. They do not copy data from an existing SQLite database. Current PostgreSQL images expect PostgreSQL 18; PostgreSQL 16 volumes are not compatible as-is.

For backup and restore procedures, use Backups and Restore. Do not treat a copy of only the SQLite database file from a running WAL-mode deployment as a complete backup. PostgreSQL dumps are database state only; they do not include media files.

Roadmap

There are no open items on this page. The previous list (Home history sorting, availability policies, download reasons, player-client override, PO-token provider, local staging, metadata locks, custom posters, source type selection, source library views, Channel Discovery, PostgreSQL deployment, and PostgreSQL in-app backups) shipped in 2026.9.14.

Roadmap entries never implied a release date. New features should preserve existing behavior for current users unless a release note says otherwise.

For shared behavior such as media profiles, naming templates, podcast feeds, SponsorBlock, retention, and custom scripts, use the Upstream Pinchflat wiki.