# fladder — NixOS package

Unofficial NixOS package for [Fladder](https://github.com/DonutWare/Fladder),
a cross-platform [Jellyfin](https://jellyfin.org/) 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

```bash
# 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`:

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

### As an overlay

```nix
# 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

```nix
# 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](https://appimage-builder.readthedocs.io/). 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 `dlopen`s `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](https://github.com/DonutWare/Fladder/issues/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:

```nix
# 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:
   ```bash
   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](https://github.com/DonutWare/Fladder/blob/develop/LICENSE).