Pinchflat

Last reviewed Sep 13, 2026 · 840 words

Pinchflat's whole reason to exist is that it writes files the way Jellyfin wants them. Subscribe to a channel, and it lands as Channel Name/Season 2026/Channel Name - s2026e0913 - Video Title.mp4 with an NFO file, a thumbnail and embedded metadata, so the videos show up in your media server as a series with episodes rather than a pile of files with 11-character IDs. A yt-dlp cron job can do the download; Pinchflat does the download plus the naming, the metadata, the scheduling and the retention, in a single container that needs about 512 MB of RAM.

What it is, and what it is competing with

Pinchflat is an Elixir application, AGPL-3.0, first released in 2024, at 5,295 GitHub stars. It wraps yt-dlp and drives it on a schedule against a list of sources you define. It is not a YouTube front end: you do not watch anything in Pinchflat, and it does not replace Invidious. It is the archiver that feeds the player.

Tube Archivist is the bigger project and the right pick if you want a browsable archive with search and an in-browser player of its own; the Elasticsearch requirement is the price. Pinchflat is the pick when Jellyfin or Plex is already your player and you just want channels to appear in it.

Compose and volume layout

services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    ports:
      - "8945:8945"
    volumes:
      - ./config:/config
      - /srv/media/youtube:/downloads
    restart: unless-stopped

Port 8945 is the web UI, /config holds the SQLite database and yt-dlp state, and /downloads is where the media goes. Point /downloads at a directory your media server also mounts, and keep it on the same filesystem as the rest of your library so moves are instant. There is no authentication on the UI by default; put it behind your reverse proxy with auth, or keep it on the LAN only. The Docker Compose patterns post covers the network layout I use for this class of app.

Media profiles decide everything

Before adding a source you create a media profile: output template, quality (1080p is the sensible default; 4K balloons disk fast), whether to embed subtitles and thumbnails, and whether to write NFO files. Then each source (a channel or playlist URL) gets a profile, a check interval and a retention rule. The two options I set on every profile are "download only videos newer than" so a subscription does not pull 800 back-catalogue videos on day one, and "keep the last N" for news-style channels that you never rewatch. Shorts and livestreams can be excluded per source, which you will want.

Adding the library to Jellyfin

Create a library of type Shows, point it at the download directory, and turn off the online metadata fetchers for that library so Jellyfin reads the NFO files Pinchflat wrote instead of trying to match a YouTube channel against TVDB. Each channel becomes a show, each year a season, each video an episode with its upload date and description. The Jellyfin setup guide has the library-configuration walkthrough if this is your first non-standard library. Plex works the same way with the "Personal Media Shows" agent.

Expect yt-dlp breakage, and plan for it

YouTube changes its player and anti-bot behaviour regularly, and every downloader on earth breaks for a few days when it does. Pinchflat bundles yt-dlp and updates it on container updates, so the fix is usually pulling a new image. Between fixes you will see failed downloads in the UI; they retry on the next scheduled run. If you archive a lot, expect rate limiting and occasional "sign in to confirm you're not a bot" errors; the project documents a cookies-file workaround using a throwaway Google account, which I would not do with a real one. Nothing here is Pinchflat's fault, but it is the reason a 2024-era project can feel less finished than it is.

What I'd do

Pinchflat on the media box, /downloads on the library disk, one profile at 1080p with NFO and thumbnails on, subscriptions set to "newer than 30 days" and a retention cap, Jellyfin Shows library with online metadata off. Pull a new image on a monthly schedule with the rest of the stack so yt-dlp stays current. That gives you a dozen channels showing up in Jellyfin as ordinary series, offline, ad-free, for zero extra infrastructure. Go to Tube Archivist only if you want a searchable archive with its own player and are willing to feed Elasticsearch for it.