Celluloid: a GTK4 window over libmpv, with mpv's own config files underneath

The window is the product, mpv does the work

The README's definition is one sentence: a simple GTK+ frontend for mpv that interacts with mpv through the client API exported by libmpv, giving access to mpv's powerful playback capabilities. That boundary explains both the size of the codebase and the feature list. Celluloid does not implement decoding, demuxing or subtitle rendering; it issues commands over libmpv and renders what comes back. The consequence for a user is that mpv's capabilities are Celluloid's capabilities, including anything you would otherwise configure through mpv's own files. The project was formerly known as GNOME MPV, which is visible in the topics and in the older Ubuntu PPA, and the repository mirror now lives on Codeberg rather than only on GitHub.

The dependency floor is what decides whether you can install it

The dependency list is short and the versions are the point. Build time needs appstream, pkg-config and gcc. At runtime it needs glib 2.68 or newer, gtk 4.16 or newer, gdk-pixbuf 2.30 or newer, libadwaita 1.8.0 or newer, mpv 0.32 or newer, and epoxy. Lua and youtube-dl are listed as optional. GTK 4.16 and libadwaita 1.8 are recent floors, so on an older distribution the Flatpak or Snap route is not a convenience but the only practical one. Check those numbers before you plan a migration from another player, because they decide whether a native package in your distribution will even build.

Three install routes, and only one of them compiles anything

Distribution packages exist, with a Repology badge for packaging status and a PPA for Ubuntu users who want more up to date versions than their release carries. The Flatpak is the route the project describes as supporting multiple distributions and being sandboxed, with Flatpak 0.9.5 or newer recommended for the best integration:

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub io.github.celluloid_player.Celluloid

Stable releases are also on Snapcraft:

sudo snap install celluloid

From source it is a meson build in the source directory:

meson setup build && cd build && ninja && sudo ninja install

The repository holds a meson.build at the root plus flatpak/ and data/ directories and a meson-post-install.py, which is where desktop integration and icon installation are handled.

Three configuration layers, and the third is mpv's own

Configuration is layered, and knowing which layer to use saves time. The preferences dialog covers what the app exposes. A number of less common options live in the dconf database and can be edited with a tool like Dconf Editor. Everything else is mpv's, through a configuration file written in mpv.conf syntax that you must both create and then point at from the preferences dialog, under the MPV Configuration section, before it takes effect. That last requirement is the trap: an mpv.conf sitting in the right place does nothing until the app is told to read it. There is also an Extra MPV Options text box in the preferences dialog where you can type options as you would pass them to mpv on a command line, and on the command line itself the mpv- prefix passes an option through, so an option written as --mpv-vf=flip is equivalent to --vf=flip in mpv.

The playlist is hidden behind F9, and dropping on the video replaces it

The playlist is hidden by default, shown from the Playlist menu item or with F9, which keeps the window uncluttered for the common case of one file. Adding files by drag and drop onto the playlist appends them, but dropping onto the video area replaces the playlist contents, so a stray drop while watching something discards your queue. Playlist files and online playlists are expanded into individual items when loaded, which is what you want for a long remote list. Items reorder by drag and drop and are removed by selecting and pressing the delete key on the keyboard. Four ways to open media are listed: command line arguments, the Open file chooser, the Open Location dialog for URIs, and drag and drop.

mpv user scripts load as-is, unless the keys collide

The plugin story is delegated almost entirely to mpv. Celluloid can use most mpv user scripts as they are, and installation is a file drop into the Plugins tab of the preferences dialog. The one documented friction is keybindings: a script that defines keybindings conflicting with Celluloid's own will not behave, and the fix is to define new bindings explicitly using input.conf. That file syntax is mpv's, and Celluloid's own bindings live in a macro called DEFAULT_KEYBINDS in src/celluloid-def.h, which is a useful file to read if you want to see what is already taken. Extra keybindings can also be defined in an external input.conf file whose path you set in the preferences dialog under Keybindings. The bindings defined there are applied on top of the defaults provided by mpv.

Contributions are welcome, generated code is not

Two policy statements sit at the end of the README and both are unusual enough to matter. Translations are coordinated through Weblate, with a widget tracking status, and there is one rule for translators: do not translate the string translator-credits, put your name and optionally an email in the format FirstName LastName <Email Address> instead, and it appears in the About dialog when your translation is active. The second is sharper: due to the lack of clarity around its copyright status, AI generated code is not accepted in this project, and pull requests containing it should not be opened. If you plan to contribute tooling assisted code, that is a hard no rather than a review comment. The licence is GPL-3.0 or later.

Against mpv's own interface

What Celluloid adds is a conventional desktop application: a preferences dialog with searchable sections, a visible playlist with drag and drop reordering, a file chooser, and a window that behaves the way other GNOME applications do. Settings not exposed in the preferences dialog can also use the documented dconf options, mpv.conf, or the Extra MPV Options box. Choose Celluloid if you want a normal application and can accept routing settings through mpv's syntax; stay with mpv if you would rather everything be one interface and one config file.

Editorial conclusion

Celluloid suits anyone who wants mpv's playback engine in a native GNOME application, since the split is honest, libmpv does the work and the app contributes a playlist, a preferences dialog and keybindings, and mpv.conf and input.conf use mpv's syntax. Skip it on a system below the GTK 4.16 and libadwaita 1.8.0 floor, or if you want a player that adds codec support or an integrated library, because nothing here changes what mpv can play. Before building from source, install the listed build dependencies, since appstream, pkg-config and gcc are needed before meson setup will configure, and note that the project has moved its mirror to Codeberg and refuses AI generated code in pull requests. Version 0.30 was released on 2026-03-29 and the last push was on 2026-10-04.

Frequently asked questions

Official sources

1. celluloid-player/celluloid on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases