Nixflix Documentation

Maintainerr rules use a section-based logic system to determine how conditions are evaluated.

Logical Grouping

• Sections: Rules within the same section are ANDed together. Different sections are ORed together.
• Operators: Within a section, the first rule must have operator = null. Subsequent rules use:
  • operator = "0": AND the condition.
  • operator = "1": OR the condition.

Action Values (action)

The action field corresponds to RulePossibility values:

Servarr Action Values (arrAction)

Used to define what happens to the media (e.g., deletion or unmonitoring):

To enable subtitle acquisition in Jellyfin using Nixflix, you must configure the nixflix.jellyfin.plugins section and define library-specific subtitleSettings.

This setup requires secrets for OpenSubtitles credentials managed via sops. You can enable specific plugins like subbuzz, Open Subtitles, and Subtitle Extract to handle different aspects of subtitle fetching and extraction.

{config, ...}: {
  sops.secrets."opensubtitles-com/api-key" = { };
  sops.secrets."opensubtitles-com/password" = { };

  nixflix.jellyfin = {
    enable = true;

    plugins = {
      subbuzz = {
        enable = true;
        config = {
          OpenSubUserName = "kiriwalawren";
          OpenSubPassword._secret = config.sops.secrets."opensubtitles-com/password".path;
          OpenSubApiKey._secret = config.sops.secrets."opensubtitles-com/api-key".path;
          EnableOpenSubtitles = true;
          EnableYifySubtitles = true;
          Cache.SubLifeInMinutes = "Always";
        };
      };

      "Open Subtitles" = {
        enable = true;
        config = {
          Username = "kiriwalawren";
          Password._secret = config.sops.secrets."opensubtitles-com/password".path;
        };
      };

      "Subtitle Extract" = {
        enable = true;
        config.ExtractionDuringLibraryScan = true;
      };
    };

    libraries = {
      Shows = { 
        disabledSubtitleFetchers = ["subbuzz"];
        subtitleFetcherOrder = ["subbuzz" "Open Subtitles"];
        subtitleDownloadLanguages = ["eng" "spa"];
        saveSubtitlesWithMedia = true;
        allowEmbeddedSubtitles = "AllowAll";
        requirePerfectSubtitleMatch = true;
        skipSubtitlesIfAudioTrackMatches = false;
        skipSubtitlesIfEmbeddedsubtitlesPresent = true;
      };
      # Repeat for Anime, Movies, etc.
    };
  };
}

Because Maintainerr rules are complex, the recommended workflow is to design them in the Maintainerr UI first, then export the JSON via the API and declare them in your Nix configuration.

Workflow

1. Enable Maintainerr: Ensure the service is running.
2. Design in UI: Open the Maintainerr UI and create rule groups on the Rules page. Configure libraries, data types, collection settings, and rule conditions.
3. Retrieve JSON: Use the API to get the resulting configuration:

   curl -s http://localhost:6246/api/rules | jq .

4. Convert to Nix: Convert the JSON to a Nix attribute set and add it to nixflix.maintainerr.rules.
5. Rebuild: The maintainerr-rules service will sync the state, creating or updating declared groups and deleting those no longer listed.

Field Mapping & Conversion Notes

When converting API JSON to Nix, note these specific mapping requirements:

• library: Use the human-readable title (e.g., "Movies") instead of the libraryId GUID. The service resolves this via GET /api/media-server/libraries.
• radarrServerName / sonarrServerName: Use the server name as configured in nixflix.maintainerr.settings.radarr or nixflix.maintainerr.settings.sonarr (e.g., "Radarr", "Sonarr Anime"), not the integer ID.
• arrAction: Map this from collection.arrAction in the API response.
• listExclusions / forceSeerr: Map these from collection.listExclusions and collection.forceSeerr.
• rules: The API returns a ruleJson string for each rule. You must parse this string and use its fields directly in your Nix list.

To easily inspect the parsed rule logic, use this command:

