MellowPlayer - Man Page

MellowPlayer is born from the need of a Qt-based alternative to NuvolaPlayer for the KaOS linux distribution

Here are the initial goals:

• the application should embed a web view of the music streaming service (the same as you see in a regular browser) and should provide an integration with the desktop (media keys support, global shortcuts, notifications,...).
• the application should be able to support more than 1 streaming service
• we (the core team) will only support the streaming services that we are actively using. Other services should be added and maintained by contributors. The main reason is that we won't be able to support non-free services (even those who have a trial period). Support for free services (even with limitations) might be added by the team after the release 1.0.
• adding a new service/extension should be easy: you just write a javascript plugin

This page will guide you throught the installation of MellowPlayer on the supported operating systems.

We provide several ways to install a pre-compiled version of MellowPlayer on GNU/Linux:

1. Flatpak
2. Native packages

Flatpak is the recommended solution as it is what the developers use and test against. It contains a recent version of QtWebEngine/Chromium which is essential for MellowPlayer to work correctly.

Native packages (especially on old/LTS distributions) may cause problems as they don't provide a recent version of QtWebEngine/Chromium

MellowPlayer is available on flathub:

flatpak install flathub com.gitlab.ColinDuquesnoy.MellowPlayer

Starting from Fedora 27, MellowPlayer is available from the official stable repositories:

sudo dnf install mellowplayer

Most services require proprietary audio codecs to work. You can install them from the RPMFusion repositories:

sudo dnf install qt5-qtwebengine-freeworld

MellowPlayer is available from the AUR, install it with your favorite AUR tool (e.g. yaourt).

yaourt -S mellowplayer

MellowPlayer is available from KaOSx/apps repository, just run:

$ sudo pacman -S mellowplayer

Pre-compiled packages for other distributions (Ubuntu, openSUSE,...) can be found on our OBS Download Page

See the README for build instructions.

Many services like Spotify, Tidal and Amazon Music require the widevine DRM plugin to work.

You can install it on GNU/Linux by running the below script (tested with native packages and flatpak; make sure the binutils package is installed on Debian/Ubuntu providing the ar command)

curl -s "https://gitlab.com/ColinDuquesnoy/MellowPlayer/-/raw/master/scripts/install-widevine.sh" | bash

Just grab the windows installer from the official website (click on the Windows folder) and follow the instructions.

Please note the Windows Installer we provide is built with a version of QtWebEngine built without proprietary codecs support (for licensing reasons). If your favorite service require proprietary codecs to work, you'll need to build QtWebEngine with the flag use_proprietary_codecs and build MellowPlayer using that QtWebEngine version.

OSX is not officially supported anymore. You may try to build and run MellowPlayer from sources.

• Cross-platform (available on Windows, Mac OSX and GNU/Linux)
• System tray integration and notifications
• Mpris2 support (GNU/Linux only)
• Hotkeys and media player keys support
• Plugin based application (you can add support for a new web-based music streaming service by writing a javascript plugin)
• User scripts support

With MellowPlayer >= 3.1 you have the possibility to use user scripts.

This means that you can customize the look and feel of a streaming service as you like it, or simply to add features you miss.

• Download and use different themes
• Download and use different user scripts

On the first startup, you'll be presented with the following screen: [image]

Just click on a service to start running it.

You can start multiple service at the same time and quickly switch between them using Ctrl+Tab/Ctrl+Shift+Tab. You can stop a service by clicking on the power button.

You can mark a service as a favorite by clicking on the little start icon. Favorite services are available from the system tray icon and you can choose to view only those services in the home page by activating the switch at the top left.

You can also use the filter bar to look for a service by name. [image]

You can get back to the service selection page using F8 or the select service button: [image]

You can change application settings by clicking on the menu button and by selecting the Settings entry or by pressing F2: [image]

This will bring the following page: [image]

There are a series of settings category:

• General: general options
• Appearance: let you change the appearance of the application
• Notifications: let you change some notification settings
• Shortcuts: let you change all the application shortcuts
• Privacy: enable or disable privacy related options
• Services: list the available services and let configure them (url, user scripts)
• Cache: a few buttons that let you clear the application cache (album art covers,...) and clear the web cookies.

By default, MellowPlayer will display a notification whenever the current track changed. [image]

You can change the notifications behaviour in the application settings page [image]

and you can also quickly toggle notifications on/off using the button in the toolbar: [image]

MellowPlayer can keep track of your listens and display it in a side panel. This feature is OFF by default.

You can see your listening history by pressing the listening history button: [image]

Here is what the history look like: [image]

You can search the history and filter by service by clicking on the search icon [image]

Most GNU/Linux Desktop Environments have a MPRIS client interface that sits in the system tray and let you control media players easily.

MellowPlayer implements the DBUS MPRIS 2 interface and should appear in your MPRIS2 client interface:

• Plasma 5:

[image]

• Gnome:

[image]

• Unity:

[image]

You can pass chromium flags using the QTWEBENGINE_CHROMIUM_FLAGS environemnt variable:

export QTWEBENGIN_CHROMIUM_FLAGS=--no-sandbox --disable-logging
./MellowPlayer

For many services to work, QtWebEngine/chromium needs to be compiled with support for proprietary Audio/Video codecs support (off by default in official pre-compiled Qt binaries) If you have playback issues on GNU/Linux, we recommend to use

`our flatpak`_

(which comes with all necessary codecs) instead of the native package or the AppImage.

Additionally, many services (Spotify, Tidal, Netflix, Amazon Music,...) use DRM and you MUST install the widevine DRM plugin.

Yes. The windows version of MellowPlayer is built with the official pre-compiled Qt binaries wich is built without proprietary codecs. Services that requires proprietary codecs are blacklisted on Windows becauouse they wouldn't work with our binary distribution anyway.

To workaround the isseu, try the following steps:

1.

Edit the plugin metadata file ($INSTALL_DIR/plugins/PLUGIN_NAME/metadata.ini) and change the support_platform value to All instead of Linux

2.

Recompile QtWebEngine from source and make sure to enable proprietary codecs support

3.

Replace the QtWebEngine dll supplied by the MellowPlayer installer by the one you just built (or recompile MellowPlayer from source using your own version of Qt)

4.

If the service require DRM, try to find the widevinecdm dll in your google chrom installation and copy it next to the MellowPlayer executable.

NOTE:

We never tried the above mentioned steps as most of us are not Windows users. Your contribution is welcome!

Qt/QML applications don't work well with the open source NVIDIA drivers (nouveau). It is recommended to use the proprietary NVIDIA drivers.

Make sure you rebooted after your last NVIDIA driver update and make sure to run sudo nvidia-xconfig before reporting the issue.

If you get the following (or similar) error message:

You are trying to sign in from a browser or app that doesn't allow us to keep your account secure.
Try using a different browser.

NOTE:

The message might a bit different (e.g. on Yandex, the message say the browser is outdated).

You may want to try to spoof your user agent  with the one from Firefox.

To change the user agent in MellowPlayer: Settings -> Privacy -> User Agent.

If you're using a native version of MellowPlayer on an old distribution or our AppImage chances are the Qt (especially QtWebEngine/chromium) version is too old is not supported by the service you try to log in.

Use our flatpak instead.

Since version 3.6.0, MellowPlayer tries to detect broken plugins and display a message to warn the user.

Here are the circumstances under which such a warning may appear:

• there are some unhandled exception in the intergation plugin.
• there is a known open issue on our issue tracker with the "broken integration plugin" label.
• [not yet implemented] the song information is empty but the web page is playing audio

We use the llvm code formating guidelines using clang-format.

We made a small script that will format any C++/javascript source file in the project to fit the style guidelines:

sh scripts/beautify.sh

To run this tool, you need to install the following packages:

• clang-format: sudo pacman -S clang
• jsbeautifier: sudo pip3 install jsbeautifier

Please, run this script before submitting a pull request!

See the coding guidelines wiki page for more information: https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/coding-guidelines

See the architecture wiki page for more information: https://gitlab.com/ColinDuquesnoy/MellowPlayer/wikis/architecture

MellowPlayer can be extended by writing a streaming service integration plugin.

A streaming service integration plugin is just a directoy that contains some specific files:

• integration.js: the actual code that integrates the service into MellowPlayer
• logo.svg: the logo of the service
• metadata.ini: plugin's metadata
• theme.json: optional theme definition. The colors defined in this file are used through the whole user interface if theme is set to adaptive.

The file integration.js contains a series of function that you must implement. Those functions will get called by the C++ application for updating the player state or when the user triggered an action (play, pause,...).

MellowPlayer will look for plugins in the following directories:

• $CURRENT_WORKING_DIR/plugins
• /usr/share/mellowplayer/plugins
• /usr/local/share/mellowplayer/plugins
• ~/.local/share/MellowPlayer/plugins

This feature does not exists anymore in v2.95.0, we will be back for v3.0.0

To create a plugin, go to the Control drop down menu or the Developer main menu and click on Create plugin.

