FAQ

Known limitations

Playlist support is inconsistent. Playlists may fail to download media, fail to fetch metadata, or exhibit unpredictable behavior depending on the deployment environment. If you need reliable downloads, use a channel URL instead of a playlist URL where possible. Playlist support is being actively investigated and improved.

ARM hardware (Raspberry Pi) is unsupported. Pinchfork will run on Pi hardware but there are known architecture-specific bugs — particularly around yt-dlp's source type auto-detection (channels being detected as playlists) and YouTube authentication behavior. These issues are low priority and may not be fixed in the near term. Use Pi deployments at your own risk.

---

How do I get media into Plex/Jellyfin/Kodi?

Note: Plex cannot read metadata from MKV files. Pinchfork saves files as MP4 by default — leave those settings alone.

There is no explicit media center integration. Instead, Pinchfork formats the filepath and adds metadata in a way that media center apps pick up automatically:

• Ensure Pinchfork's download directory is visible to your media center app.
• Create a new Media Profile with the Media Center preset. You can adjust the parent directory in Output path template but do not change the template structure itself.
• Configure your media center app to scan for TV shows in the directory above. In Plex, create a separate library for YouTube content (Settings → Manage → Libraries → Add Library) and enable Prefer local metadata and Use local assets in the Advanced library settings. Keeping YouTube content in its own library separate from regular TV shows is strongly recommended.

How do I download one-off videos?

Create an unlisted playlist on YouTube, add the videos you want, and add that playlist as a source in Pinchfork. You can create as many unlisted playlists as you like if you want different download rules for different videos.

What is indexing and how does it work?

Indexing scans a channel or playlist (a Source) for media. Pinchfork builds a list of all media belonging to a source regardless of your filters, then applies filters to decide what to download. This means changing filters doesn't require re-indexing.

For channels (not playlists), a full top-to-bottom index only happens once. After that, indexing only looks for new and recently changed media. Forcing a source to index from the UI triggers a full re-index.

How frequently should I index a source?

Indexing too aggressively can actually slow down how quickly you see new content, since the app limits concurrent yt-dlp operations to avoid IP rate limiting. Rough guidelines:

• Channel uploads multiple times a day → 1 or 3 hour interval
• Channel you want indexed as quickly as possible → enable Fast Indexing
• Channel whose videos risk deletion minutes after upload → enable Fast Indexing
• All other channels → base it on upload schedule (weekly uploads → daily index, monthly uploads → weekly index)

I just added a source — why isn't it indexing or downloading yet?

Pinchfork limits how many yt-dlp operations run simultaneously to avoid IP rate limiting from Google. A substantial queue delay is normal when adding many large sources at once. Initial downloads of large channels can take many hours; subsequent runs are much faster.

Check the logs for entries mentioning yt-dlp being called — if those are appearing, the app is working normally.

My source isn't indexing on the schedule I set

This is expected. The next index is only scheduled after the current one completes, so a 60-minute interval on a source that takes 30 minutes to index will actually run every 90 minutes. Multiple sources also get staggered to avoid simultaneous yt-dlp calls. This is intentional.

What is Fast Indexing?

Fast Indexing uses an RSS feed (or YouTube API if configured) to check for new videos frequently, rather than a full yt-dlp scan on a schedule. It can be hundreds of times faster than normal indexing but may miss videos in edge cases (e.g. many uploads within a few minutes of each other). A normal full index still runs monthly as a catch-up.

Fast Indexing is not recommended for playlists. Configure an API key in Settings for the fastest and most reliable experience — see Generating a YouTube API key.

Will Pinchfork delete videos removed from the source or filtered out?

No. There is no logic to delete files when videos are removed from a source or when you change filters. You can set a retention period per source to automatically delete old downloads — see Automatically Delete Media.

I only want certain videos from a source — how do I filter?

• Small number of specific videos: create an unlisted playlist with just those videos and use that as the source.
• Title-based filtering: enable Advanced Mode on the source and use the Title Filter Regex field.
• Date-based filtering: set a Download Cutoff Date on the source — only videos uploaded after that date will be downloaded.
• Duration filtering: enable Advanced Mode and use the minimum/maximum duration fields.

How can I test filtering before downloading?

Disable Download Media on the source. The source will still index, and you can check the Pending Media tab to verify only the expected media is queued. The page does not update live — reload to see the latest state. Once satisfied, re-enable Download Media.

Can I import my existing library?

This is not currently supported.

How do I update yt-dlp?

Pinchfork checks for yt-dlp updates daily. The YT_DLP_VERSION environment variable controls update behavior:

• stable (default) — updates to the latest stable release
• nightly — updates to the latest nightly build
• master — updates to the latest master build
• pinned or none — disables automatic updates
• A specific version string like 2025.12.08 — pins to that exact version

To update manually: docker exec -it --user root pinchfork yt-dlp -U

Note: there is no need to restart the container after a manual yt-dlp update.