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 af‐
30 ter the release 1.0.
31 • adding a new service/extension should be easy: you just write a java‐
33 script 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. Flatpak
44 2. Native packages
46 Flatpak is the recommended solution as it is what the developers use
48 and test against. It contains a recent version of QtWebEngine/Chromium
49 which is essential for MellowPlayer to work correctly.
50 Native packages (especially on old/LTS distributions) may cause prob‐
52 lems as they don't provide a recent version of QtWebEngine/Chromium
53 Flatpak
55 MellowPlayer is available on flathub:
56 flatpak install flathub com.gitlab.ColinDuquesnoy.MellowPlayer
58 Native Packages
60 Fedora
61 Starting from Fedora 27, MellowPlayer is available from the official
62 stable repositories:
63 sudo dnf install mellowplayer
65 Most services require proprietary audio codecs to work. You can install
67 them from the RPMFusion repositories:
68 sudo dnf install qt5-qtwebengine-freeworld
70 ArchLinux
72 MellowPlayer is available from the AUR, install it with your favorite
73 AUR tool (e.g. yaourt).
74 yaourt -S mellowplayer
76 KaOS
78 MellowPlayer is available from KaOSx/apps repository, just run:
79 $ sudo pacman -S mellowplayer
81 Other distributions
83 Pre-compiled packages for other distributions (Ubuntu, openSUSE,...)
84 can be found on our OBS Download Page
85 Compiling from source
87 See the README for build instructions.
88 Widevine DRM Plugin
90 Many services like Spotify, Tidal and Amazon Music require the widevine
91 DRM plugin to work.
92 You can install it on GNU/Linux by running the below script (tested
94 with native packages and flatpak; make sure the binutils package is in‐
95 stalled on Debian/Ubuntu providing the ar command)
96 curl -s "https://gitlab.com/ColinDuquesnoy/MellowPlayer/-/raw/master/scripts/install-widevine.sh" | bash
98 Windows
100 Just grab the windows installer from the official website (click on the
101 Windows folder) and follow the instructions.
102 Please note the Windows Installer we provide is built with a version of
104 QtWebEngine built without proprietary codecs support (for licensing
105 reasons). If your favorite service require proprietary codecs to work,
106 you'll need to build QtWebEngine with the flag use_proprietary_codecs
107 and build MellowPlayer using that QtWebEngine version.
108 OS X
110 OSX is not officially supported anymore. You may try to build and run
111 MellowPlayer from sources.
112 Features
114 • Cross-platform (available on Windows, Mac OSX and GNU/Linux)
115 • System tray integration and notifications
117 • Mpris2 support (GNU/Linux only)
119 • Hotkeys and media player keys support
121 • Plugin based application (you can add support for a new web-based mu‐
123 sic streaming service by writing a javascript plugin)
124 • User scripts support
126 Supported Services
128 ────────────────────────────────────────────────────────────────────────────────────
129 Service GNU/Linux AppImage Windows OSx Require Require Require
130 non-free Flash DRM
131 HTML
132 codecs
133 ────────────────────────────────────────────────────────────────────────────────────
134 Deezer Yes Yes Yes Yes Optional Optional No
135 ────────────────────────────────────────────────────────────────────────────────────
136 Mixcloud Yes No No No Yes No No
137 ────────────────────────────────────────────────────────────────────────────────────
138 Soundcloud Yes No No No Yes No No
139 ────────────────────────────────────────────────────────────────────────────────────
140 Spotify Yes No No No Yes No Yes
141 ────────────────────────────────────────────────────────────────────────────────────
142 TuneIn Yes Yes Yes Yes Depends No No
143 on
144 streams
145 ────────────────────────────────────────────────────────────────────────────────────
146 8tracks Yes Yes Yes Yes Depends No No
147 on
148 streams
149 ────────────────────────────────────────────────────────────────────────────────────
150 Google Yes Yes Yes Yes ? ? ?
151 Play Music
152 ────────────────────────────────────────────────────────────────────────────────────
153 Youtube Yes Yes Yes Yes Depends No No
154 on
155 streams
156 ────────────────────────────────────────────────────────────────────────────────────
157 Tidal Yes Yes Yes Yes No Yes No
158 ────────────────────────────────────────────────────────────────────────────────────
159 Anghami Yes No No No Yes No No
160 ────────────────────────────────────────────────────────────────────────────────────
161 Pocket Yes No No No Yes No No
162 Casts
163 ────────────────────────────────────────────────────────────────────────────────────
164 HearThisAt Yes Yes Yes Yes Depends No No
165 on
166 streams
167 ────────────────────────────────────────────────────────────────────────────────────
168 Jamendo Yes Yes Yes Yes No No No
169 ────────────────────────────────────────────────────────────────────────────────────
170 Radionomy Yes Yes Yes Yes Depends No No
171 on
172 streams
173 ────────────────────────────────────────────────────────────────────────────────────
174 Wynk Yes No No No Yes No No
175 ────────────────────────────────────────────────────────────────────────────────────
176 ympd Yes Yes Yes Yes No No No
177 ┌───────────┬───────────┬──────────┬─────────┬─────┬──────────┬──────────┬─────────┐
178 │ │ │ │ │ │ │ │ │
179 │ User Scrip│ts │ │ │ │ │ │ │
180 │ With M│ellowPlayer │>= 3.1 you │have the p│ossibi│lity to use│user scrip│ts. │
181 │ │ │ │ │ │ │ │ │
182 │ This m│eans that yo│u can custo│mize the l│ook an│d feel of a│streaming │ser‐ │
183 │ vice a│s you like i│t, or simpl│y to add f│eature│s you miss.│ │ │
184 │ │ │ │ │ │ │ │ │
185 │ • D│ownload and │use differe│nt themes │ │ │ │ │
186 │ │ │ │ │ │ │ │ │
187 │ • D│ownload and │use differe│nt user sc│ripts │ │ │ │
188 │ │ │ │ │ │ │ │ │
189 │ Getting st│arted │ │ │ │ │ │ │
190 │ First star│tup │ │ │ │ │ │ │
191 │ On the│first start│up, you'll │be present│ed wit│h the fol│lowing scr│een: │
192 │ [image│] │ │ │ │ │ │ │
193 │ │ │ │ │ │ │ │ │
194 │ Just c│lick on a se│rvice to st│art runnin│g it. │ │ │ │
195 You can start multiple service at the same time and quickly switch be‐
197 tween them using Ctrl+Tab/Ctrl+Shift+Tab. You can stop a service by
198 clicking on the power button.
199 You can mark a service as a favorite by clicking on the little start
201 icon. Favorite services are available from the system tray icon and you
202 can choose to view only those services in the home page by activating
203 the switch at the top left.
204 You can also use the filter bar to look for a service by name. [image]
206 You can get back to the service selection page using F8 or the select
208 service button: [image]
209 Application Settings
211 You can change application settings by clicking on the menu button and
212 by selecting the Settings entry or by pressing F2: [image]
213 This will bring the following page: [image]
215 There are a series of settings category:
217 • General: general options
219 • Appearance: let you change the appearance of the application
221 • Notifications: let you change some notification settings
223 • Shortcuts: let you change all the application shortcuts
225 • Privacy: enable or disable privacy related options
227 • Services: list the available services and let configure them (url,
229 user scripts)
230 • Cache: a few buttons that let you clear the application cache (album
232 art covers,...) and clear the web cookies.
233 Notifications
235 By default, MellowPlayer will display a notification whenever the cur‐
236 rent track changed. [image]
237 You can change the notifications behaviour in the application settings
239 page [image]
240 and you can also quickly toggle notifications on/off using the button
242 in the toolbar: [image]
243 Listening History
245 MellowPlayer can keep track of your listens and display it in a side
246 panel. This feature is OFF by default.
247 You can see your listening history by pressing the listening history
249 button: [image]
250 Here is what the history look like: [image]
252 You can search the history and filter by service by clicking on the
254 search icon [image]
255 MPRIS2 Interface
257 Most GNU/Linux Desktop Environments have a MPRIS client interface that
258 sits in the system tray and let you control media players easily.
259 MellowPlayer implements the DBUS MPRIS 2 interface and should appear in
261 your MPRIS2 client interface:
262 • Plasma 5:
264 [image]
265 • Gnome:
267 [image]
268 • Unity:
270 [image]
271 Passing chromium flags
273 You can pass chromium flags using the QTWEBENGINE_CHROMIUM_FLAGS envi‐
274 ronemnt variable:
275 export QTWEBENGIN_CHROMIUM_FLAGS=--no-sandbox --disable-logging
277 ./MellowPlayer
278 FAQ & Known issues
280 Playback does not start on some services... What can I do?
281 For many services to work, QtWebEngine/chromium needs to be compiled
282 with support for proprietary Audio/Video codecs support (off by default
283 in official pre-compiled Qt binaries) If you have playback issues on
284 GNU/Linux, we recommend to use
285 `our flatpak`_
286 (which comes with all necessary codecs) instead of the native package
287 or the AppImage.
288 Additionally, many services (Spotify, Tidal, Netflix, Amazon Music,...)
290 use DRM and you MUST install the widevine DRM plugin.
291 Some services are not listed on Windows, is that normal?
293 Yes. The windows version of MellowPlayer is built with the official
294 pre-compiled Qt binaries wich is built without proprietary codecs. Ser‐
295 vices that requires proprietary codecs are blacklisted on Windows be‐
296 cauouse they wouldn't work with our binary distribution anyway.
297 To workaround the isseu, try the following steps:
299 1. Edit the plugin metadata file ($INSTALL_DIR/plug‐
301 ins/PLUGIN_NAME/metadata.ini) and change the support_platform value
302 to All instead of Linux
303 2. Recompile QtWebEngine from source and make sure to enable propri‐
305 etary codecs support
306 3. Replace the QtWebEngine dll supplied by the MellowPlayer installer
308 by the one you just built (or recompile MellowPlayer from source us‐
309 ing your own version of Qt)
310 4. If the service require DRM, try to find the widevinecdm dll in your
312 google chrom installation and copy it next to the MellowPlayer exe‐
313 cutable.
314 NOTE:
316 We never tried the above mentioned steps as most of us are not Win‐
317 dows users. Your contribution is welcome!
318 The application crashes at startup on GNU/Linux with open source NVIDIA
320 drivers. What can I do?
321 Qt/QML applications don't work well with the open source NVIDIA drivers
322 (nouveau). It is recommended to use the proprietary NVIDIA drivers.
323 The application crashes at startup on GNU/Linux with proprietary NVIDIA
325 drivers. What can I do?
326 Make sure you rebooted after your last NVIDIA driver update and make
327 sure to run sudo nvidia-xconfig before reporting the issue.
328 There is a message saying that the browser is not supported or outdated.
330 What can I do?
331 If you get the following (or similar) error message:
332 You are trying to sign in from a browser or app that doesn't allow us to keep your account secure.
334 Try using a different browser.
335 NOTE:
337 The message might a bit different (e.g. on Yandex, the message say
338 the browser is outdated).
339 You may want to try to spoof your user agent with the one from Fire‐
341 fox.
342 To change the user agent in MellowPlayer: Settings -> Privacy -> User
344 Agent.
345 My login credentials are lost or refused. What can I do?
347 If you're using a native version of MellowPlayer on an old distribution
348 or our AppImage chances are the Qt (especially QtWebEngine/chromium)
349 version is too old is not supported by the service you try to log in.
350 Use our flatpak instead.
352 I have a warning about broken integration plugin. What can I do?
354 Since version 3.6.0, MellowPlayer tries to detect broken plugins and
355 display a message to warn the user.
356 Here are the circumstances under which such a warning may appear:
358 • there are some unhandled exception in the intergation plugin.
360 • there is a known open issue on our issue tracker with the "broken in‐
362 tegration plugin" label.
363 • [not yet implemented] the song information is empty but the web page
365 is playing audio
366
368 Contents:
369 Coding guidelines
371 We use the llvm code formating guidelines using clang-format.
372 We made a small script that will format any C++/javascript source file
374 in the project to fit the style guidelines:
375 sh scripts/beautify.sh
377 To run this tool, you need to install the following packages:
379 • clang-format: sudo pacman -S clang
381 • jsbeautifier: sudo pip3 install jsbeautifier
383 Please, run this script before submitting a pull request!
385 See the coding guidelines wiki page for more information:
387 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/coding-guidelines
388 Project structure
390 See the architecture wiki page for more information:
391 https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/architecture
392 Plugins
394 Introduction
395 MellowPlayer can be extended by writing a streaming service integration
396 plugin.
397 A streaming service integration plugin is just a directoy that contains
399 some specific files:
400 • integration.js: the actual code that integrates the service into Mel‐
402 lowPlayer
403 • logo.svg: the logo of the service
405 • metadata.ini: plugin's metadata
407 • theme.json: optional theme definition. The colors defined in this
409 file are used through the whole user interface if theme is set to
410 adaptive.
411 The file integration.js contains a series of function that you must im‐
413 plement. Those functions will get called by the C++ application for up‐
414 dating the player state or when the user triggered an action (play,
415 pause,...).
416 MellowPlayer will look for plugins in the following directories:
418 • $CURRENT_WORKING_DIR/plugins
420 • /usr/share/mellowplayer/plugins
422 • /usr/local/share/mellowplayer/plugins
424 • ~/.local/share/MellowPlayer/plugins
426 Create a new plugin
428 This feature does not exists anymore in v2.95.0, we will be back for
429 v3.0.0
430 To create a plugin, go to the Control drop down menu or the Developer
432 main menu and click on Create plugin.
433 This will bring the following wizard: [image]
435 Fill in the details: [image]
437 When you're done, select your new plugin service in the services dialog
439 that will automatically pop out: [image]
440 Specify the supported platforms
442 When you create the plugin, you need to specify the list of supported
443 platforms. Services that require proprietary codecs to work are not
444 supported on AppImage, Windows and OSX.
445 If you are developing on GNU/Linux and want to know if you plugin will
447 work everywhere, try it from an official AppImage release. If it works,
448 you can safely check All platforms, otherwise it might only work as a
449 native package from a GNU/Linux distribution.
450 Functions to implement
452 Here is a brief description of the functions you need to implement in
453 order to integrate a new web-based streaming service.
454 update()
456 This function is called regularly to update the player information.
457 You must return a dictionnary with the following keys:
459 • playbackStatus (int): Use MellowPlayer.PlaybackStatus)*. Mandatory
461 • canSeek (bool): True if the player can seek into the current song.
463 • canGoNext (bool): True if the player can skip to the next song.
465 • canGoPrevious (bool): True if the playe can skip to the previous
467 song.
468 • canAddToFavorites (bool): True if the user can add or remove the cur‐
470 rent song from a list of favorites
471 • volume (float [0-1]): Player volume. Optional, leave it 1 if your
473 plugin cannot control the volume.
474 • songId (str): The unique id of the current song. Mandatory. Either
476 use a GUID or hash the song title if no id is available.
477 • songTitle (str): The title of the current song. Mandatory
479 • artistName (str): The name of the artist of the current. Optional.
481 • albumTitle (str): The name of the album of the current song. Op‐
483 tional.
484 • artUrl (str): The current song art url.
486 • isFavorite (bool): True if the song is in the list of the user's fa‐
488 vorite songs. Optional.
489 • duration (int [seconds]): The duration of the song, in seconds. Op‐
491 tional (but nice).
492 • position (int [seconds]): The position (or elapsed time) of the song,
494 in seconds. Optional (but nice).
495 play()
497 Starts playback.
498 pause()
500 Pauses playback.
501 goNext()
503 Skips to next song.
504 goPrevious()
506 Skips to previous song.
507 setVolume(volume)
509 Sets the player's volume.
510 volume is a float in the range [0-1].
512 addToFavorites()
514 Adds song to favorites.
515 removeFromFavorites()
517 Removes song from favorites.
518 seekToPosition(position)
520 Seeks to the specified position.
521 position is an int representing the new position inside the song (in
523 seconds).
524 PlaybackStatus
526 MellowPlayer will inject a few constants that you can use for repre‐
527 senting the current PlaybackStatus:
528 • MellowPlayer.PlaybackStatus.STOPPED: indicates that the playback has
530 stopped.
531 • MellowPlayer.PlaybackStatus.PAUSED: indicates that the playback has
533 paused.
534 • MellowPlayer.PlaybackStatus.BUFFERING: indicates that the a song is
536 buffering.
537 • MellowPlayer.PlaybackStatus.PLAYING: indicates that the a song is
539 currently playing.
540 Utility functions
542 • function getHashCode(string): returns the hash code of the specified
543 string. You can use this to generate the song id if none is available
544 via the web streaming service API.
545 • toSeconds(string) converts a time string (HH:mm:ss) to a number of
547 seconds.
548 Contributing to MellowPlayer
550 Reporting bugs or Wishes
551 Report any bugs you encountered or any wishes on our issue tracker.
552 If you’re reporting a bug, make sure to provide the following informa‐
554 tion:
555 • Information about your Operating system (e.g. Windows 8.1, Mac OSX
557 Yosemite,…). If you’re on Linux, you’ll need to specify the name of
558 the distribution and the desktop environment you’re using and whether
559 you’re using a native package or the AppImage.
560 • The music streaming service that you were using when you encountered
562 the bug if related to a specific streaming service.
563 • A clear description of the bug with steps to reproduce.
565 • You should use English to describe your issue. French is also ac‐
567 cepted.
568 • Paste the application log between triple backquotes (About > Show
570 Logs).
571 Setting up a development environment
573 Read the how to setup page of the wiki
574 Some helper scripts to setup your development environment for different
576 GNU/Linux distributions can be found in the scripts/env-setup folder.
577 We also recommend you read the architecture and the coding guidelines
579 pages before hacking on MellowPlayer.
580 Submitting a pull request
582 Here are the steps you need to follow to start working on MellowPlayer
583 and submit your work for evaluation or integration into the main
584 project:
585 1. Fork the Repo on gitlab.
587 2. Create a feature or a bugfix branch before you start coding.
589 3. Add your name to AUTHORS.md
591 4. Format the code using scripts/beautify.py (run it from the root
593 source directory).
594 5. Push to your fork and submit a pull request to the develop branch.
596 Adding support for a new service
598 Web streaming service integration plugins are now written in pure java‐
599 script.
600 1. Create a new plugin using the wizard (see
602 http://mellowplayer.readthedocs.io/en/latest/developers/plugins.html#create-a-new-plugin)
603 2. Edit metadata.ini (add correct url, name, version,…)
605 3. Edit description.html to describe the streaming service
607 4. Customise logo.svg
609 5. Implement the needed functions in integration.js
611 6. Once your plugin works, submit a pull request to the develop branch.
613 Adding/Updating a new translation
615 MellowPlayer translations are hosted on transifex
616 • Create an account at transifex
618 • Go to the project’s homepage and click on the “Join the team” button
620 • If the language you want to work on does not exists yet, send us a
622 language request. Once the request has been accepted, a new transla‐
623 tion file for the requested language will be created automatically by
624 transifex.
625 • To actually start translating, go to the project’s home page on tran‐
627 sifex and click on the tr
628 • Index
630 • Module Index
632 • Search Page
634
636 Colin Duquesnoy
637
639 2014-2023, Colin Duquesnoy
6403.6 Jul 20, 2023 MELLOWPLAYER(1)