This will bring the following wizard: [image]

Fill in the details: [image]

When you're done, select your new plugin service in the services dialog that will automatically pop out: [image]

When you create the plugin, you need to specify the list of supported platforms. Services that require proprietary codecs to work are not supported on AppImage, Windows and OSX.

If you are developing on GNU/Linux and want to know if you plugin will work everywhere, try it from an official AppImage release. If it works, you can safely check All platforms, otherwise it might only work as a native package from a GNU/Linux distribution.

Here is a brief description of the functions you need to implement in order to integrate a new web-based streaming service.

This function is called regularly to update the player information.

You must return a dictionnary with the following keys:

• playbackStatus (int): Use MellowPlayer.PlaybackStatus)*. Mandatory
• canSeek (bool): True if the player can seek into the current song.
• canGoNext (bool): True if the player can skip to the next song.
• canGoPrevious (bool): True if the playe can skip to the previous song.
• canAddToFavorites (bool): True if the user can add or remove the current song from a list of favorites
• volume (float [0-1]): Player volume. Optional, leave it 1 if your plugin cannot control the volume.
• songId (str): The unique id of the current song. Mandatory. Either use a GUID or hash the song title if no id is available.
• songTitle (str): The title of the current song. Mandatory
• artistName (str): The name of the artist of the current. Optional.
• albumTitle (str): The name of the album of the current song. Optional.
• artUrl (str): The current song art url.
• isFavorite (bool): True if the song is in the list of the user's favorite songs. Optional.
• duration (int [seconds]): The duration of the song, in seconds. Optional (but nice).
• position (int [seconds]): The position (or elapsed time) of the song, in seconds. Optional (but nice).

Starts playback.

Pauses playback.

Skips to next song.

Skips to previous song.

Sets the player's volume.

volume is a float in the range [0-1].

Adds song to favorites.

Removes song from favorites.

Seeks to the specified position.

position is an int representing the new position inside the song (in seconds).

MellowPlayer will inject a few constants that you can use for representing the current PlaybackStatus:

• MellowPlayer.PlaybackStatus.STOPPED: indicates that the playback has stopped.
• MellowPlayer.PlaybackStatus.PAUSED: indicates that the playback has paused.
• MellowPlayer.PlaybackStatus.BUFFERING: indicates that the a song is buffering.
• MellowPlayer.PlaybackStatus.PLAYING: indicates that the a song is currently playing.

• function getHashCode(string): returns the hash code of the specified string. You can use this to generate the song id if none is available via the web streaming service API.
• toSeconds(string) converts a time string (HH:mm:ss) to a number of seconds.

Report any bugs you encountered or any wishes on our issue tracker.

If you’re reporting a bug, make sure to provide the following information:

• Information about your Operating system (e.g. Windows 8.1, Mac OSX Yosemite,…). If you’re on Linux, you’ll need to specify the name of the distribution and the desktop environment you’re using and whether you’re using a native package or the AppImage.
• The music streaming service that you were using when you encountered the bug if related to a specific streaming service.
• A clear description of the bug with steps to reproduce.
• You should use English to describe your issue. French is also accepted.
• Paste the application log between triple backquotes (About > Show Logs).

Read the how to setup page of the wiki

Some helper scripts to setup your development environment for different GNU/Linux distributions can be found in the scripts/env-setup folder.

We also recommend you read the architecture and the coding guidelines pages before hacking on MellowPlayer.

Here are the steps you need to follow to start working on MellowPlayer and submit your work for evaluation or integration into the main project:

1. Fork the Repo on gitlab.
2. Create a feature or a bugfix branch before you start coding.
3. Add your name to AUTHORS.md
4. Format the code using scripts/beautify.py (run it from the root source directory).
5. Push to your fork and submit a pull request to the develop branch.

Web streaming service integration plugins are now written in pure javascript.

1. Create a new plugin using the wizard (see http://mellowplayer.readthedocs.io/en/latest/developers/plugins.html#create-a-new-plugin)
2. Edit metadata.ini (add correct url, name, version,…)
3. Edit description.html to describe the streaming service
4. Customise logo.svg
5. Implement the needed functions in integration.js
6. Once your plugin works, submit a pull request to the develop branch.

MellowPlayer translations are hosted on transifex

• Create an account at transifex
• Go to the project’s homepage and click on the “Join the team” button
• If the language you want to work on does not exists yet, send us a language request. Once the request has been accepted, a new translation file for the requested language will be created automatically by transifex.
• To actually start translating, go to the project’s home page on transifex and click on the tr
• Index
• Module Index
• Search Page