1MELLOWPLAYER(1) MellowPlayer MELLOWPLAYER(1)
2
6 mellowplayer - MellowPlayer Documentation [image]
7
9 Contents:
10 About MellowPlayer
12 MellowPlayer is born from the need of a Qt-based alternative to
13 NuvolaPlayer for the KaOS linux distribution
14 Here are the initial goals:
16 · the application should embed a web view of the music streaming ser‐
18 vice (the same as you see in a regular browser) and should provide an
19 integration with the desktop (media keys support, global shortcuts,
20 notifications,...).
21 · the application should be able to support more than 1 streaming ser‐
23 vice
24 · we (the core team) will only support the streaming services that we
26 are actively using. Other services should be added and maintained by
27 contributors. The main reason is that we won't be able to support
28 non-free services (even those who have a trial period). Support for
29 free services (even with limitations) might be added by the team
30 after the release 1.0.
31 · adding a new service/extension should be easy: you just write a
33 javascript plugin
34 Installation
36 This page will guide you throught the installation of MellowPlayer on
37 the supported operating systems.
38 GNU/Linux
40 We provide several ways to install a pre-compiled version of Mellow‐
41 Player on GNU/Linux:
42 1. Native package (only for Ubuntu, Fedora, ArchLinux & openSUSE)
44 2. Flatpak
46 3. AppImage
48 To choose which kind of installer you should use, follow those simple
50 rules:
51 · Always prefer the native package to any other format if that is
53 available for your distribution. Native package will always integrate
54 better with your desktop and, in most cases, it will pick up propri‐
55 etary codecs (ffmpeg) from your system if installed.
56 · Prefer flatpak over AppImage, especially if the service you want to
58 use require proprietary audio codecs.
59 · Use the AppImage if flatpak is not available on your distribution
61 (very unlikely) and you don't need proprietary codecs.
62 Fedora
64 Starting from Fedora 27, MellowPlayer is available from the official
65 stable repositories:
66 sudo dnf install mellowplayer
68 Proprietary codecs
70 Most services require proprietary audio codecs to work. You can install
71 them from the RPMFusion repositories:
72 sudo dnf install qt5-qtwebengine-freeworld
74 Flash
76 Services such as Deezer and Tidal require flash to work. You can
77 install it from the adobe repositories:
78 sudo rpm -ivh http://linuxdownload.adobe.com/adobe-release/adobe-release-i386-1.0-1.noarch.rpm
80 sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-adobe-linux
81 sudo dnf install flash-player-ppapi
82 Widevine
84 Some services such as Spotify and Amazon Music requires the widevine
85 ppapi plugin to work, you can install it by running the below commands:
86 wget https://archive.archlinux.org/packages/c/chromium/chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
88 wget https://dl.google.com/widevine-cdm/1.4.8.1008-linux-x64.zip
89 tar -xvf chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
90 unzip 1.4.8.1008-linux-x64.zip
91 sudo mkdir /usr/lib/chromium
93 sudo cp libwidevinecdm.so /usr/lib/chromium
94 sudo cp ./usr/lib/chromium/libwidevinecdmadapter.so /usr/lib/chromium
95 sudo chmod 644 /usr/lib/chromium/libwidevinecdm.so
96 sudo chmod 644 /usr/lib/chromium/libwidevinecdmadapter.so
97 NOTE:
99 You might need to adapt this script to download a version of
100 chromium and widevine that match the version used by your Qt instal‐
101 lation.
102 Ubuntu
104 18.04
105 Before installing MellowPlayer, make sure the universe repository is
106 enabled:
107 sudo add-apt-repository universe
109 Install procedure:
111 sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/ColinDuquesnoy/xUbuntu_18.04/ /' > /etc/apt/sources.list.d/mellowplayer.list"
113 wget -nv https://download.opensuse.org/repositories/home:ColinDuquesnoy/xUbuntu_18.04/Release.key -O Release.key
114 sudo apt-key add - < Release.key
115 sudo apt update
116 sudo apt install mellowplayer
117 19.10
119 Before installing MellowPlayer, make sure the universe repository is
120 enabled:
121 sudo add-apt-repository universe
123 Install procedure:
125 sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/ColinDuquesnoy/xUbuntu_19.10/ /' > /etc/apt/sources.list.d/mellowplayer.list"
127 wget -nv https://download.opensuse.org/repositories/home:ColinDuquesnoy/xUbuntu_19.10/Release.key -O Release.key
128 sudo apt-key add - < Release.key
129 sudo apt update
130 sudo apt install mellowplayer
131 Debian
133 Stable (Buster)
134 sudo sh -c "echo 'deb https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_10/ /' > /etc/apt/sources.list.d/mellowplayer.list"
135 wget -nv https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_10/Release.key -O Release.key
136 sudo apt-key add - < Release.key
137 sudo apt update
138 sudo apt install mellowplayer
139 Testing
141 sudo sh -c "echo 'deb https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_Testing/ /' > /etc/apt/sources.list.d/mellowplayer.list"
142 wget -nv https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_Testing/Release.key -O Release.key
143 sudo apt-key add - < Release.key
144 sudo apt update
145 sudo apt install mellowplayer
146 Unstable
148 sudo sh -c "echo 'deb https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_Unstable/ /' > /etc/apt/sources.list.d/mellowplayer.list"
149 wget -nv https://download.opensuse.org/repositories/home:/ColinDuquesnoy/Debian_Unstable/Release.key -O Release.key
150 sudo apt-key add - < Release.key
151 sudo apt update
152 sudo apt install mellowplayer
153 ArchLinux
155 MellowPlayer is available from the AUR, install it with your favorite
156 AUR tool (e.g. yaourt).
157 yaourt -S mellowplayer
159 openSUSE Leap 15
161 Use the openSUSE build service web interface or install manually:
162 zypper addrepo https://download.opensuse.org/repositories/home:ColinDuquesnoy/openSUSE_Leap_15.1/home:ColinDuquesnoy.repo
164 zypper refresh
165 zypper install MellowPlayer
166 openSUSE Tumbleweed
168 Use the openSUSE build service web interface or install manually:
169 zypper addrepo http://download.opensuse.org/repositories/home:ColinDuquesnoy/openSUSE_Tumbleweed/home:ColinDuquesnoy.repo
171 zypper refresh
172 zypper install MellowPlayer
173 KaOS
175 MellowPlayer is available from KaOSx/apps repository, just run:
176 $ sudo pacman -S mellowplayer
178 Flatpak
180 MellowPlayer's flatpak is not yet available on flathub but you can
181 download and install a single file bundle:
182 1. Download the flatpak from our bintray repository
184 2. Install the flatpak: flatpak install ./MellowPlayer.flatpak
186 3. Run the flatpak from your application menu or from command line:
188 flatpak run com.gitlab.ColinDuquesnoy.MellowPlayer
189 AppImage
191 1. Download the AppImage from our bintray repository
192 2. Make it executable: chmod +x ./MellowPlayer.AppImage
194 3. Run it: ./MellowPlayer.AppImage
196 Compiling from source
198 See the README for build instructions.
199 Windows
201 Just grab the windows installer from the official website (click on the
202 Windows folder) and follow the instructions.
203 Please note the Windows Installer we provide is built with a version of
205 QtWebEngine built without proprietary codecs support (for licensing
206 reasons). If your favorite service require proprietary codecs to work,
207 you'll need to build QtWebEngine with the flag use_proprietary_codecs
208 and build MellowPlayer using that QtWebEngine version.
209 OS X
211 OSX is not officially supported anymore. You may try to build and run
212 MellowPlayer from sources.
213 Features
215 · Cross-platform (available on Windows, Mac OSX and GNU/Linux)
216 · System tray integration and notifications
218 · Mpris2 support (GNU/Linux only)
220 · Hotkeys and media player keys support
222 · Plugin based application (you can add support for a new web-based
224 music streaming service by writing a javascript plugin)
225 · User scripts support
227 Supported Services
229 ┌───────────┬───────────┬──────────┬─────────┬─────┬──────────┬──────────┬─────────┐
230 │Service │ GNU/Linux │ AppImage │ Windows │ OSx │ Require │ Require │ Require │
231 │ │ │ │ │ │ non-free │ Flash │ DRM │
232 │ │ │ │ │ │ HTML │ │ │
233 │ │ │ │ │ │ codecs │ │ │
234 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
235 │Deezer │ Yes │ Yes │ Yes │ Yes │ Optional │ Optional │ No │
236 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
237 │Mixcloud │ Yes │ No │ No │ No │ Yes │ No │ No │
238 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
239 │Soundcloud │ Yes │ No │ No │ No │ Yes │ No │ No │
240 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
241 │Spotify │ Yes │ No │ No │ No │ Yes │ No │ Yes │
242 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
243 │TuneIn │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
244 │ │ │ │ │ │ on │ │ │
245 │ │ │ │ │ │ streams │ │ │
246 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
247 │8tracks │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
248 │ │ │ │ │ │ on │ │ │
249 │ │ │ │ │ │ streams │ │ │
250 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
251 │Google │ Yes │ Yes │ Yes │ Yes │ ? │ ? │ ? │
252 │Play Music │ │ │ │ │ │ │ │
253 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
254 │Youtube │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
255 │ │ │ │ │ │ on │ │ │
256 │ │ │ │ │ │ streams │ │ │
257 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
258 │Tidal │ Yes │ Yes │ Yes │ Yes │ No │ Yes │ No │
259 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
260 │Anghami │ Yes │ No │ No │ No │ Yes │ No │ No │
261 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
262 │Pocket │ Yes │ No │ No │ No │ Yes │ No │ No │
263 │Casts │ │ │ │ │ │ │ │
264 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
265 │HearThisAt │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
266 │ │ │ │ │ │ on │ │ │
267 │ │ │ │ │ │ streams │ │ │
268 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
269 │Jamendo │ Yes │ Yes │ Yes │ Yes │ No │ No │ No │
270 └───────────┴───────────┴──────────┴─────────┴─────┴──────────┴──────────┴─────────┘
271 │Radionomy │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
275 │ │ │ │ │ │ on │ │ │
276 │ │ │ │ │ │ streams │ │ │
277 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
278 │Wynk │ Yes │ No │ No │ No │ Yes │ No │ No │
279 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
280 │ympd │ Yes │ Yes │ Yes │ Yes │ No │ No │ No │
281 └───────────┴───────────┴──────────┴─────────┴─────┴──────────┴──────────┴─────────┘
282 User Scripts
284 With MellowPlayer >= 3.1 you have the possibility to use user scripts.
285 This means that you can customize the look and feel of a streaming ser‐
287 vice as you like it, or simply to add features you miss.
288 · Download and use different themes
290 · Download and use different user scripts
292 Getting started
294 First startup
295 On the first startup, you'll be presented with the following screen:
296 [image]
297 Just click on a service to start running it. You can start multiple
299 service at the same time and quickly switch between them using
300 Ctrl+Tab/Ctrl+Shift+Tab. [image]
301 You can get back to the service selection page using F8 or the select
303 service button: [image]
304 Application Settings
306 You can change application settings by clicking on the menu button and
307 by selecting the Settings entry or by pressing F2: [image]
308 This will bring the following page: [image]
310 There are a series of settings category:
312 · General: general options
314 · Appearance: let you change the appearance of the application
316 · Notifications: let you change some notification settings
318 · Shortcuts: let you change all the application shortcuts
320 · Privacy: enable or disable privacy related options
322 · Services: list the available services and let configure them (url,
324 user scripts)
325 · Cache: a few buttons that let you clear the application cache (album
327 art covers,...) and clear the web cookies.
328 Notifications
330 By default, MellowPlayer will display a notification whenever the cur‐
331 rent track changed. [image]
332 You can change the notifications behaviour in the application settings
334 page [image]
335 and you can also quickly toggle notifications on/off using the button
337 in the toolbar: [image]
338 Listening History
340 MellowPlayer can keep track of your listens and display it in a side
341 panel. This feature is OFF by default.
342 You can see your listening history by pressing the listening history
344 button: [image]
345 Here is what the history look like: [image]
347 You can search the history and filter by service by clicking on the
349 search icon [image]
350 MPRIS2 Interface
352 Most GNU/Linux Desktop Environments have a MPRIS client interface that
353 sits in the system tray and let you control media players easily.
354 MellowPlayer implements the DBUS MPRIS 2 interface and should appear in
356 your MPRIS2 client interface:
357 · Plasma 5:
359 [image]
360 · Gnome:
362 [image]
363 · Unity:
365 [image]
366 FAQ & Known issues
368 Playback does not start on some services such as Soundcloud or Mixcloud...
369 What can I do?
370 Services that don't use flash often requires proprietary audio codecs
371 to be installed on your system. Those codecs are not included in our
372 official releases (AppImage and Windows Installer).
373 To solve the problem, you need to build MellowPlayer and Qt from
375 sources and make sure you enable propertietary codecs support, see
376 https://doc.qt.io/qt-5.11/qtwebengine-features.html#audio-and-video-codecs
377 If you're using GNU/Linux, check if a native package of MellowPlayer is
379 available for your distribution and use it instead of AppImage. Native
380 packages usually use system ffmpeg and it should be enought to install
381 extra ffmpeg plugins for the missing proprietary codecs.
382 NOTE:
384 MP3 is still considered as a proprietary/patented codec prior to Qt
385 5.11.
386 NOTE:
388 Services that require proprietary codecs are included in our offi‐
389 cial releases but won't appear in the application.
390 The application crashes at startup on GNU/Linux with open source NVIDIA
392 drivers. What can I do?
393 Qt/QML applications don't work well with the open source NVIDIA drivers
394 (nouveau). It is recommended to use the proprietary NVIDIA drivers.
395 The application crashes at startup on GNU/Linux with proprietary NVIDIA
397 drivers. What can I do?
398 Make sure you rebooted after your last NVIDIA driver update and make
399 sure to run sudo nvidia-xconfig before reporting the issue.
400 There is no music playback on Spotify. What can I do?
402 Make sure you have installed both the proprietary audio codecs (ffmpeg
403 with extra codecs) and the widevine DRM plugin. The DRM plugin can be
404 extracted from chromium binary archive:
405 wget https://archive.archlinux.org/packages/c/chromium/chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
407 wget https://dl.google.com/widevine-cdm/1.4.8.1008-linux-x64.zip
408 tar -xvf chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
409 unzip 1.4.8.1008-linux-x64.zip
410 sudo mkdir /usr/lib/chromium
412 sudo cp libwidevinecdm.so /usr/lib/chromium
413 sudo cp ./usr/lib/chromium/libwidevinecdmadapter.so /usr/lib/chromium
414 sudo chmod 644 /usr/lib/chromium/libwidevinecdm.so
415 sudo chmod 644 /usr/lib/chromium/libwidevinecdmadapter.so
416
418 Contents:
419 Coding guidelines
421 We use the llvm code formating guidelines using clang-format.
422 We made a small script that will format any C++/javascript source file
424 in the project to fit the style guidelines:
425 sh scripts/beautify.sh
427 To run this tool, you need to install the following packages:
429 · clang-format: sudo pacman -S clang
431 · jsbeautifier: sudo pip3 install jsbeautifier
433 Please, run this script before submitting a pull request!
435 See the coding guidelines wiki page for more information:
437 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/coding-guidelines
438 Project structure
440 See the architecture wiki page for more information:
441 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/architecture
442 Plugins
444 Introduction
445 MellowPlayer can be extended by writing a streaming service integration
446 plugin.
447 A streaming service integration plugin is just a directoy that contains
449 some specific files:
450 · integration.js: the actual code that integrates the service into Mel‐
452 lowPlayer
453 · logo.svg: the logo of the service
455 · metadata.ini: plugin's metadata
457 · theme.json: optional theme definition. The colors defined in this
459 file are used through the whole user interface if theme is set to
460 adaptive.
461 The file integration.js contains a series of function that you must
463 implement. Those functions will get called by the C++ application for
464 updating the player state or when the user triggered an action (play,
465 pause,...).
466 MellowPlayer will look for plugins in the following directories:
468 · $CURRENT_WORKING_DIR/plugins
470 · /usr/share/mellowplayer/plugins
472 · /usr/local/share/mellowplayer/plugins
474 · ~/.local/share/MellowPlayer/plugins
476 Create a new plugin
478 This feature does not exists anymore in v2.95.0, we will be back for
479 v3.0.0
480 To create a plugin, go to the Control drop down menu or the Developer
482 main menu and click on Create plugin.
483 This will bring the following wizard: [image]
485 Fill in the details: [image]
487 When you're done, select your new plugin service in the services dialog
489 that will automatically pop out: [image]
490 Specify the supported platforms
492 When you create the plugin, you need to specify the list of supported
493 platforms. Services that require proprietary codecs to work are not
494 supported on AppImage, Windows and OSX.
495 If you are developing on GNU/Linux and want to know if you plugin will
497 work everywhere, try it from an official AppImage release. If it works,
498 you can safely check All platforms, otherwise it might only work as a
499 native package from a GNU/Linux distribution.
500 Functions to implement
502 Here is a brief description of the functions you need to implement in
503 order to integrate a new web-based streaming service.
504 update()
506 This function is called regularly to update the player information.
507 You must return a dictionnary with the following keys:
509 · playbackStatus (int): Use mellowplayer.PlaybackStatus)*. Mandatory
511 · canSeek (bool): True if the player can seek into the current song.
513 · canGoNext (bool): True if the player can skip to the next song.
515 · canGoPrevious (bool): True if the playe can skip to the previous
517 song.
518 · canAddToFavorites (bool): True if the user can add or remove the cur‐
520 rent song from a list of favorites
521 · volume (float [0-1]): Player volume. Optional, leave it 1 if your
523 plugin cannot control the volume.
524 · songId (str): The unique id of the current song. Mandatory. Either
526 use a GUID or hash the song title if no id is available.
527 · songTitle (str): The title of the current song. Mandatory
529 · artistName (str): The name of the artist of the current. Optional.
531 · albumTitle (str): The name of the album of the current song.
533 Optional.
534 · artUrl (str): The current song art url.
536 · isFavorite (bool): True if the song is in the list of the user's
538 favorite songs. Optional.
539 · duration (int [seconds]): The duration of the song, in seconds.
541 Optional (but nice).
542 · position (int [seconds]): The position (or elapsed time) of the song,
544 in seconds. Optional (but nice).
545 play()
547 Starts playback.
548 pause()
550 Pauses playback.
551 goNext()
553 Skips to next song.
554 goPrevious()
556 Skips to previous song.
557 setVolume(volume)
559 Sets the player's volume.
560 volume is a float in the range [0-1].
562 addToFavorites()
564 Adds song to favorites.
565 removeFromFavorites()
567 Removes song from favorites.
568 seekToPosition(position)
570 Seeks to the specified position.
571 position is an int representing the new position inside the song (in
573 seconds).
574 PlaybackStatus
576 MellowPlayer will inject a few constants that you can use for repre‐
577 senting the current PlaybackStatus:
578 · mellowplayer.PlaybackStatus.STOPPED: indicates that the playback has
580 stopped.
581 · mellowplayer.PlaybackStatus.PAUSED: indicates that the playback has
583 paused.
584 · mellowplayer.PlaybackStatus.BUFFERING: indicates that the a song is
586 buffering.
587 · mellowplayer.PlaybackStatus.PLAYING: indicates that the a song is
589 currently playing.
590 Utility functions
592 · function getHashCode(string): returns the hash code of the specified
593 string. You can use this to generate the song id if none is available
594 via the web streaming service API.
595 · toSeconds(string) converts a time string (HH:mm:ss) to a number of
597 seconds.
598 Contributing to MellowPlayer
600 Reporting bugs or Wishes
601 Report any bugs you encountered or any wishes on our issue tracker.
602 If you’re reporting a bug, make sure to provide the following informa‐
604 tion:
605 · Information about your Operating system (e.g. Windows 8.1, Mac OSX
607 Yosemite,…). If you’re on Linux, you’ll need to specify the name of
608 the distribution and the desktop environment you’re using and whether
609 you’re using a native package or the AppImage.
610 · The music streaming service that you were using when you encountered
612 the bug if related to a specific streaming service.
613 · A clear description of the bug with steps to reproduce.
615 · You should use English to describe your issue. French is also
617 accepted.
618 · Paste the application log between triple backquotes (About > Show
620 Logs).
621 Setting up a development environment
623 Read the how to setup page of the wiki
624 Some helper scripts to setup your development environment for different
626 GNU/Linux distributions can be found in the scripts/env-setup folder.
627 We also recommend you read the architecture and the coding guidelines
629 pages before hacking on MellowPlayer.
630 Submitting a pull request
632 Here are the steps you need to follow to start working on MellowPlayer
633 and submit your work for evaluation or integration into the main
634 project:
635 1. Fork the Repo on gitlab.
637 2. Create a feature or a bugfix branch before you start coding.
639 3. Add your name to AUTHORS.md
641 4. Format the code using scripts/beautify.py (run it from the root
643 source directory).
644 5. Push to your fork and submit a pull request to the develop branch.
646 Adding support for a new service
648 Web streaming service integration plugins are now written in pure
649 javascript.
650 1. Create a new plugin using the wizard (see
652 http://mellowplayer.readthedocs.io/en/latest/developers/plugins.html#create-a-new-plugin)
653 2. Edit metadata.ini (add correct url, name, version,…)
655 3. Edit description.html to describe the streaming service
657 4. Customise logo.svg
659 5. Implement the needed functions in integration.js
661 6. Once your plugin works, submit a pull request to the develop branch.
663 Adding/Updating a new translation
665 MellowPlayer translations are hosted on transifex
666 · Create an account at transifex
668 · Go to the project’s homepage and click on the “Join the team” button
670 · If the language you want to work on does not exists yet, send us a
672 language request. Once the request has been accepted, a new transla‐
673 tion file for the requested language will be created automatically by
674 transifex.
675 · To actually start translating, go to the project’s home page on tran‐
677 sifex and click on the tr
678 · genindex
680 · modindex
682 · search
684
686 Colin Duquesnoy
687
689 2019, Colin Duquesnoy
6903.5 Nov 25, 2019 MELLOWPLAYER(1)