curl -s http://localhost:6246/api/rules | jq '.[0].rules[].ruleJson | fromjson'

nixflix.maintainerr.rules = [
  {
    name = "Movies To Delete";
    description = "Deletes movies that have been watched or have been around for too long.";
    library = "Movies";
    dataType = "movie";
    radarrServerName = "Radarr";
    collection = {
      deleteAfterDays = 14;
      overlayEnabled = true;
    };
    rules = [
      {
        customVal = { ruleTypeId = 3; value = "1"; };
        firstVal = [ 6 42 ];
        action = 2;
        section = 0;
      }
    ];
  }
];

To use Nixflix with Flakes, follow these two steps:

1. Enable Flakes: Ensure your NixOS configuration has experimental-features set to include flakes and nix-command.
2. Add as Input: Add nixflix to your inputs in flake.nix. It is recommended to use inputs.nixpkgs.follows = "nixpkgs"; to ensure version consistency.
3. Include in Modules: Add nixflix.nixosModules.default to your nixosSystem modules list.

### Enable Flakes
```nix
{
  nix.settings.experimental-features = ["nix-command" "flakes"];
}

Adding Nixflix to Your Flake

{
  description = "My NixOS Configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    nixflix = {
      url = "github:kiriwalawren/nixflix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    nixflix,
    ...
  }: {
    nixosConfigurations.yourhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        nixflix.nixosModules.default
      ];
    };
  };
}

To add a Jellyfin plugin, you must define both the plugin repository (where the manifest is located) and the plugin itself (the package and its configuration).

1. Define the Repository: Add the manifest URL and its hash to nixflix.jellyfin.system.pluginRepositories.
2. Define the Plugin: Add the plugin configuration to nixflix.jellyfin.plugins.<name>. You must provide a package using the nixflix.lib.jellyfinPlugins.fromRepo helper, which requires a version and a hash.
3. Configure Settings: Provide a config attribute set containing the plugin's specific settings.

let
  fromRepo = nixflix.lib.jellyfinPlugins.fromRepo;
in {
  nixflix.jellyfin = {
    system.pluginRepositories = {
      "Plugin Name" = {
        url = "https://example.com/manifest.json";
        hash = "sha256-<manifest-hash>";
        enabled = true;
      };
    };

    plugins."Plugin Name" = {
      package = fromRepo {
        version = "1.0.0";
        hash = "sha256-<unpacked-plugin-hash>";
      };
      config = {
        # Plugin specific settings go here
        SettingKey = "Value";
      };
    };
  };
}

Nixflix uses a Nix configuration pattern to orchestrate a full media stack. A standard setup includes core services (Sonarr, Radarr, Lidarr, Prowlarr), download clients (SABnzbd), media streaming (Jellyfin), and request management (Seerr).

Key configuration requirements:

• Secrets Management: Use sops.secrets to provide paths to sensitive data (API keys, passwords, VPN configs). Use the ._secret suffix in service configs to reference these paths.
• Storage: Define mediaDir for your media files and stateDir for service state.
• Reverse Proxy: You must choose either nginx or caddy. Do not enable both. Use addHostsEntries = true; if you want Nix to manage DNS entries for your services.
• VPN: Enable vpn to confine download services to a WireGuard network namespace. Use wgConfFile for the secret path and accessibleFrom to define your local network subnet (e.g., ["192.168.1.0/24"]).

{
  sops.secrets = {
    "sonarr/api_key" = {};
    # ... other secrets
  };

  nixflix = {
    enable = true;
    mediaDir = "/data/media";
    stateDir = "/data/.state";
    mediaUsers = ["myuser" ];

    nginx = {
      enable = true;
      addHostsEntries = true;
    };

    sonarr = {
      enable = true;
      config = {
        apiKey._secret = config.sops.secrets."sonarr/api_key".path;
        hostConfig.password._secret = config.sops.secrets."sonarr/password".path;
      };
    };
    # ... other services
  };
}