^{logo by @hernandito}

Your next YouTube media manager

Table of contents:

What it does

Pinchflat is a self-hosted app for downloading YouTube content built using yt-dlp. It's designed to be lightweight, self-contained, and easy to use. You set up rules for how to download content from YouTube channels or playlists and it'll do the rest, periodically checking for new content. It's perfect for people who want to download content for use in with a media center app (Plex, Jellyfin, Kodi) or for those who want to archive media!

While you can download individual videos, Pinchflat is best suited for downloading content from channels or playlists. It's also not meant for consuming content in-app - Pinchflat downloads content to disk where you can then watch it with a media center app or VLC.

If it doesn't work for your use case, please make a feature request! You can also check out these great alternatives: Tube Archivist, ytdl-sub, and TubeSync

Features

Self-contained - just one Docker container with no external dependencies
Powerful naming system so content is stored where and how you want it
Easy-to-use web interface with presets to get you started right away
First-class support for media center apps like Plex, Jellyfin, and Kodi (docs)
Supports serving RSS feeds to your favourite podcast app (docs)
Automatically downloads new content from channels and playlists
- Uses a novel approach to download new content more quickly than other apps
Supports downloading audio content
Custom rules for handling YouTube Shorts and livestreams
Apprise support for notifications
Allows automatically redownloading new media after a set period
- This can help improve the download quality of new content or improve SponsorBlock tags
Optionally automatically delete old content (docs)
Advanced options like setting cutoff dates and filtering by title (docs)
Reliable hands-off operation
Can pass cookies to YouTube to download your private playlists (docs)
Sponsorblock integration
[Advanced] allows custom yt-dlp options (docs)
[Advanced] supports running custom scripts when after downloading/deleting media (alpha - docs)

Screenshots

Installation

Unraid

Simply search for Pinchflat in the Community Apps store!

Portainer

Important

See the note below about storing config on a network file share. It's preferred to store the config on a local disk if at all possible.

Docker Compose file:

version: '3'
services:
  pinchflat:
    image: ghcr.io/kieraneglin/pinchflat:latest
    environment:
      # Set the timezone to your local timezone
      - TZ=America/New_York
    ports:
      - '8945:8945'
    volumes:
      - /host/path/to/config:/config
      - /host/path/to/downloads:/downloads

Docker

Create two directories on your host machine: one for storing config and one for storing downloaded media. Make sure they're both writable by the user running the Docker container.
Prepare the docker image in one of the two ways below:
- From GHCR: docker pull ghcr.io/kieraneglin/pinchflat:latest
  - NOTE: also available on Docker Hub at keglin/pinchflat:latest
- Building locally: docker build . --file docker/selfhosted.Dockerfile -t ghcr.io/kieraneglin/pinchflat:latest
Run the container:

# 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

IMPORTANT: File permissions

You must ensure the host directories you've mounted are writable by the user running the Docker container. If you get a permission error follow the steps it suggests. See #106 for more.

Important

It's not recommended to run the container as root. Doing so can create permission issues if other apps need to work with the downloaded media.

ADVANCED: Storing Pinchflat config directory on a network share

As pointed out in #137, SQLite doesn't like being run in WAL mode on network shares. If you're running Pinchflat on a network share, you can disable WAL mode by setting the JOURNAL_MODE environment variable to delete. This will make Pinchflat run in rollback journal mode which is less performant but should work on network shares.

Caution

Changing this setting from WAL to delete on an existing Pinchflat instance could, conceivably, result in data loss. Only change this setting if you know what you're doing, why this is important, and are okay with possible data loss or DB corruption. Backup your database first!

If you change this setting and it works well for you, please leave a comment on #137! Doubly so if it does not work well.

Environment variables

Name	Required?	Default	Notes
`TZ`	No	`UTC`	Must follow IANA TZ format
`LOG_LEVEL`	No	`debug`	Can be set to `info` but `debug` is strongly recommended
`BASIC_AUTH_USERNAME`	No		See authentication docs
`BASIC_AUTH_PASSWORD`	No		See authentication docs
`EXPOSE_FEED_ENDPOINTS`	No	`false`	See RSS feed docs
`ENABLE_IPV6`	No	`false`	Setting to any non-blank value will enable IPv6
`JOURNAL_MODE`	No	`wal`	Set to `delete` if your config directory is stored on a network share (not recommended)
`TZ_DATA_DIR`	No	`/etc/elixir_tzdata_data`	The container path where the timezone database is stored
`BASE_ROUTE_PATH`	No	`/`	The base path for route generation. Useful when running behind certain reverse proxies, but prefix must be stripped.
`YT_DLP_WORKER_CONCURRENCY`	No	`2`	The number of concurrent workers that use `yt-dlp` per queue. Set to 1 if you're getting IP limited, otherwise don't touch it

EFF donations

Prior to 2024-05-10, a portion of all donations were given to the Electronic Frontier Foundation. Now, the app doesn't accept donations that go to me personally and instead directs you straight to the EFF. Here are some people that have generously donated.

The EFF defends your online liberties and backed youtube-dl when Google took them down.

Stability disclaimer

This software is in active development and anything can break at any time. I make no guarantees about the stability of this software, forward-compatibility of updates, or integrity (both related to and independent of Pinchflat).

License

See LICENSE file

License

akzov/pinchflat

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages