1MELLOWPLAYER(1)                  MellowPlayer                  MELLOWPLAYER(1)
2
3
4

NAME

6       mellowplayer - MellowPlayer Documentation [image]
7

USER DOCUMENTATION

9       Contents:
10
11   About MellowPlayer
12       MellowPlayer  is  born  from  the  need  of  a  Qt-based alternative to
13       NuvolaPlayer for the KaOS linux distribution
14
15       Here are the initial goals:
16
17       • 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
22       • the  application should be able to support more than 1 streaming ser‐
23         vice
24
25       • 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
32       • adding a new service/extension should be easy: you just write a java‐
33         script plugin
34
35   Installation
36       This page will guide you throught the installation of  MellowPlayer  on
37       the supported operating systems.
38
39   GNU/Linux
40       We  provide  several  ways to install a pre-compiled version of Mellow‐
41       Player on GNU/Linux:
42
43       1. Flatpak
44
45       2. Native packages
46
47       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
51       Native packages (especially on old/LTS distributions) may  cause  prob‐
52       lems as they don't provide a recent version of QtWebEngine/Chromium
53
54   Flatpak
55       MellowPlayer is available on flathub:
56
57          flatpak install flathub com.gitlab.ColinDuquesnoy.MellowPlayer
58
59   Native Packages
60   Fedora
61       Starting  from  Fedora  27, MellowPlayer is available from the official
62       stable repositories:
63
64          sudo dnf install mellowplayer
65
66       Most services require proprietary audio codecs to work. You can install
67       them from the RPMFusion repositories:
68
69          sudo dnf install qt5-qtwebengine-freeworld
70
71   ArchLinux
72       MellowPlayer  is  available from the AUR, install it with your favorite
73       AUR tool (e.g. yaourt).
74
75          yaourt -S mellowplayer
76
77   KaOS
78       MellowPlayer is available from KaOSx/apps repository, just run:
79
80          $ sudo pacman -S mellowplayer
81
82   Other distributions
83       Pre-compiled packages for other  distributions  (Ubuntu,  openSUSE,...)
84       can be found on our OBS Download Page
85
86   Compiling from source
87       See the README for build instructions.
88
89   Widevine DRM Plugin
90       Many services like Spotify, Tidal and Amazon Music require the widevine
91       DRM plugin to work.
92
93       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
97          curl -s "https://gitlab.com/ColinDuquesnoy/MellowPlayer/-/raw/master/scripts/install-widevine.sh" | bash
98
99   Windows
100       Just grab the windows installer from the official website (click on the
101       Windows folder) and follow the instructions.
102
103       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
109   OS X
110       OSX  is  not officially supported anymore. You may try to build and run
111       MellowPlayer from sources.
112
113   Features
114       • Cross-platform (available on Windows, Mac OSX and GNU/Linux)
115
116       • System tray integration and notifications
117
118       • Mpris2 support (GNU/Linux only)
119
120       • Hotkeys and media player keys support
121
122       • Plugin based application (you can add support for a new web-based mu‐
123         sic streaming service by writing a javascript plugin)
124
125       • User scripts support
126
127   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 │           │           │          │         │     │          │          │         │
179User 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 │           │           │          │         │     │          │          │         │
189Getting st│arted       │          │         │     │          │          │         │
190First 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
196       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
200       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
205       You can also use the filter bar to look for a service by name.  [image]
206
207       You can get back to the service selection page using F8 or  the  select
208       service button: [image]
209
210   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
214       This will bring the following page: [image]
215
216       There are a series of settings category:
217
218       • General: general options
219
220       • Appearance: let you change the appearance of the application
221
222       • Notifications: let you change some notification settings
223
224       • Shortcuts: let you change all the application shortcuts
225
226       • Privacy: enable or disable privacy related options
227
228       • Services: list the available services and let  configure  them  (url,
229         user scripts)
230
231       • Cache:  a few buttons that let you clear the application cache (album
232         art covers,...) and clear the web cookies.
233
234   Notifications
235       By default, MellowPlayer will display a notification whenever the  cur‐
236       rent track changed.  [image]
237
238       You  can change the notifications behaviour in the application settings
239       page [image]
240
241       and you can also quickly toggle notifications on/off using  the  button
242       in the toolbar: [image]
243
244   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
248       You can see your listening history by pressing  the  listening  history
249       button: [image]
250
251       Here is what the history look like: [image]
252
253       You  can  search  the  history and filter by service by clicking on the
254       search icon [image]
255
256   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
260       MellowPlayer implements the DBUS MPRIS 2 interface and should appear in
261       your MPRIS2 client interface:
262
263       • Plasma 5:
264       [image]
265
266       • Gnome:
267       [image]
268
269       • Unity:
270       [image]
271
272   Passing chromium flags
273       You can pass chromium flags using the QTWEBENGINE_CHROMIUM_FLAGS  envi‐
274       ronemnt variable:
275
276          export QTWEBENGIN_CHROMIUM_FLAGS=--no-sandbox --disable-logging
277          ./MellowPlayer
278
279   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
289       Additionally, many services (Spotify, Tidal, Netflix, Amazon Music,...)
290       use DRM and you MUST install the widevine DRM plugin.
291
292   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
298       To workaround the isseu, try the following steps:
299
300       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
304       2. Recompile  QtWebEngine  from  source and make sure to enable propri‐
305          etary codecs support
306
307       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
311       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
315       NOTE:
316          We never tried the above mentioned steps as most of us are not  Win‐
317          dows users. Your contribution is welcome!
318
319   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
324   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
329   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
333          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
336       NOTE:
337          The message might a bit different (e.g. on Yandex, the  message  say
338          the browser is outdated).
339
340       You  may  want to try to spoof your user agent  with the one from Fire‐
341       fox.
342
343       To change the user agent in MellowPlayer: Settings -> Privacy  ->  User
344       Agent.
345
346   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
351       Use our flatpak instead.
352
353   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
357       Here are the circumstances under which such a warning may appear:
358
359       • there are some unhandled exception in the intergation plugin.
360
361       • there is a known open issue on our issue tracker with the "broken in‐
362         tegration plugin" label.
363
364       • [not  yet implemented] the song information is empty but the web page
365         is playing audio
366

