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 18.04
104 Before installing MellowPlayer, make sure the universe repository is
105 enabled:
106 sudo add-apt-repository universe
108 Install procedure:
110 sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/ColinDuquesnoy/xUbuntu_18.04/ /' > /etc/apt/sources.list.d/mellowplayer.list"
112 wget -nv https://download.opensuse.org/repositories/home:ColinDuquesnoy/xUbuntu_18.04/Release.key -O Release.key
113 sudo apt-key add - < Release.key
114 sudo apt update
115 sudo apt install mellowplayer
116 Ubuntu 18.10
118 Before installing MellowPlayer, make sure the universe repository is
119 enabled:
120 sudo add-apt-repository universe
122 Install procedure:
124 sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/ColinDuquesnoy/xUbuntu_18.10/ /' > /etc/apt/sources.list.d/mellowplayer.list"
126 wget -nv https://download.opensuse.org/repositories/home:ColinDuquesnoy/xUbuntu_18.10/Release.key -O Release.key
127 sudo apt-key add - < Release.key
128 sudo apt update
129 sudo apt install mellowplayer
130 ArchLinux
132 MellowPlayer is available from the AUR, install it with your favorite
133 AUR tool (e.g. yaourt).
134 yaourt -S mellowplayer
136 openSUSE Leap 15
138 Use the openSUSE build service web interface or install manually:
139 zypper addrepo https://download.opensuse.org/repositories/home:ColinDuquesnoy/openSUSE_Leap_15.0/home:ColinDuquesnoy.repo
141 zypper refresh
142 zypper install MellowPlayer
143 openSUSE Tumbleweed
145 Use the openSUSE build service web interface or install manually:
146 zypper addrepo http://download.opensuse.org/repositories/home:ColinDuquesnoy/openSUSE_Tumbleweed/home:ColinDuquesnoy.repo
148 zypper refresh
149 zypper install MellowPlayer
150 KaOS
152 MellowPlayer is available from KaOSx/apps repository, just run:
153 $ sudo pacman -S mellowplayer
155 Flatpak
157 MellowPlayer's flatpak is not yet available on flathub but you can
158 download and install a single file bundle:
159 1. Download the flatpak from our bintray repository
161 2. Install the flatpak: flatpak install ./MellowPlayer.flatpak
163 3. Run the flatpak from your application menu or from command line:
165 flatpak run com.gitlab.ColinDuquesnoy.MellowPlayer
166 AppImage
168 1. Download the AppImage from our bintray repository
169 2. Make it executable: chmod +x ./MellowPlayer.AppImage
171 3. Run it: ./MellowPlayer.AppImage
173 Compiling from source
175 See the README for build instructions.
176 Windows
178 Just grab the windows installer from the official website (click on the
179 Windows folder) and follow the instructions.
180 Please note the Windows Installer we provide is built with a version of
182 QtWebEngine built without proprietary codecs support (for licensing
183 reasons). If your favorite service require proprietary codecs to work,
184 you'll need to build QtWebEngine with the flag use_proprietary_codecs
185 and build MellowPlayer using that QtWebEngine version.
186 OS X
188 OSX is not officially supported anymore. You may try to build and run
189 MellowPlayer from sources.
190 Features
192 · Cross-platform (available on Windows, Mac OSX and GNU/Linux)
193 · System tray integration and notifications
195 · Mpris2 support (GNU/Linux only)
197 · Hotkeys and media player keys support
199 · Plugin based application (you can add support for a new web-based
201 music streaming service by writing a javascript plugin)
202 · User scripts support
204 Supported Services
206 ┌───────────┬───────────┬──────────┬─────────┬─────┬──────────┬──────────┬─────────┐
207 │Service │ GNU/Linux │ AppImage │ Windows │ OSx │ Require │ Require │ Require │
208 │ │ │ │ │ │ non-free │ Flash │ DRM │
209 │ │ │ │ │ │ HTML │ │ │
210 │ │ │ │ │ │ codecs │ │ │
211 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
212 │Deezer │ Yes │ Yes │ Yes │ Yes │ Optional │ Optional │ No │
213 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
214 │Mixcloud │ Yes │ No │ No │ No │ Yes │ No │ No │
215 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
216 │Soundcloud │ Yes │ No │ No │ No │ Yes │ No │ No │
217 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
218 │Spotify │ Yes │ No │ No │ No │ Yes │ No │ Yes │
219 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
220 │TuneIn │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
221 │ │ │ │ │ │ on │ │ │
222 │ │ │ │ │ │ streams │ │ │
223 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
224 │8tracks │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
225 │ │ │ │ │ │ on │ │ │
226 │ │ │ │ │ │ streams │ │ │
227 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
228 │Google │ Yes │ Yes │ Yes │ Yes │ ? │ ? │ ? │
229 │Play Music │ │ │ │ │ │ │ │
230 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
231 │Youtube │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
232 │ │ │ │ │ │ on │ │ │
233 │ │ │ │ │ │ streams │ │ │
234 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
235 │Tidal │ Yes │ Yes │ Yes │ Yes │ No │ Yes │ No │
236 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
237 │Anghami │ Yes │ No │ No │ No │ Yes │ No │ No │
238 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
239 │Pocket │ Yes │ No │ No │ No │ Yes │ No │ No │
240 │Casts │ │ │ │ │ │ │ │
241 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
242 │HearThisAt │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
243 │ │ │ │ │ │ on │ │ │
244 │ │ │ │ │ │ streams │ │ │
245 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
246 │Jamendo │ Yes │ Yes │ Yes │ Yes │ No │ No │ No │
247 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
248 │Radionomy │ Yes │ Yes │ Yes │ Yes │ Depends │ No │ No │
249 │ │ │ │ │ │ on │ │ │
250 │ │ │ │ │ │ streams │ │ │
251 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
252 │Wynk │ Yes │ No │ No │ No │ Yes │ No │ No │
253 ├───────────┼───────────┼──────────┼─────────┼─────┼──────────┼──────────┼─────────┤
254 │ympd │ Yes │ Yes │ Yes │ Yes │ No │ No │ No │
255 └───────────┴───────────┴──────────┴─────────┴─────┴──────────┴──────────┴─────────┘
256 User Scripts
258 With MellowPlayer >= 3.1 you have the possibility to use user scripts.
259 This means that you can customize the look and feel of a streaming ser‐
261 vice as you like it, or simply to add features you miss.
262 · Download and use different themes
264 · Download and use different user scripts
266 Getting started
268 First startup
269 On the first startup, you'll be presented with the following screen:
270 [image]
271 Just click on a service to start running it. You can start multiple
273 service at the same time and quickly switch between them using
274 Ctrl+Tab/Ctrl+Shift+Tab. [image]
275 You can get back to the service selection page using F8 or the select
277 service button: [image]
278 Application Settings
280 You can change application settings by clicking on the menu button and
281 by selecting the Settings entry or by pressing F2: [image]
282 This will bring the following page: [image]
284 There are a series of settings category:
286 · General: general options
288 · Appearance: let you change the appearance of the application
290 · Notifications: let you change some notification settings
292 · Shortcuts: let you change all the application shortcuts
294 · Privacy: enable or disable privacy related options
296 · Services: list the available services and let configure them (url,
298 user scripts)
299 · Cache: a few buttons that let you clear the application cache (album
301 art covers,...) and clear the web cookies.
302 Notifications
304 By default, MellowPlayer will display a notification whenever the cur‐
305 rent track changed. [image]
306 You can change the notifications behaviour in the application settings
308 page [image]
309 and you can also quickly toggle notifications on/off using the button
311 in the toolbar: [image]
312 Listening History
314 MellowPlayer can keep track of your listens and display it in a side
315 panel. This feature is OFF by default.
316 You can see your listening history by pressing the listening history
318 button: [image]
319 Here is what the history look like: [image]
321 You can search the history and filter by service by clicking on the
323 search icon [image]
324 MPRIS2 Interface
326 Most GNU/Linux Desktop Environments have a MPRIS client interface that
327 sits in the system tray and let you control media players easily.
328 MellowPlayer implements the DBUS MPRIS 2 interface and should appear in
330 your MPRIS2 client interface:
331 · Plasma 5:
333 [image]
334 · Gnome:
336 [image]
337 · Unity:
339 [image]
340 FAQ & Known issues
342 Playback does not start on some services such as Soundcloud or Mixcloud...
343 What can I do?
344 Services that don't use flash often requires proprietary audio codecs
345 to be installed on your system. Those codecs are not included in our
346 official releases (AppImage and Windows Installer).
347 To solve the problem, you need to build MellowPlayer and Qt from
349 sources and make sure you enable propertietary codecs support, see
350 https://doc.qt.io/qt-5.11/qtwebengine-features.html#audio-and-video-codecs
351 If you're using GNU/Linux, check if a native package of MellowPlayer is
353 available for your distribution and use it instead of AppImage. Native
354 packages usually use system ffmpeg and it should be enought to install
355 extra ffmpeg plugins for the missing proprietary codecs.
356 NOTE:
358 MP3 is still considered as a proprietary/patented codec prior to Qt
359 5.11.
360 NOTE:
362 Services that require proprietary codecs are included in our offi‐
363 cial releases but won't appear in the application.
364 The application crashes at startup on GNU/Linux with open source NVIDIA
366 drivers. What can I do?
367 Qt/QML applications don't work well with the open source NVIDIA drivers
368 (nouveau). It is recommended to use the proprietary NVIDIA drivers.
369 The application crashes at startup on GNU/Linux with proprietary NVIDIA
371 drivers. What can I do?
372 Make sure you rebooted after your last NVIDIA driver update and make
373 sure to run sudo nvidia-xconfig before reporting the issue.
374 There is no music playback on Spotify. What can I do?
376 Make sure you have installed both the proprietary audio codecs (ffmpeg
377 with extra codecs) and the widevine DRM plugin. The DRM plugin can be
378 extracted from chromium binary archive:
379 wget https://archive.archlinux.org/packages/c/chromium/chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
381 wget https://dl.google.com/widevine-cdm/1.4.8.1008-linux-x64.zip
382 tar -xvf chromium-61.0.3163.100-1-x86_64.pkg.tar.xz
383 unzip 1.4.8.1008-linux-x64.zip
384 sudo mkdir /usr/lib/chromium
386 sudo cp libwidevinecdm.so /usr/lib/chromium
387 sudo cp ./usr/lib/chromium/libwidevinecdmadapter.so /usr/lib/chromium
388 sudo chmod 644 /usr/lib/chromium/libwidevinecdm.so
389 sudo chmod 644 /usr/lib/chromium/libwidevinecdmadapter.so
390
392 Contents:
393 Coding guidelines
395 We use the llvm code formating guidelines using clang-format.
396 We made a small script that will format any C++/javascript source file
398 in the project to fit the style guidelines:
399 sh scripts/beautify.sh
401 To run this tool, you need to install the following packages:
403 · clang-format: sudo pacman -S clang
405 · jsbeautifier: sudo pip3 install jsbeautifier
407 Please, run this script before submitting a pull request!
409 See the coding guidelines wiki page for more information:
411 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/coding-guidelines
412 Project structure
414 See the architecture wiki page for more information:
415 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/architecture
416 Plugins
418 Introduction
419 MellowPlayer can be extended by writing a streaming service integration
420 plugin.
421 A streaming service integration plugin is just a directoy that contains
423 some specific files:
424 · integration.js: the actual code that integrates the service into Mel‐
426 lowPlayer
427 · logo.svg: the logo of the service
429 · metadata.ini: plugin's metadata
431 · theme.json: optional theme definition. The colors defined in this
433 file are used through the whole user interface if theme is set to
434 adaptive.
435 The file integration.js contains a series of function that you must
437 implement. Those functions will get called by the C++ application for
438 updating the player state or when the user triggered an action (play,
439 pause,...).
440 MellowPlayer will look for plugins in the following directories:
442 · $CURRENT_WORKING_DIR/plugins
444 · /usr/share/mellowplayer/plugins
446 · /usr/local/share/mellowplayer/plugins
448 · ~/.local/share/MellowPlayer/plugins
450 Create a new plugin
452 This feature does not exists anymore in v2.95.0, we will be back for
453 v3.0.0
454 To create a plugin, go to the Control drop down menu or the Developer
456 main menu and click on Create plugin.
457 This will bring the following wizard: [image]
459 Fill in the details: [image]
461 When you're done, select your new plugin service in the services dialog
463 that will automatically pop out: [image]
464 Specify the supported platforms
466 When you create the plugin, you need to specify the list of supported
467 platforms. Services that require proprietary codecs to work are not
468 supported on AppImage, Windows and OSX.
469 If you are developing on GNU/Linux and want to know if you plugin will
471 work everywhere, try it from an official AppImage release. If it works,
472 you can safely check All platforms, otherwise it might only work as a
473 native package from a GNU/Linux distribution.
474 Functions to implement
476 Here is a brief description of the functions you need to implement in
477 order to integrate a new web-based streaming service.
478 update()
480 This function is called regularly to update the player information.
481 You must return a dictionnary with the following keys:
483 · playbackStatus (int): Use mellowplayer.PlaybackStatus)*. Mandatory
485 · canSeek (bool): True if the player can seek into the current song.
487 · canGoNext (bool): True if the player can skip to the next song.
489 · canGoPrevious (bool): True if the playe can skip to the previous
491 song.
492 · canAddToFavorites (bool): True if the user can add or remove the cur‐
494 rent song from a list of favorites
495 · volume (float [0-1]): Player volume. Optional, leave it 1 if your
497 plugin cannot control the volume.
498 · songId (str): The unique id of the current song. Mandatory. Either
500 use a GUID or hash the song title if no id is available.
501 · songTitle (str): The title of the current song. Mandatory
503 · artistName (str): The name of the artist of the current. Optional.
505 · albumTitle (str): The name of the album of the current song.
507 Optional.
508 · artUrl (str): The current song art url.
510 · isFavorite (bool): True if the song is in the list of the user's
512 favorite songs. Optional.
513 · duration (int [seconds]): The duration of the song, in seconds.
515 Optional (but nice).
516 · position (int [seconds]): The position (or elapsed time) of the song,
518 in seconds. Optional (but nice).
519 play()
521 Starts playback.
522 pause()
524 Pauses playback.
525 goNext()
527 Skips to next song.
528 goPrevious()
530 Skips to previous song.
531 setVolume(volume)
533 Sets the player's volume.
534 volume is a float in the range [0-1].
536 addToFavorites()
538 Adds song to favorites.
539 removeFromFavorites()
541 Removes song from favorites.
542 seekToPosition(position)
544 Seeks to the specified position.
545 position is an int representing the new position inside the song (in
547 seconds).
548 PlaybackStatus
550 MellowPlayer will inject a few constants that you can use for repre‐
551 senting the current PlaybackStatus:
552 · mellowplayer.PlaybackStatus.STOPPED: indicates that the playback has
554 stopped.
555 · mellowplayer.PlaybackStatus.PAUSED: indicates that the playback has
557 paused.
558 · mellowplayer.PlaybackStatus.BUFFERING: indicates that the a song is
560 buffering.
561 · mellowplayer.PlaybackStatus.PLAYING: indicates that the a song is
563 currently playing.
564 Utility functions
566 · function getHashCode(string): returns the hash code of the specified
567 string. You can use this to generate the song id if none is available
568 via the web streaming service API.
569 · toSeconds(string) converts a time string (HH:mm:ss) to a number of
571 seconds.
572 Contributing to MellowPlayer
574 Reporting bugs or Wishes
575 Report any bugs you encountered or any wishes on our issue tracker.
576 If you’re reporting a bug, make sure to provide the following informa‐
578 tion:
579 · Information about your Operating system (e.g. Windows 8.1, Mac OSX
581 Yosemite,…). If you’re on Linux, you’ll need to specify the name of
582 the distribution and the desktop environment you’re using and whether
583 you’re using a native package or the AppImage.
584 · The music streaming service that you were using when you encountered
586 the bug if related to a specific streaming service.
587 · A clear description of the bug with steps to reproduce.
589 · You should use English to describe your issue. French is also
591 accepted.
592 · Paste the application log between triple backquotes (About > Show
594 Logs).
595 Setting up a development environment
597 Read the how to setup page of the wiki
598 We also recommend you read the architecture and the coding guidelines
600 pages before hacking on MellowPlayer.
601 Submitting a pull request
603 Here are the steps you need to follow to start working on MellowPlayer
604 and submit your work for evaluation or integration into the main
605 project:
606 1. Fork the Repo on gitlab.
608 2. Create a feature or a bugfix branch before you start coding.
610 3. Add your name to AUTHORS.md
612 4. Format the code using scripts/beautify.py (run it from the root
614 source directory).
615 5. Push to your fork and submit a pull request to the develop branch.
617 Adding support for a new service
619 Web streaming service integration plugins are now written in pure
620 javascript.
621 1. Create a new plugin using the wizard (see
623 http://mellowplayer.readthedocs.io/en/latest/developers/plugins.html#create-a-new-plugin)
624 2. Edit metadata.ini (add correct url, name, version,…)
626 3. Edit description.html to describe the streaming service
628 4. Customise logo.svg
630 5. Implement the needed functions in integration.js
632 6. Once your plugin works, submit a pull request to the develop branch.
634 Adding/Updating a new translation
636 MellowPlayer translations are hosted on transifex
637 · Create an account at transifex
639 · Go to the project’s homepage and click on the “Join the team” button
641 · If the language you want to work on does not exists yet, send us a
643 language request. Once the request has been accepted, a new transla‐
644 tion file for the requested language will be created automatically by
645 transifex.
646 · To actually start translating, go to the project’s home page on tran‐
648 sifex and click on the tr
649 · genindex
651 · modindex
653 · search
655
657 Colin Duquesnoy
658
660 2015, Colin Duquesnoy
6613.5 May 28, 2019 MELLOWPLAYER(1)