Fladder for macOS

A personal Jellyfin client for the Mac, built with Flutter.

This is Haryk96's independently maintained fork of DonutWare/Fladder. Development is driven by everyday use on a Mac, including a laptop connected to a TV: reliable playback, readable subtitles, comfortable keyboard controls, downloads that save storage space, and a useful fullscreen interface.

macOS is the only supported release target for this fork. Release automation builds the Apple Silicon Mac app. The repository retains code for other platforms inherited from upstream, but maintaining and releasing those platforms is outside this fork's scope.

Features

• Stream from Jellyfin with direct playback or server transcoding.
• Browse libraries, continue watching, and queue the next episode.
• Combine Continue Watching and Next Up into one row without duplicate shows.
• Select audio and subtitle tracks, skip media segments, and use trickplay previews.
• Download media for local playback and keep watch progress in sync.
• Save space with download qualities from 480p through 2160p (4K), size estimates, and a remembered default.
• Switch between accounts and Jellyfin servers.
• Use keyboard shortcuts, fullscreen playback, and a TV-oriented interface.
• Control the Mac from Jellyfin's existing Android app using its Play On menu.
• Keep downloaded playback visible to Jellyfin while online, with local progress saved even if the connection fails.
• Jump between chapters using visible controls, with preview fallbacks when chapter artwork is missing.
• Customize the theme, layout, and subtitle appearance.
• Access Seerr/Jellyseerr integration and library management tools.

This fork adds space-saving download presets and Mac reliability improvements to the original Fladder feature set. Current findings and proposed work are recorded in the macOS improvement review.

Download quality

Choose Original, 480p, 720p (HD), 1080p (Full HD), 1440p (2K), or 2160p (4K) when downloading a movie, episode, season, or batch. The picker shows approximate sizes and lets you save a default for future downloads. You can also set the default under Settings → Downloads → Download quality. Advanced codec and bitrate controls remain available.

Original downloads preserve the server file. The other presets request an H.264/AAC MP4 encoded by Jellyfin, with resolution and bitrate limits. Lower-resolution sources are not upscaled. Encoding uses server resources, and the final size depends on the content.

A complete download was verified against Jellyfin 12.1.0 on this Mac: a 549 MB source became a playable 30 MB, 480p file with stereo audio. Details and remaining work are in the macOS improvement review.

Install

There are no published releases of this fork yet. Build the app locally using the instructions below. Future macOS downloads will appear on this fork's releases page.

A release build produces a standalone Fladder.app. Copy it into your Applications folder and launch it normally; Flutter and Xcode are only needed to build the app.

The app currently uses the original bundle identifier, nl.jknaapen.fladder. Local builds therefore share the original application's account and settings storage. Quit any other Fladder instance before switching between builds.

To replace an upstream installation, quit it and move only its Fladder.app from Applications to Trash, then copy the locally built app into Applications. Keep Fladder's Library data and download files; an app cleaner that removes these would also remove your saved account and settings.

The in-app release checker and project link point to this fork. Upstream Fladder is credited separately in About and below.

The Mac build workflow runs tests and creates a DMG artifact for relevant pull requests, pushes to the main development branches, and manual runs. Pushing a v tag matching the version in pubspec.yaml also prepares a draft release with the DMG and its checksum. Review and publish that draft from GitHub when ready. The updated workflow has passed local validation; its first hosted run is still outstanding.

Build on macOS

Requirements

• macOS 12 or newer, as configured by the project.
• Xcode with its command-line tools selected.
• CocoaPods.
• FVM to use the Flutter version pinned in .fvmrc, currently 3.47.6 (Dart 3.13.5).

The release build has been verified on an Apple Silicon Mac with macOS 27.0.1 and Xcode 27.0. Intel builds have not been verified for this fork.

The dependency upgrade notes record the updated packages, compatibility constraints, and regression checks.

Build a standalone app

git clone https://github.com/Haryk96/Fladder.git
cd Fladder
fvm install
fvm flutter pub get
./scripts/build_macos.sh

The output is:

build/macos/Build/Products/Release-production/Fladder.app

The build script targets the current Mac's architecture and verifies the app's local signature. It repairs stale signatures left by incremental Flutter builds. On Apple Silicon, its FLUTTER_XCODE_ARCHS=arm64 setting also avoids a Flutter/Xcode 27 architecture-verification issue with this pinned Flutter version. Rebuild after changing the app's code to use those changes in your standalone copy.

Quit Fladder, then install the verified build and open the Applications copy:

./scripts/install_macos.sh
open /Applications/Fladder.app

If Spotlight shows several Fladder entries, use the one labeled Applications. The Release-production and Debug-production entries are development outputs. Repeat both the build and install steps after code changes to update the Applications copy.

Use a Mac connected to a TV

For a TV used as an external display, open the app normally, move its window onto the TV, and enter fullscreen using the macOS window controls.

The existing --htpc launch option starts the app in fullscreen with the television layout and directional keyboard navigation, using its startup window placement. Quit Fladder first so the launch arguments apply to a fresh instance, then run:

open /Applications/Fladder.app --args --htpc

The Mac app restores its last window position and fullscreen state. If the TV is disconnected, it fits the window onto an available display. TV mode checks the display containing the app when the display resolution changes. HDMI reconnection still needs a check with a real TV.

Adjust subtitle timing

With the MPV player, open the subtitle menu to show subtitles earlier or later in 0.25-second steps. The default shortcuts are [ for earlier, ] for later, and \ to reset. They are customizable under Player settings. A brief indicator shows the current offset; positive values display subtitles later. The adjustment survives a reload of the same video and resets for the next video. Timing controls are currently available for MPV; use that player when you need this feature. Subtitles already burned into the video by the server cannot be shifted by the player.

Use your phone as a remote

Leave Fladder open and signed into Jellyfin on the Mac. In the Jellyfin Android app, connect to the same server, open Play On (the cast/device button), and select Fladder. Choose a movie or episode on your phone to play it on the Mac. Playback controls support pause/resume, seeking, stop, next/previous in the current queue, volume/mute, and audio/subtitle selection. No separate Fladder phone app is needed.

The server must allow your phone's account to control that session. Both devices need access to the Jellyfin server, including any required VPN. Fladder reconnects automatically after a dropped server connection and changes connections when you switch accounts or servers. This feature currently runs in the macOS app. Remote queue editing, SyncPlay, and navigating Fladder's menus from the phone are not implemented.

Run while developing

fvm flutter run -d macos --flavor production

When changing models, routes, or other inputs to generated code:

fvm dart run build_runner build --delete-conflicting-outputs

When changing translations:

fvm flutter gen-l10n

Contributing

Report bugs and propose changes in this fork's issues and pull requests. Include the macOS version, Mac model, app version, Jellyfin version, and steps to reproduce. For playback problems, include the selected player, audio/subtitle format, and whether an external display is connected.

Keep changes focused and describe how they were checked on macOS. Contributions from upstream will be considered where they improve this fork's Mac experience; an upstream PR being open or merged does not by itself mean its changes are included here.

Credits and license

Fladder was created by DonutWare and its contributors. This fork builds on their work, Flutter, and the project's existing open-source dependencies.

The project remains licensed under the GNU General Public License v3.0.