fladder-nix/README.md

fladder — NixOS package

Unofficial NixOS package for Fladder, a cross-platform Jellyfin client built on Flutter.

Files

File	Purpose
package.nix	The derivation (import this into your config or flake)
default.nix	Convenience wrapper for nix-build local testing

Quick start

# Build and test locally
nix-build        # produces ./result/bin/fladder
./result/bin/fladder

Adding to your NixOS configuration

Standalone (no flake)

Copy this repo somewhere (e.g. ~/nixpkgs-overlays/fladder/) then in /etc/nixos/configuration.nix:

{ pkgs, ... }:
let
  fladder = pkgs.callPackage /path/to/this/repo/package.nix { };
in
{
  environment.systemPackages = [ fladder ];
}

As an overlay

# In configuration.nix or a separate overlay file:
nixpkgs.overlays = [
  (final: prev: {
    fladder = final.callPackage /path/to/this/repo/package.nix { };
  })
];

environment.systemPackages = [ pkgs.fladder ];

With flakes

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    fladder-pkg.url = "path:/path/to/this/repo";  # or a github: URL
  };

  outputs = { nixpkgs, fladder-pkg, ... }: {
    nixosConfigurations.mymachine = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            fladder-pkg.packages.x86_64-linux.fladder
          ];
        })
      ];
    };
  };
}

Package notes

AppImage type

Fladder distributes a Type 2 (SquashFS) AppImage built with appimage-builder. The derivation uses appimageTools.wrapType2, which:

1. Extracts the SquashFS filesystem.
2. Patches the ELF interpreter and RPATH to point at the Nix store.
3. Wraps the binary in a minimal FHS environment that provides the expected shared libraries.

Runtime dependencies

The main external shared libraries are:

Library	Why needed
libmpv	Media playback (video/audio streaming)
gtk3	Flutter Linux window embedder
libGL / mesa	Flutter Impeller / OpenGL compositor
libxkbcommon	Keyboard input
wayland	Native Wayland support (Flutter ≥ 3.13)
libpulseaudio	Audio (mpv PulseAudio / PipeWire-pulse back-end)
python3	libmpv in nixpkgs pulls in vapoursynth which dlopens libpython

The python3 dependency is subtle but important: without it the app exits immediately with libpython3.x.so.1.0: cannot open shared object file (upstream issue #724).

AMD GPU (RX 580)

The RX 580 uses the open-source amdgpu / radeonsi Mesa driver stack, which is included via pkgs.mesa in extraPkgs. No additional configuration should be required. If you encounter rendering artefacts, try:

# In configuration.nix
hardware.opengl.enable = true;  # (or hardware.graphics.enable on 25.05+)
hardware.opengl.driSupport = true;

X11 / Wayland

Fladder runs on both. Flutter will prefer Wayland when WAYLAND_DISPLAY is set; it falls back to X11/XWayland otherwise. No special flags are needed.

Updating to a new version

1. Update version in package.nix.
2. Update the hash field — get the new hash with:

   nix-prefetch-url --type sha256 \
     https://github.com/DonutWare/Fladder/releases/download/vNEW/Fladder-Linux-NEW.AppImage
   # Convert to SRI format:
   nix hash to-sri --type sha256 <raw-hash>
   

3. Run nix-build and test.

Troubleshooting

libmpv.so: cannot open shared object file

Ensure pkgs.mpv is in extraPkgs. If you build mpv yourself with custom options, the .so name or version may differ — check with nix run nixpkgs#patchelf -- --print-needed result/bin/.fladder-wrapped.

libpython3.x.so.1.0: cannot open shared object file

The python3 package in extraPkgs should fix this. If it persists, pin the python version to match the one nixpkgs' mpv was linked against.

App window is black / no video

Make sure Mesa / OpenGL is enabled in your NixOS config (see AMD GPU section above). Also try setting LIBGL_ALWAYS_SOFTWARE=0 to rule out Mesa's software rasterizer being selected.

Wayland: window appears but is blank

Try forcing X11 as a workaround: WAYLAND_DISPLAY="" ./result/bin/fladder. This is a known Flutter/Wayland edge case on some compositor versions.

License

The Nix packaging files in this repo are released under the MIT license. Fladder itself is GPL-3.0.