DEVELOPER DOCUMENTATION

368       Contents:
369
370   Coding guidelines
371       We use the llvm code formating guidelines using clang-format.
372
373       We made a small script that will format any C++/javascript source  file
374       in the project to fit the style guidelines:
375
376          sh scripts/beautify.sh
377
378       To run this tool, you need to install the following packages:
379
380clang-format: sudo pacman -S clang
381
382jsbeautifier: sudo pip3 install jsbeautifier
383
384       Please, run this script before submitting a pull request!
385
386       See   the   coding   guidelines   wiki   page   for  more  information:
387       https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/coding-guidelines
388
389   Project structure
390       See   the   architecture    wiki    page    for    more    information:
391       https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/architecture
392
393   Plugins
394   Introduction
395       MellowPlayer can be extended by writing a streaming service integration
396       plugin.
397
398       A streaming service integration plugin is just a directoy that contains
399       some specific files:
400
401integration.js: the actual code that integrates the service into Mel‐
402         lowPlayer
403
404logo.svg: the logo of the service
405
406metadata.ini: plugin's metadata
407
408theme.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
412       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
417       MellowPlayer will look for plugins in the following directories:
418
419$CURRENT_WORKING_DIR/plugins
420
421/usr/share/mellowplayer/plugins
422
423/usr/local/share/mellowplayer/plugins
424
425~/.local/share/MellowPlayer/plugins
426
427   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
431       To create a plugin, go to the Control drop down menu or  the  Developer
432       main menu and click on Create plugin.
433
434       This will bring the following wizard: [image]
435
436       Fill in the details: [image]
437
438       When you're done, select your new plugin service in the services dialog
439       that will automatically pop out: [image]
440
441   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
446       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
451   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
455   update()
456       This function is called regularly to update the player information.
457
458       You must return a dictionnary with the following keys:
459
460playbackStatus (int): Use MellowPlayer.PlaybackStatus)*. Mandatory
461
462canSeek (bool): True if the player can seek into the current song.
463
464canGoNext (bool): True if the player can skip to the next song.
465
466canGoPrevious (bool): True if the playe  can  skip  to  the  previous
467         song.
468
469canAddToFavorites (bool): True if the user can add or remove the cur‐
470         rent song from a list of favorites
471
472volume (float [0-1]): Player volume. Optional, leave  it  1  if  your
473         plugin cannot control the volume.
474
475songId  (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
478songTitle (str): The title of the current song. Mandatory
479
480artistName (str): The name of the artist of the current. Optional.
481
482albumTitle (str): The name of the album  of  the  current  song.  Op‐
483         tional.
484
485artUrl (str): The current song art url.
486
487isFavorite  (bool): True if the song is in the list of the user's fa‐
488         vorite songs. Optional.
489
490duration (int [seconds]): The duration of the song, in  seconds.  Op‐
491         tional (but nice).
492
493position (int [seconds]): The position (or elapsed time) of the song,
494         in seconds. Optional (but nice).
495
496   play()
497       Starts playback.
498
499   pause()
500       Pauses playback.
501
502   goNext()
503       Skips to next song.
504
505   goPrevious()
506       Skips to previous song.
507
508   setVolume(volume)
509       Sets the player's volume.
510
511       volume is a float in the range [0-1].
512
513   addToFavorites()
514       Adds song to favorites.
515
516   removeFromFavorites()
517       Removes song from favorites.
518
519   seekToPosition(position)
520       Seeks to the specified position.
521
522       position is an int representing the new position inside  the  song  (in
523       seconds).
524
525   PlaybackStatus
526       MellowPlayer  will  inject  a few constants that you can use for repre‐
527       senting the current PlaybackStatus:
528
529MellowPlayer.PlaybackStatus.STOPPED: indicates that the playback  has
530         stopped.
531
532MellowPlayer.PlaybackStatus.PAUSED:  indicates  that the playback has
533         paused.
534
535MellowPlayer.PlaybackStatus.BUFFERING: indicates that the a  song  is
536         buffering.
537
538MellowPlayer.PlaybackStatus.PLAYING:  indicates  that  the  a song is
539         currently playing.
540
541   Utility functions
542function 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
546toSeconds(string) converts a time string (HH:mm:ss) to  a  number  of
547         seconds.
548
549   Contributing to MellowPlayer
550   Reporting bugs or Wishes
551       Report any bugs you encountered or any wishes on our issue tracker.
552
553       If  you’re reporting a bug, make sure to provide the following informa‐
554       tion:
555
556       • 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
561       • The  music streaming service that you were using when you encountered
562         the bug if related to a specific streaming service.
563
564       • A clear description of the bug with steps to reproduce.
565
566       • You should use English to describe your issue.  French  is  also  ac‐
567         cepted.
568
569       • Paste  the  application  log  between triple backquotes (About > Show
570         Logs).
571
572   Setting up a development environment
573       Read the how to setup page of the wiki
574
575       Some helper scripts to setup your development environment for different
576       GNU/Linux distributions can be found in the scripts/env-setup folder.
577
578       We  also  recommend you read the architecture and the coding guidelines
579       pages before hacking on MellowPlayer.
580
581   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
586       1. Fork the Repo on gitlab.
587
588       2. Create a feature or a bugfix branch before you start coding.
589
590       3. Add your name to AUTHORS.md
591
592       4. Format the code using scripts/beautify.py  (run  it  from  the  root
593          source directory).
594
595       5. Push to your fork and submit a pull request to the develop branch.
596
597   Adding support for a new service
598       Web streaming service integration plugins are now written in pure java‐
599       script.
600
601       1. Create    a     new     plugin     using     the     wizard     (see
602          http://mellowplayer.readthedocs.io/en/latest/developers/plugins.html#create-a-new-plugin)
603
604       2. Edit metadata.ini (add correct url, name, version,…)
605
606       3. Edit description.html to describe the streaming service
607
608       4. Customise logo.svg
609
610       5. Implement the needed functions in integration.js
611
612       6. Once your plugin works, submit a pull request to the develop branch.
613
614   Adding/Updating a new translation
615       MellowPlayer translations are hosted on transifex
616
617       • Create an account at transifex
618
619       • Go to the project’s homepage and click on the “Join the team” button
620
621       • 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
626       • To actually start translating, go to the project’s home page on tran‐
627         sifex and click on the tr
628
629Index
630
631Module Index
632
633Search Page
634

AUTHOR

636       Colin Duquesnoy
637
639       2014-2023, Colin Duquesnoy
640
641
642
643
6443.6                              Jul 20, 2023                  MELLOWPLAYER(1)
Impressum