About
Quick start
Documentation
Requirements
What works
What is being developed
Installation
Configuration
Controls
- General
- Songs
- Playback
- Equalizer
- Misc
Troubleshooting
Credits
Changelog

Clay [beta]

Standalone command line player for Google Play Music.

This app wouldn't be possible without the wonderful gmusicapi and VLC libraries.

This project is neither affiliated nor endorsed by Google.

It's being actively developed, but is still in the early beta stage, so many features are missing and/or may be bugged.

We're on IRC!

Server: irc.oftc.net
Channel: #clay

Screenshot:

Clay Player screenshot

Click the image below to see the screencast:

Quick start

sudo apt install python-gi python-gi-cairo python3-gi python3-gi-cairo vlc keybinder python-keybinder
pip install --user clay-player
clay

Documentation

Documentation is available here.

Requirements

Python 3.x (native)
gmusicapi (PYPI)
urwid (PYPI)
PyYAML (PYPI)
libVLC (native, distributed with VLC player)
PyGObject (optional) (native, used for global X keybinds)
Keybinder (optional) (native, used for global X keybinds)
setproctitle (optional) PYPI, used to change clay process name from 'python' to 'clay')
python-dbus (optional)

What works

Audio equalizer
Caching (not for song data, that one is coming soon)
Configurable keybinds and colours
Configuration UI
Filtering results
Global hotkeys
Like/dislike tracks
Liked songs playlist
Music library browsing & management
Notifications - in-app & OSD (via DBus)
PYPI package
Playback
Playlists
Queue management
Radio stations
Song file caching
Song operations (add to library, start station etc.)
Song search
Token caching for faster authorizations

What is being developed

Artist/album display
Artist/album search
Other functionality that is supported by gmusicapi
Playlist editing

Installation

Warning: The AUR and PyPy packages called python3-keybinder will not work with Clay since you need to use the official bindings. Since Ubuntu seperated the official bindings into a different package but with the same name as the unofficial one it can cause some confusion. So if you get a Namespace Keybinder not available warning it is probably caused by this. So, for example, on Arch Linux you need the libkeybinder3 package instead.

Install Python 3, and VLC from your package manager.
Optionally, you can install PyGObject, DBus for Python and keybinder plus bindings if you want global X keybinds.

Method 1 (PyPi, automatic)

Just install the player using pip:

pip install --user clay-player
clay

Method 2 (from source, manual)

Clone the source code.

Create & activate virtualenv with system packages:

virtualenv --system-site-packages --prompt="(clay) " .env
source .env/bin/activate

Install the requirements:
```
pip install -r requirements.txt
```
Run the player:
```
./clay/app.py
```

Method 3 (in Docker)

Sometimes you want to run stuff in Docker. You can run Clay in docker as well.

There are two strict requirements:

You need to build the container by yourself (bacause of PulseAudio related paths & magic cookies.)
You must have PulseAudio running on host with module-native-protocol-tcp module enabled.

Here's how you do it:

Clone the source code
Create "~/.config/clay" directory (to have proper volume permissions in docker)
```
mkdir ~/.config/clay
```
Build & run the image
```
make run
```

You should get the sound working. Also docker will reuse the Clay config file from host (if you have one).

Configuration

Once you launch the app, use the "Settings" page to enter your login and password.
You will also need to know your Device ID. Thanks to gmusicapi, the app should display possible IDs once you enter a wrong one.
Please be aware that this app has not been tested with 2FA yet.
For people with 2FA, you can just create an app password in Google accounts page and proceed normally. (Thanks @j605)

Controls

General

<UP|DOWN|LEFT|RIGHT> - nagivate around
<ALT> + 0..9 - switch active tab

Songs

<ENTER> - play highlighted track
<CTRL> w - play/pause
<CTRL> e - play next song
<CTRL> a - append highlighted song to the queue
<CTRL> u - remove highlighted song from the queue
<CTRL> p - start station from highlighted song
<ALT> m - show context menu for this song
<ALT> u - thumb up the highlighted song
<ALT> d - thumb down the highlighted song

Playback

<CTRL> s - toggle shuffle
<CTRL> r - toggle song repeat
<SHIFT> <LEFT|RIGHT> - seek backward/forward by 5% of the song duration
<CTRL> q - seek to song beginning

Equalizer

+ - increase amplification
- - decrease amplification

Misc

<ESC> or <CTRL> / or _ - close most recent notification or popup
<CTRL> x - exit app
To filter songs just start typing words. Hit <ESC> to cancel.

X keybinds

NOTE: you need to pass the --with-x-keybinds flag for these to work

<XF86AudioPlay> - play/pause the song
<XF86AudioNext> - play the next song
<XF86AudioPrev> - play previous song

Troubleshooting

At some point, the app may fail. Possible reasons are app bugs, Google Play Music API issues, gmusicapi bugs, urwid bugs etc.

If you encounter a problem, please feel free to submit an issue. I'll try to figure it out ASAP.

Most issues can be reproduced only with specific data coming from Google Play Music servers.

Use "Debug" tab within app to select the error and hit "Enter" to copy it into clipboard. This will help me to investigate this issue.

Credits

Made by Andrew Dunai.

Regards to gmusicapi and VLC who made this possible.

People who contribute to this project: