pinchflat: init at v2025.1.14

[charludo]

Pinchflat is a self-hosted app for downloading YouTube content built using yt-dlp. 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 also tags media in a Plex, Jellyfin, and Kodi compatible manner, and integrates with Sponsorblock.

This PR adds the package itself, as well as a NixOS module for configuring a server install of pinchflat.
This resolves #351127.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[ob7]

I enabled the pinchflat service and it seems to work well, I'm archiving a channel now. However, I haven't reviewed the code, just testing if it works or not.

I do wonder if there is a way to automate the secrets file part, as that takes some additional manual set up that isn't clear if you never used pinchflat before. Effectively I needed to install elixir, and generate the key by running an interactive iex session and running :crypto.strong_rand_bytes(64) |> Base.encode64() |> binary_part(0, 64) then saving the output to the secrets file. Just a suggestion if possible for usability is to generate the secrets file if user doesn't supply one. Just a personal suggestion, not something that would effect merging AFAIK.

Other observations are the systemd log for the service is very verbose, and perhaps this is due to pinchflat itself I don't know. I do notice you have LOG_LEVEL = "info" as an example one could use for extraConfig. Perhaps enable a less verbose log level by default?

Again just my observations from an initial install/setup user perspective, not a review of the code or service implementation etc. In a nutshell, it seems to install and function as intended, nice work!

One other suggestion is perhaps note that the services.pinchflat.port is where user accesses the web gui, ie localhost:8945 by default, it may not be clear in the docs that that is where the user accesses pinchflat from.

This is a pretty cool tool though, nice job. Another idea is make it so channels to archive can be supplied in the configuration.nix, similar to how the ollama service allows ppl to declare what models they want downloaded by passing them to services.ollama.loadModels.

[ob7]

Note I ran into an error when setting extraConfig:

error: attribute 'toString' missing
at /home/nixos/nixpkgs/nixos/modules/services/misc/pinchflat.nix:131:70:
   130|           "PHX_SERVER=true"
   131|         ] ++ lib.attrValues (lib.mapAttrs (name: value: name + "=" + lib.toString value) cfg.extraConfig);
      |                                                                      ^
   132|         EnvironmentFile = lib.optional (cfg.secretsFile != null) cfg.secretsFile;

I changed the value via

services.pinchflat.extraConfig = {
  LOG_LEVEL = "info";
}

as suggested in man configuration.nix

However I was able to make this work by modifying nixos/modules/services/misc/pinchflat.nix line 131
from

] ++ lib.attrValues (lib.mapAttrs (name: value: name + "=" + lib.toString value) cfg.extraConfig); 

to

] ++ lib.attrValues (lib.mapAttrs (name: value: name + "=" + builtins.toString value) cfg.extraConfig); 

[ob7]

Another observation, services.pinchflat.mediaDir and services.pinchflat.dataDir depend on each other. If one changes dataDir without changing mediaDir, downloads break as default mediaDir is a subdirectory of dataDir. This is only apparent if one is checking systemd logs, as everything appears to be running fine in GUI other than the lack of growth in downloads/library size. Maybe just set it to $dataDir/media by default?... ie:

config = mkIf cfg.enable {
  services.pinchflat.mediaDir = lib.mkDefault "${cfg.dataDir}/media";

and user can still change the value if they please.

As it currently stands, if user changes dataDir and does not update mediaDir, mediaDir will no longer exist as a valid path, as the service does not create /var/lib/pinchflat/media in the absense of /var/lib/pinchflat.

[charludo]

However I was able to make this work by modifying nixos/modules/services/misc/pinchflat.nix line 131 from

] ++ lib.attrValues (lib.mapAttrs (name: value: name + "=" + lib.toString value) cfg.extraConfig); 

to

] ++ lib.attrValues (lib.mapAttrs (name: value: name + "=" + builtins.toString value) cfg.extraConfig); 

Oops, yes, thank you for catching this!

[charludo]

Another observation, services.pinchflat.mediaDir and services.pinchflat.dataDir depend on each other. If one changes dataDir without changing mediaDir, downloads break as default mediaDir is a subdirectory of dataDir. This is only apparent if one is checking systemd logs, as everything appears to be running fine in GUI other than the lack of growth in downloads/library size. Maybe just set it to $dataDir/media by default?.

Absolutely, good call. Should have done that from the get-go.

[charludo]

I do wonder if there is a way to automate the secrets file part, as that takes some additional manual set up that isn't clear if you never used pinchflat before. Effectively I needed to install elixir, and generate the key by running an interactive iex session and running :crypto.strong_rand_bytes(64) |> Base.encode64() |> binary_part(0, 64) then saving the output to the secrets file. Just a suggestion if possible for usability is to generate the secrets file if user doesn't supply one. Just a personal suggestion, not something that would effect merging AFAIK.

I will add a note in the docs for the option. You can use any string longer than 64 bytes, it doesn't appear to matter if they were generated like you / the docs describe.

But I also just double-checked and it looks like adding a RUN_CONTEXT=selfhosted env var would make pinchflat not check for a user-supplied secret, so I'll add an option for that.

Other observations are the systemd log for the service is very verbose, and perhaps this is due to pinchflat itself I don't know. I do notice you have LOG_LEVEL = "info" as an example one could use for extraConfig. Perhaps enable a less verbose log level by default?

Agreed, it's very verbose.

Another idea is make it so channels to archive can be supplied in the configuration.nix, similar to how the ollama service allows ppl to declare what models they want downloaded by passing them to services.ollama.loadModels.

I am afraid this one is not possible. The reason this can be done for e.g. ollama is that setting a my:modelName there simply executes ollama pull my:modelName on restart of the service, if that model is missing.
The extraConfig option added in this PR lets you set any and all of Pinchflat's settings, but pre-configuring the channels to download simply isn't one of them.

I checked the pinchflat repo, and it does not appear that such a feature request has been made in the past. But I honestly don't know if it even could be added at a reasonable amount of effort. Because it's not just the channels you need to define, you also need to define all the other download settings, as well as a media profile with all of its settings. These then need to be read in to the database, as well as have a mechanism to detect when old entries were removed, and so on.

I think this is just one of those services - like sonarr, jellyfin,... - that are sufficiently complex to configure that a fully stateless solution isn't feasible :(

But hey, thanks for your review! 🎉 I'll push the requested changes shortly.