README.md
1# Celluloid
2
3Celluloid (formerly GNOME MPV) is a simple GTK+ frontend for mpv. Celluloid
4interacts with mpv via the client API exported by libmpv, allowing access to
5mpv's powerful playback capabilities.
6
7
8
9## Dependencies
10
11- appstream-glib<sup>[[1]](#note1)</sup> (build)
12- autoconf >= 2.69<sup>[[1]](#note1)</sup> (build)
13- autoconf-archive<sup>[[1]](#note1)</sup> (build)
14- automake >= 1.12<sup>[[1]](#note1)</sup> (build)
15- pkg-config (build)
16- gcc (build)
17- glib >= 2.66
18- gtk >= 4.0
19- mpv >= 0.32
20- epoxy
21- lua (optional)
22- youtube-dl (optional)
23
24<a name="note1">[1]</a>: Not required when building from release tarballs
25
26## Installation
27
28### GNU/Linux packages
29- Arch Linux: https://www.archlinux.org/packages/celluloid
30- Arch Linux (Git): https://aur.archlinux.org/packages/celluloid-git
31- Debian: https://tracker.debian.org/pkg/celluloid
32- Fedora (rpmfusion): https://admin.rpmfusion.org/pkgdb/package/free/celluloid/
33- OpenSUSE: https://software.opensuse.org/package/celluloid
34- Gentoo: https://packages.gentoo.org/packages/media-video/celluloid
35- Guix: https://guix.gnu.org/en/packages/celluloid-0.20
36- Solus: https://packages.getsol.us/shannon/g/gnome-mpv/
37- Ubuntu: https://launchpad.net/~xuzhen666/+archive/ubuntu/gnome-mpv
38
39### Flatpak
40
41[Flatpak](https://flatpak.org) packages support multiple distributions and are sandboxed.
42Flatpak 0.9.5+ is recommended for best integration.
43
44Stable releases are hosted on [Flathub](https://flathub.org):
45
46```sh
47flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
48flatpak install flathub io.github.celluloid_player.Celluloid
49```
50
51Development versions are also packaged:
52
53```sh
54flatpak install https://dl.tingping.se/flatpak/gnome-mpv.flatpakref
55```
56
57
58### Source code
59Run the following command in the source code directory to build and install:
60
61```sh
62meson build && cd build && ninja && sudo ninja install
63```
64
65Alternatively, you can use Autotools:
66
67```sh
68./autogen.sh && make && sudo make install
69```
70
71When building from release tarballs, replace `./autogen.sh` with `./configure`:
72
73```sh
74./configure && make && sudo make install
75```
76
77## Usage
78
79### Opening files
80
81There are 4 ways to open files in Celluloid.
82
831. Passing files and/or URIs as command line arguments.
842. Using the file chooser dialog box, accessible via the "Open" menu item.
853. Typing URI into the "Open Location" dialog box, accessible via the
86 menu item with the same name.
874. Dragging and dropping files or URIs onto Celluloid.
88
89### Manipulating playlist
90
91The playlist is hidden by default. To show the playlist, click the "Playlist"
92menu item or press F9. Files can be added by dragging and dropping files or URIs
93onto the playlist. Dropping files or URIs onto the video area will replace the
94content of the playlist. Playlist files or online playlists (eg. YouTube's
95playlist) will be automatically expanded into individual items when loaded.
96
97Items in the playlist can be reordered via drag-and-drop. To remove items from
98the playlist, select the item by clicking on it then press the delete button on
99your keyboard.
100
101### Configuration
102
103Celluloid can be configured using the preferences dialog accessible via the
104"Preferences" menu item. Additional configuration options can be set from an
105external file using the same syntax as mpv's `mpv.conf`.
106See [mpv's manual](https://mpv.io/manual/stable/) for the full list of options.
107The file must be specified and enabled in the preferences dialog under the "MPV
108Configuration" section.
109
110It is also possible to set mpv options by putting the options — as you
111would pass to mpv on the command line — in `Extra MPV Options` text box in
112the preferences dialog. You can also pass options directly on the command line
113by adding `mpv-` prefix to the option name. For example, using the option
114`--mpv-vf=flip` when launching Celluloid is equivalent to using `--vf=flip` in
115mpv.
116
117### User Scripts
118
119Celluloid can use most mpv user scripts as-is. Some user scripts may define
120keybindings that conflict with Celluloid, in which case you'll need to resolve
121the conflict by explicitly defining new keybindings using `input.conf`. See
122[mpv's manual](https://mpv.io/manual/stable/#lua-scripting-[,flags]]%29) for
123more details.
124
125User scripts can be installed by switching to the "Plugins" tab in the
126preferences dialog and dropping the files there. A list of mpv user scripts can
127be found [here](https://github.com/mpv-player/mpv/wiki/User-Scripts).
128
129### Keybindings
130
131Celluloid defines a set of keybindings in the macro `DEFAULT_KEYBINDS`, which
132can be found in
133[src/celluloid-def.h](https://github.com/celluloid-player/celluloid/blob/master/src/celluloid-def.h).
134The syntax used is exactly the same as mpv's `input.conf`. These keybindings are
135applied on top of default keybindings provided by mpv.
136
137Additional keybindings can be defined in an external file using mpv's
138`input.conf` syntax. The file can be set in the preferences dialog under the
139"Keybindings" section.
140
141## Contributing Translations
142
143
144
145Celluloid uses [Weblate](https://weblate.org) to coordinate translations. You
146can find Celluloid's page [here](https://hosted.weblate.org/projects/celluloid).
147
148While translating, you will find the string `translator-credits`. You should not
149translate this string. Instead, you should put your name, and optionally your
150email address, in the following format: `FirstName LastName <Email Address>`.
151Your name will then appear in the About dialog when your translation is active.
152
153## License
154
155Celluloid is free software: you can redistribute it and/or modify
156it under the terms of the GNU General Public License as published by
157the Free Software Foundation, either version 3 of the License, or
158(at your option) any later version.
159
160Celluloid is distributed in the hope that it will be useful,
161but WITHOUT ANY WARRANTY; without even the implied warranty of
162MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
163GNU General Public License for more details.
164
165You should have received a copy of the GNU General Public License
166along with Celluloid. If not, see <http://www.gnu.org/licenses/>.
167
168
){kind=link}
){kind=link}