Welcome to kmpc’s documentation!¶
Readme¶
About kmpc¶
kmpc is a Kivy-based mpd client, primarily meant for use on a Raspberry Pi paired with the official 7” touchscreen mounted in a car. Using a combination of a fast-booting distro with Kivy installed (such as KivyPie), it is possible to have music playing in a few seconds after boot, and a GUI touch interface ready to use in a few seconds more. kmpc is meant to run directly on the framebuffer, with no need for X.
Full documentation can be found on ReadTheDocs.
Runtime requirements¶
kmpc depends on the following python packages:
- Kivy
- Twisted
- mutagen
- musicbrainzngs
- Pillow
- rpi-backlight (if you want to control the backlight on a Raspberry Pi touchscreen)
In addition, there must be an mpd server running that kmpc can connect to via TCP.
Installation¶
Install from PyPi¶
pip install kmpc
This should install all dependencies, although you may have trouble if you
haven’t gotten Kivy set up properly first. Kivy needs a bunch of different
libraries installed to support various hardware, so if you are, say, installing
this on a Mac, you’ll probably want to make sure Kivy is working before
installing kmpc. Two executables, kmpc
and kmpcmanager
will be
installed.
If you want to control the backlight on the touchscreen, the following will install dependencies for that:
pip install kmpc[rpi]
Install from source¶
First, make sure Kivy is up and running. I recommend installing KivyPie if you are running this on a Pi as it already has Kivy ready to go. You can also simply run:
pip install kivy
and hope for the best. Next, install the other dependencies:
pip install Twisted
pip install mutagen
pip install musicbrainzngs
pip install pillow
If you want to control the backlight on the Pi touchscreen, install this dependency as well:
pip install rpi_backlight
This should be all you need to run the python code directly. There are two
convenience scripts in the source directory, runkmpc
and
runkmpcmanager
, which should allow you to run the programs directly from
the git checkout. Once you are satisfied that is working, you can install by
running python setup.py install
, which will install the kmpc
and
kmpcmanager
executables.
Invocation¶
kmpc¶
This is the main program, accessed by either running kmpc
from an installed
package or ./runkmpc
from within the root of the git repo. It depends on a
configuration directory (~/.kmpc
) and a config file
(~/.kmpc/config.ini
) that will be automatically created at first run. You
will need to edit this config file to add the correct values for various
variables. The following commandline options are accepted, as well as all the
default Kivy options:
usage: kmpc [-h] [-q] [-d] [-n] [-V] [--helpkivy]
optional arguments:
-h, --help show this help message and exit
-q, --quiet only print errors to console log
-d, --debug print debug messages to console log
-n, --newconfig write out default config file if it doesn't exist yet
-V, --version print version number and exit
--helpkivy Print Kivy's built-in argument list
--sync {all,music,fanart,exportratings,importratings}
run the 'sync' function with the chosen module
and exit
kmpcmanager¶
This is the synchost manager program, accessed by either running
kmpcmanager
from an installed package or ./runkmpcmanager
from within
the root of the git repo. The synchost is a computer running at home that has
all the music and mpd running on it, as well as all the fanart. kmpcmanager
provides an interface for downloading fanart for all files in mpd, setting up
an rsync file to sync with, and changing song ratings and copy flags. This also
depends on the config folder and file. The following commandline options are
accepted, as well as all the default Kivy options:
usage: kmpcmanager [-h] [-q] [-d] [-n] [-V] [--helpkivy]
optional arguments:
-h, --help show this help message and exit
-q, --quiet only print errors to console log
-d, --debug print debug messages to console log
-n, --newconfig write out default config file if it doesn't exist yet
-V, --version print version number and exit
--helpkivy Print Kivy's built-in argument list
config file ~/.kmpc/config.ini
¶
This file contains several sections, and must be customized for your use. It
will be created with default values the first time kmpc
or kmpcmanager
are run, or you may pass the -n/–newconfig flag to either program to create
the config file only. Several fields are used by only one or the other, and
are described as such below.
[mpd] section¶
kmpc-only¶
- mpdhost
- Hostname or IP address that mpd is running on.
- mpdport
- Port that mpd is running on.
[paths] section¶
kmpc-only¶
- musicpath
- Path to the folder containing music. This should be the same file tree that the mpd server connected above uses. kmpc uses direct file access to pull things like album art and extra id3 tags from the files.
- fanartpath
- Path to the folder containing fanart. The directory structure for this folder is explained in another section.
- tmppath
- Where temporary files should be written.
[sync] section¶
- synchost
- Hostname or IP address of a host to sync with. This is useful if you have a
main mpd server running at home and want to sync songs/ratings/fanart to your
car. The
kmpcmanager
program is used to manage this synchost.kmpc
uses this as a host to ssh to for syncing.kmpcmanager
uses this as the mpd host to connect to. - syncplaylist
- The playlist that
kmpc
will use to sync music files. This should be a playlist on the synchost generated bykmpcmanager
.
kmpc-only¶
- syncmusicpath
- The path to the music folder on the synchost.
- syncfanartpath
- The path to the fanart folder on the synchost.
- synctmppath
- Where temporary files should be written on the synchost.
kmpcmanager-only¶
- syncmpdport
- Port that mpd is running on on the synchost.
- synclocalmusicpath
- The path to the music folder on whatever machine
kmpcmanager
is running on. - synclocalfanartpath
- The path to the fanart folder on whatever machine
kmpcmanager
is running on.
[system] section¶
kmpc-only¶
- rpienable
- Set this to
true
if you are running this on a Pi and want to control Pi-specific features, such as the backlight. Set tofalse
otherwise. Defaults tofalse
. - originalyear
- Set this to
true
to display an mp3’s originalyear tag as well as the regular year tag. Defaults totrue
. - advancedtitles
- Whether to attempt to parse track and album titles to display them more
appropriately on the screen. Defaults to
false
. - exportfirst
- Whether to export ratings before importing them when running Sync All.
Defaults to
true
. - updatecommand
- This is what runs when you press the Update button. Defaults to
sudo pip install -U kmpc --no-deps
. - rebootcommand
- This is what runs when you press the Reboot button. Defaults to
sudo reboot
. - poweroffcommand
- This is what runs when you press the Poweroff button. Defaults to
sudo poweroff
.
[logs] section¶
kmpcmanager-only¶
- artlog
- Whether to generate a file named
artlog.txt
in the config dir that contains data about every media file successfully downloaded from fanart.tv. Defaults tofalse
.
[fanart] section¶
kmpcmanager-only¶
- client_key
- Your personal client key for fanart.tv. This is not necessary, but helps them out if you use it.
[songratings] section¶
Customize the meaning of 0-10 stars. The defaults are probably good enough, but feel free to change them to whatever you want. These are the strings that are shown in the rating popup.
[colors] section¶
- backdrop
- The main backdrop used on all panels.
- button
- All buttons used in the app.
- listitem
- Rows in the playlist or library.
- listitemselected
- A selected row in the playlist or library.
- listitemcurrent
- The current song in the playlist.
[artblacklist] section¶
kmpcmanager-only¶
This section is empty by default. It allows you to blacklist certain fanart files from certain artistids in case you don’t want them automatically downloaded. An entry would look like this:
b38225b8-8e5f-42aa-bcdc-7bae5b5bdab3 = 128387,128388
The key is a MusicBrainz artistid, and the value is a comma-separated list of FanArt.tv image ids to ignore.
Using kmpc
¶
Here is a quick tour of the various tabs in kmpc and what everything does.
Now Playing¶
This is the default active tab when you first run kmpc. If there is no currently playing music, you will see ‘Playback Stopped’. If there is something playing, it will look similar to this:
Current Track Info¶
The background of this section will be pulled from the fanart directory based on the current track artist, if at least one file exists in the artistbackground folder for that artist.
First is the artist name section, which is pulled from the track artist tag. This will either be rendered in normal text, or a logo image pulled from the fanart folder. If there is more than one artist, all artists will be shown.
After that is the track name, then the album name.
Under this is a smaller line detailing the upcoming artist and track.
To the left in sideways text the release year is shown in []. If originalyear is turned on, then this value will be pulled from an mp3’s ‘originalyear’ tag, and mpd’s ‘year’ tag will be shown in {} next to it if it is different. This is to represent the original release year for an album versus the year it was remastered. If originalyear is off, only mpd’s ‘year’ tag will be shown. See [system] section for details about originalyear.
If advancedtitles is on, kmpc will attempt to parse the album and track names to make them a bit prettier. If the album name doesn’t have ‘EP’ or ‘(single)’ in it, the word ‘album’ will be shown in sideways text to the left of the album cover. Likewise, ‘EP’ will be shown if it is an EP and ‘single’ will be shown if it is a single. Strings in () or [] will be shown in a smaller font under the main title. Albums with ‘ / ‘ in them (split EPs usually) will be formatted with the above modifiers and split correctly. See [system] section for details about advancedtitles.
Bottom Section¶
At the bottom left is the album cover, if it can be pulled from the cover image tag, or a blank space otherwise. You can click on it to popup a larger view, and click outside the popup to dismiss it.
In the middle is the current track time. The time displayed inside the slider is the remaining time. On the left is the elapsed time, and on the right is the total time.
Below that is the track number. This shows the current track and the total number of tracks in the current playlist.
On the bottom right is the song rating. This will display a ? if the song has not yet been rated, or the value from 0-10 in half-star increments of the song rating as pulled from mpd. This does not check the rating tag of the file.
Backlight Controls¶
On the far right of the screen, there are four buttons to control the brightness of the Raspberry Pi touchscreen. These do nothing if the rpienable flag is not set to true in the config file. They change the brightness from brightest at the top to dimmest at the bottom. See [system] section for details about rpienable.
Playback Controls¶
Along the very bottom of the screen are the playback controls. From left to right, they are as follows:
- Previous Track
- Goes to the previous track.
- Play/Pause
- Pauses if playing, plays if paused or stopped.
- Next Track
- Goes to the next track.
- Toggle Repeat Mode
- If on, the current playlist (if Single Mode is off) or track (if Single Mode is on) will repeat indefinitely.
- Toggle Single Mode
- If Repeat Mode is on, the current song will repeat. If Repeat Mode is off, then playback will stop after the current song.
- Toggle Random Mode
- The playlist will be played back in random order if on.
- Toggle Consume Mode
- If on, the current song will be removed from the playlist after playback.
Runtime Settings¶
At the top left is a button to popup the runtime settings. This opens a menu for various ancillary controls.
The first three sliders affect mpd’s playback, and correspond to the ‘crossfade’, ‘mixrampdb’, and ‘mixrampdelay’ mpd options. Please see mpd’s documentation for explanation.
The toggle button at the bottom allows selection of Replaygain functionality. Please see mpd’s documentation for explanation.
Swiping left on the popup will bring up the next set of controls.
First is the current IP address of the host. kmpc tries to guess this intelligently, returning either the local IP address or 127.0.0.1 if no network is connected. This can be useful in determining whether the Pi in your car can reach the wifi in your house.
The Text Color and Outline Color toggles let you change the color and outline of text displayed in kmpc between white and black.
Configuration¶
At the middle left is a button to open the configuration panel. This lets you edit all the various settings in the config file. At the top left you can choose the section, and the values for that section will show up for editing underneath. Hit Close when you are done.
Playlist¶
Function Buttons¶
Along the top, under the main tabs, are several function buttons. From left right, they are as follows:
- Clear
- Clears the playlist.
- Delete
- Removes the currently selected track from the playlist.
- Move
- Does nothing right now. Sorry.
- Shuffle
- Shuffles all tracks on the playlist.
- Swap
- Switch the position of two selected tracks. Must have exactly two tracks selected.
- Save
- Saves the current playlist with a name.
List of Tracks¶
Below the buttons is the list of tracks in the current playlist. This is scrollable via touch, mousewheel, or click and drag. The currently playing track is highlighted. Clicking on a track will select it for use with the above function buttons. Long-pressing a track will start playing from that track.
Library¶
This tab lets you browse through mpd’s library of songs. Along the top are the different methods of browsing.
- Files
- Directly browse the file tree. This is exactly how your files are stored on disk.
- Albums
- A list of all album artists, with their respective albums inside.
- Tracks
- A list of all artists, with their respective tracks inside.
- Playlists
- A list of all saved playlists.
Along the right side, you will see several buttons. Their functions are as follows:
- + (Append)
- Appends the currently selected item to the playlist.
- > (Insert)
- Inserts the currently selected item after the current track on the playlist.
- ! (Replace)
- Clears the playlist then adds the currently selected item.
- X (Delete)
- Deletes the currently selected item. Only works in the Playlists section.
Files¶
When you first click the Files tab, you are presented with the top level of the filesystem. You can scroll, click to select, or long-press to descend into the folder. As you descend, you can move back up by long-pressing the ‘up to <whatever>’ line at the top. Once you get to the level of actual files, long-pressing will replace the playlist with whatever is in the current folder, and start playing from the file you long-pressed on. I recommend sorting your files into subfolders in the following hierarchy to make this useful:
- First letter of album artist name
- Album artist
- Album name, with original release year at the beginning
The following images show the descent into the filesystem. Note that file names are shown without their file extensions.
Albums¶
This lists all album artists, sorted alphabetically. You can scroll, click to select, or long-press to descend into the folder. As you descend, you can move back up by long-pressing the ‘up to <whatever>’ line at the top. Once you get to the level of actual tracks, long-pressing will replace the playlist with the current album, and start playing from the track you long-pressed on. The following images show the descent into albums.
Tracks¶
This lists all track artists, sorted alphabetically. You can scroll, click to select, or long-press to descend into the folder. As you descend, you can move back up by long-pressing the ‘up to <whatever>’ line at the top. Note that if two tracks by the same artist have the exact same name, only the first one found will show up in this list. The following images show the descent into tracks.
Playlists¶
This lists all named playlists that mpd knows about. Long-pressing on a playlist will replace the current playlist. You can also select one or more and use the buttons to the right. ‘+’ will append them, ‘>’ will insert them, ‘!’ will clear the playlist then append them, and ‘X’ will delete them.
Generate¶
Pressing this button allows you to generate playlists based on song ratings. Choose the number of stars, the operation, and a name for the playlist, then click Generate.
System¶
The Update button will run whatever command you have in the config file
[system]
section in the updatecommand
field.
The Sync button interacts with the synchost, which is explained in the following section.
Exit, Reboot, and Poweroff are pretty self-explanatory.
The Plugins button launches plugins located in ~/.kmpc/plugins
. For more
information, see the plugin documentation
Syncing with the synchost¶
This is the way I have the system set up at my home. There is a Linux server on
my local network which contains all of my music (way more than I can fit on the
128G thumb drive connected to the Pi in my car), indexed by an mpd server
running on the same box. I use the kmpcmanager
program to create a playlist
containing all the files I want to copy to the car (the synclist). This uses
both the star ratings (to set a threshold for the minimum rating to copy) as
well as another mpd sticker called ‘copy_flag’. If ‘copy_flag’ is ‘Y’, the file
is always copied. If ‘N’, the file is never copied.
When the ‘Sync’ button is pressed, you can choose between ‘Fanart’, ‘Music’, ‘Ratings’, or ‘All’.
- Fanart:
- The entire fanart directory is rsynced from synchost:syncfanartpath to fanartpath on the Pi.
- Music:
- The musicpath directory on the Pi is walked, and any file not existing in the synclist is deleted.
- All empty directories in musicpath are deleted.
rsync
is run with the synclist as input to copy any new/updated files from the synchost to the Pi.- The mpd database is updated.
- All files in the synclist are added to a playlist called ‘root’ on the Pi.
- Ratings:
- All song rating stickers are exported from the Pi to the synchost.
- All song rating stickers are imported from the synchost to the Pi.
Using kmpcmanager
¶
The kmpcmanager
app is meant to be run from your desktop, rather than from
the Pi. It provides many functions for supporting the synchost. It does not
have the level of polish that kmpc
does, since I mostly just developed it
for personal use, however I will attempt to clean it up in the future. Make
sure you read the section on the config file as there are
values you need to change.
The easiest way to use this app, if you aren’t running it directly on the synchost, is to mount the ‘music’ and ‘fanart’ folders from the synchost on to your desktop. Change the config values ‘musicpath’ and ‘fanartpath’ to match the mounted folders. Change the ‘synchost’ value to the hostname or IP address of the synchost. Change the ‘syncmusicpath’ and ‘syncfanartpath’ to the folders as they exist on the synchost.
At startup, a cache of the artist data will be read from
~/.kmpc/artist_cache.pkl
if it exists. Data is pulled from MusicBrainz and FanArt.tv.
Artists Tab¶
Functions¶
Across the top are various buttons that perform functions, as follows:
- Status bar
- Prints information about the currently running operation
- Refresh from mpd and internet
- Asks mpd for a list of all ‘musicbrainz_artistid’ tags, then iterates that list, pulling data from MusicBrainz, and populating the scrollview below. Since MusicBrainz only allows one query per second, this can take quite awhile on first run if your music collection is large.
- Refresh from cache
- Manually reload the artist cache from disk. Rarely used.
- Write to cache
- Manually write artist cache to disk. Do this at least once after running the ‘Refresh from mpd and internet’ task to ensure you don’t have to do that again.
- Scan row
- Scans the selected artist row for fanart media. This will update the columns to the right of that row.
- Scan all
- Loops through every artist row and scans for fanart media, then updates the columns on the right.
- Pull art for row
- Connects to FanArt.tv and pulls logo and background media for the selected artist row. If files are found in the ‘hdmusiclogo’ or ‘musiclogo’ section for that artist, they are downloaded to the ‘logo’ folder in the fanart directory for that artist, then trimmed to the smallest possible size. If files are found in the ‘artistbackground’ section for that artist, they are downloaded to the ‘artistbackground’ folder in the fanart directory for that artist. If files already exist in one of these folders, the operation is aborted, so as to not waste time.
- Pull art for all
- Loops through every artist row and pulls media.
Artist rows¶
The following data is shown from left to right:
- Artist name
- MusicBrainz ArtistId
- Whether at least one artistbackground exists
- Whether at least one logo exists
- Whether at least one badge exists
Artist name and id are selectable for easy copy/pasting.
Directory structure for fanart¶
The directory structure for fanart is as follows, with <fanartpath> as the root folder:
fanartpath
├── 078a9376-3c04-4280-b7d7-b20e158f345d # musicbrainz artistid
│ ├── __Artist Name__ # empty file, optional
│ ├── artistbackground # player background images
│ │ ├── 132224.jpg # you can have as many
│ │ ├── 39392.jpg # as you want
│ │ ├── 4679.jpg # or none at all
│ │ ├── 4680.jpg # format is 1280x720 JPG
│ │ └── 7578.jpg
│ ├── logo # artist logo images
│ │ ├── 130819.png # you can have as many
│ │ ├── 45979.png # as you want
│ │ ├── 15469.png # or none at all
│ │ ├── 47981.png # format is transparent PNG
│ │ ├── 39562.png # maximum 800x310
│ │ └── 5624.png
│ └── badge # artist badge images
│ ├── 130819.png # you can have as many
│ ├── 45979.png # as you want
│ ├── 15469.png # or none at all
│ ├── 47981.png # format is transparent PNG
│ ├── 39562.png # squarish aspect ratio
│ └── 5624.png
└── 391c9402-6688-4c3d-8f3d-d320d31b4de9 # and so on
├── __Another Artist__
└── logo
└── 154355.png
Badges¶
Badges are simply logos that have been manually moved to the ‘badge’ folder of an artist. This is to handle artists that have symbols or other types of squarish aspect ratio logos that do not explicitly spell out the artist’s name. An example is Dream Theater’s ‘Majesty’ symbol, or Metallica’s ‘ninja star’ symbol. Since the artist logo should clearly state the artist’s name for legibility in kmpc, these files are kept separate.
There is not currently any sort of automatic handling of these files as FanArt.tv does not treat them differently. I wrote a script to find all files of squarish aspect ratio and print them to the screen for further manual sorting.
kmpc does not currently do anything with these files, but there are plans in the future to use them somehow.
Library Tab¶
This functions similarly to the library browser in kmpc
, with a few
different functions. You can double-click as well as long-press on items so
it is easier to use on the desktop.
Additional data is displayed in the scrollview rows. First is the song rating in stars. If no rating exists, a ‘?’ will be displayed. Since mpd only supports per-file rating, anything that is not a track will display a ‘?’ initially. After that is the copy_flag field. This will display a ‘Y’ if copy_flag is set to true, a ‘N’ if set to false, and nothing if it is not set.
To the right are three buttons, which toggle the copy_flag. ‘+’ will set it to true, ‘-‘ to false, ‘/’ will clear it. These buttons function at the directory, file, artist, album, and track level.
Pressing the ‘Generate’ button brings up this popup:
If you want to generate a synclist, choose a Rating and hit ‘Generate Synclist’. This will use the specified rating and the copy_flag sticker to generate a playlist named whatever you have in your config file for ‘syncplaylist’.
If you want to generate a playlist, choose a Rating, an Operation, and a Playlist Name (or use the auto-generated name) and hit ‘Generate Playlist’.
System Tab¶
This tab has two functions. Config lets you edit the config file. Exit exits.
Workflow¶
Here’s how I use the manager. For all tracks that I want on my car Pi no matter what, I set copy_flag to true. For tracks that don’t need to be on there, I set it to false. I use this, for example, to manage greatest hits or compilation albums so that multiple copies of the same track aren’t taking up extra space. I’ll set only unique tracks on those albums to true or clear and everything that exists on some other album to false.
Then I generate the synclist based on a minimum 7-star rating. This makes sure that only songs I actually want to listen to end up on my car Pi, and no disk space is wasted with duplicate tracks. However, my home music collection can be complete and much more extensive.
The ~/.ssh/config
file is set up correctly on the car Pi to connect to the
synchost, and it is running on the same network the car Pi connects to when I
am at home. When I want to sync music, fanart media, and/or song ratings, I
just have to press the ‘Sync’ button in kmpc on the car Pi and everything
works. I also sometimes ssh into the car Pi and run the commandline sync
commands instead if I know it’s going to take awhile and I don’t want to sit in
the car staring at the screen.
Car Installation Tutorial¶
This document will guide you through a method of setting up a fully functional touchscreen solution that can be mounted in your car. It uses KivyPie as the base linux distro.
Step 1: Install KivyPie¶
Visit the download site and download the latest build of KivyPie. Note that this project needs at least Kivy v1.10.0, so download accordingly.
Unzip the downloaded file and flash it to a MicroSD card. I recommend using Etcher. Boot your Pi with this card.
Read the KivyPie FAQ Page to understand how you can connect to it. The latest version (as of this writing) has a new method to configure the network that doesn’t seem to be documented however. If you need wifi, do the following: #. Power down the Pi and mount the SD card on your desktop. #. Edit the file
interfaces
in the root of the SD card.Change the line:
wpa-ssid pipaos
to:
wpa-ssid <whatever-your-ssid-is>
Change the line:
wpa-psk pipa123pass
to:
wpa-psk <whatever-your-passphrase-is>
Save the changes, eject the SD card, put it back in the Pi and boot.
Login with the credentials given in the FAQ, either with a physical keyboard or via SSH. The rest of the guide will use the default user, however if you wish to add a new user, set a password, and do everything with that it should be fine, just adjust accordingly.
Run the following to give your user password-less sudo access:
cat << EOF | sudo tee /etc/sudoers.d/$USER $USER ALL=(ALL:ALL) NOPASSWD:ALL EOF
You’ll need to expand your root volume to use the whole SD card. Run:
sudo pipaos-config
choose Expand Filesystem, hit enter a few times, let the Pi reboot, then log back in.
If you don’t want the rainbow screen to show on boot, edit the file
/boot/config.txt
and adddisable_splash=1
to the end of it.Run this to update your packages:
sudo apt-get update
Run this to give your user access to the backlight device (taken from https://github.com/linusg/rpi-backlight):
cat <<EOF | sudo tee /etc/udev/rules.d/backlight-permissions.rules SUBSYSTEM=="backlight",RUN+="/bin/chmod 666 \ /sys/class/backlight/%k/brightness /sys/class/backlight/%k/bl_power" EOF
Reboot.
Step 2: Install kmpc¶
KivyPie mounts an extremely small tmpfs at /tmp, which interferes with pip’s ability to install things. Run the following to remount /tmp temporarily during the install process:
sudo mkdir /root/tmp sudo umount -l /tmp sudo mount --bind /tmp /root/tmp
As of this writing, the version of pip/setuptools on KivyPie is old. Run the following to update:
sudo pip install --upgrade pip setuptools wheel
Run the following to install kmpc and pull in the Pi-specific dependencies:
sudo pip install kmpc[rpi]
Run:
kmpc --newconfig
This will generate the default config file.
Optional configuration tasks in
~/.kivy/config.ini
:If you want a mouse cursor to show up on the screen (in case you are running with a keyboard and mouse), add the following to the [modules] section:
cursor =
If you don’t want a little circle to show up on the screen anywhere you touch, comment out this line in the [modules] section:
touchring = scale=0.3,alpha=0.7,show_cursor=1
If you are getting duplicate clicks and/or keypresses with a physical mouse or keyboard, comment out the following line in the [input] section:
%(name)s = probesysfs,provider=hidinput
Step 3: Set up mpd¶
Put some mp3 files on there somewhere. I suggest a USB thumb drive for ease of use, but in a pinch you can just put them on the SD card somewhere. The path to these files will henceforth be named <musicpath>.
Make sure your audio connection is working. Run
amixer sset 'PCM' 0
to turn the audio volume up, then runspeaker-test
and listen for some output.Run the following to install mpc, as it is needed for testing and by the sync function:
sudo apt-get -y install mpc
The version of mpd in the repo as of this writing is super old and buggy, so we’re going to compile from source. Change <musicpath> in the below text to your musicpath. Here’s the commands:
export MUSICPATH=<musicpath> wget https://www.musicpd.org/download/mpd/0.19/mpd-0.19.21.tar.xz tar xf mpd-0.19.21.tar.xz cd mpd-0.19.21/ sudo apt-get -y install g++ libboost-dev libicu-dev libglib2.0-dev \ libsqlite3-dev libmpdclient-dev libexpat1-dev \ libid3tag0-dev libflac-dev libaudiofile-dev libmad0-dev libmp3lame-dev \ libasound2-dev libcurl4-gnutls-dev libsystemd-daemon-dev \ libfaad-dev libmpg123-dev libavcodec-dev libsndfile-dev libvorbis-dev \ libavformat-dev libavutil-dev ./configure \ --enable-werror --prefix=/usr --sysconfdir=/etc \ --with-systemdsystemunitdir=/etc/systemd/system --enable-systemd-daemon \ --enable-database --enable-sqlite --enable-libmpdclient --enable-expat \ --enable-alsa --disable-oss --enable-icu --enable-glib \ --enable-flac --enable-audiofile --enable-dsd --enable-mad --enable-id3 --enable-curl \ --enable-mms=no --enable-smbclient=no --enable-nfs=no --enable-zlib=no --enable-bzip2=no \ --enable-roar=no --enable-ao=no --enable-vorbis=yes --enable-wavpack=no --enable-gme=no \ --enable-lame-encoder=no --enable-shine-encoder=no \ --enable-twolame-encoder=no --enable-vorbis-encoder=no --enable-wave-encoder=no \ --enable-modplug=no --enable-mpc=no --enable-mpg123=yes --enable-openal=no \ --enable-opus=no --enable-sidplay=no --enable-shout=no --enable-adplug=no \ --enable-sndfile=yes --enable-wildmidi=no --enable-soundcloud=no --enable-ffmpeg=yes \ --enable-jack=no --enable-pulse=no --enable-lsr=no --enable-soxr=no --enable-fluidsynth=no \ --enable-cdio-paranoia=no \ --enable-recorder-output=no --enable-httpd-output=no --enable-solaris-output=no \ --enable-libwrap=no --enable-upnp=no --enable-neighbor-plugins=no --with-zeroconf=no \ --enable-aac make sudo make install sudo useradd -M mpd sudo usermod -L mpd sudo usermod -G audio mpd sudo mkdir -p /var/lib/mpd/playlists sudo mkdir -p /var/log/mpd sudo chown -R mpd:audio /var/lib/mpd sudo chown -R mpd:audio /var/log/mpd cat << EOF | sudo tee /etc/mpd.conf music_directory "$MUSICPATH" playlist_directory "/var/lib/mpd/playlists" db_file "/var/lib/mpd/database" log_file "/var/log/mpd/mpd.log" pid_file "/var/lib/mpd/pid" state_file "/var/lib/mpd/state" sticker_file "/var/lib/mpd/sticker.sql" user "mpd" group "audio" bind_to_address "127.0.0.1" max_output_buffer_size "32768" EOF sudo chown -R $USER:audio "$MUSICPATH" sudo chmod g+w "$MUSICPATH" sudo systemctl enable mpd sudo systemctl start mpd
See https://www.musicpd.org/doc/user/config.html for further details on the
/etc/mpd.conf
file. You might want to add ‘replaygain’ variables, for example.Restart mpd:
sudo systemctl restart mpd
Run the following to update the mpd database:
mpc update
Edit the file
~/.kmpc/config.ini
and set themusicpath
variable to <musicpath>Save the file and run
kmpc
again. You should now be able to browse the library, add files to the playlist, and generally use the app.
Step 4: Run at Boot¶
The easiest way to get kmpc running at boot time is by using a systemd user unit. Run the following commands:
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/kmpc.service <<EOL
[Unit]
Description=kmpc
[Service]
ExecStart=/usr/local/bin/kmpc
Restart=always
[Install]
WantedBy=default.target
EOL
systemctl --user enable kmpc
sudo loginctl enable-linger sysop # substitute your username if you used a new one
You can now start the kmpc process using systemctl --user start kmpc
.
Step 5: Add Fanart (optional)¶
The directory structure for fanart is as follows, with <fanartpath> as the root folder:
fanartpath
├── 078a9376-3c04-4280-b7d7-b20e158f345d # musicbrainz artistid
│ ├── __Artist Name__ # empty file, optional
│ ├── artistbackground # player background images
│ │ ├── 132224.jpg # you can have as many
│ │ ├── 39392.jpg # as you want
│ │ ├── 4679.jpg # or none at all
│ │ ├── 4680.jpg # format is 1280x720 JPG
│ │ └── 7578.jpg
│ ├── logo # artist logo images
│ │ ├── 130819.png # you can have as many
│ │ ├── 45979.png # as you want
│ │ ├── 15469.png # or none at all
│ │ ├── 47981.png # format is transparent PNG
│ │ ├── 39562.png # maximum 800x310
│ │ └── 5624.png
│ └── badge # artist badge images
│ ├── 130819.png # you can have as many
│ ├── 45979.png # as you want
│ ├── 15469.png # or none at all
│ ├── 47981.png # format is transparent PNG
│ ├── 39562.png # squarish aspect ratio
│ └── 5624.png
└── 391c9402-6688-4c3d-8f3d-d320d31b4de9 # and so on
├── __Another Artist__
└── logo
└── 154355.png
Once you’ve added some art, do the following
Edit the file
~/.kmpc/config.ini
and change thefanartpath
variable to <fanartpath>.Run:
sudo chown -R $USER:audio <fanartpath> sudo chmod -R g+w <fanartpath> sudo find <fanartpath> -type d -exec chmod g+s '{}' \; systemctl --user restart kmpc
You should now see logos and background images for the artists that have images in the fanart folder.
Step 6: Setup Sync (optional)¶
See the section on Using kmpcmanager to learn how the manager program interacts with the synchost. The basic gist of it is this:
Have a Linux box running in your house, connected the same wifi that the car Pi will be able to connect to. This will be called the synchost.
Have mpd running on it, and fully updated.
Use
kmpcmanager
to automatically download all the fanart and manage the ratings and copy_flags for all your tracks.Edit the file
~/.kmpc/config.ini
on your car Pi and change the variables in the [synchost] section. See the section on config file ~/.kmpc/config.ini for details.Run
ssh-keygen
and hit enter on all the defaults. This creates a public key for this user.Insert the contents of
~/.ssh/id_rsa.pub
on the car Pi into the~/.ssh/authorized_keys
file on the synchost as whatever user you have set up there.Edit the file
~/.ssh/config
and add the following:Host <synchost> # this should match config.ini User <synchost_username> # a user on <synchost> StrictHostKeyChecking no
For example, my ssh config looks like this:
Host 192.168.1.100 User cgraham StrictHostKeyChecking no
And the
synchost
variable in the[sync]
section in my~/.kmpc/config.ini
is set to “192.168.1.100”.Test that your connection is working by running:
ssh <synchost>
Stop the kmpc service and test the sync manually by going to the Config tab and clicking Sync:
systemctl --user stop kmpc kmpc
If that worked well, exit kmpc and restart the service:
systemctl --user start kmpc
Now you should be able to use the Sync button in the Config tab to automatically sync all music, fanart, and song ratings with the synchost. Note that all fanart is syncronized, not just artists in the list of files to sync.
Plugins¶
Plugins are accessed via the System Tab:
Upon clicking the Plugins button, you are presented with a list of all
available plugins in the ~/.kmpc/plugins
folder:
Pictured are some plugins that are available at https://gitlab.com/eratosthene/kmpc-plugins.
Plugin Folder Contents¶
Inside the ~/.kmpc/plugins
folder, there should be one or more folders
named for each plugin. Each plugin folder must contain either at least two
files named plugin.py
and plugin.kv
or a file named plugin.sh
:
plugins
├── someguiplugin
│ ├── plugin.kv
│ └── plugin.py
├── somescript
│ └── plugin.sh
└── anothergui
├── plugin.kv
└── plugin.py
GUI Plugins¶
These are plugins that need to display an interface for interaction. They are writtine in python and kv.
plugin.py¶
This file contains the logic for a plugin, written in python. You can import whatever you want, and it will have access to any global variables in the kmpc application, including App. The only requirement is to have at least one class named <pluginname>PluginContent, that is a subclass of some Kivy widget. So, for example, the kivypiewifi plugin has the following in it:
class kivypiewifiPluginContent(BoxLayout):
Do whatever needs to be done, just make sure you are doing things in a non-blocking manner. I prefer to use the twisted reactor and its associated methods for this.
plugin.kv¶
This file contains the presentation for a plugin, written in kv. It should should contain at least the default kv declaration, an import for the plugin’s class, and a definition of that class. For example, the kivypiewifi plugin has the following in it:
#:kivy 1.10.0
#:import kivypiewifiPluginContent plugin.kivypiewifiPluginContent
... (skipping a few lines)
<kivypiewifiPluginContent>:
(here iss where the kv definition for your plugin goes)
Running¶
When you click on a GUI plugin in kmpc to run it, the following things happen:
- The Choose Plugin to Run popup is closed.
- A new full screen popup is opened, with a Close button at the bottom.
- The plugin’s PluginContent class is instantiated, and placed inside the popup.
When you click on a script plugin in kmpc to run it, the following things happen:
- The chosen script is executed, with control returning to kmpc only after the script exits.
- The Choose Plugin to Run popup is closed.
kmpc Change Log¶
0.6.9 - 2018-06-06¶
- Migrated to gitlab and updated all source to reflect that.
0.6.8 - 2018-02-24¶
- Cleaned up all code and comments to comply with PEP8.
0.6.7.2 - 2018-02-12¶
- Bugfix release. Manager not writing synclist.
0.6.7.1 - 2018-02-11¶
- Bugfix release. Toggle buttons in manager were not toggling.
0.6.7 - 2018-02-10¶
- Significantly revamped kmpcmanager code. This now allows it to be run as a plugin in case you want to manager things directly from your car, amongst other things.
0.6.6 - 2018-02-09¶
- Added Config and Exit buttons to a System tab in kmpcmanager.
- Plugins! You can now build your own plugins and place them in ~/.kmpc/plugins for access via the System tab. Some examples at https://gitlab.com/eratosthene/kmpc-plugins.
0.6.5.1 - 2018-02-04¶
- Bugfix release. Cover popup was not displaying the album title.
0.6.5 - 2018-02-04¶
- Moved all presentation code to .kv files. (issue 97)
- Fixed bug in advanced titles. (issue 106)
- Unified theming between app and manager.
- Fixed Update command to use proper PATH environment variable. (issue 92)
- Changed background textures to greyscale, and added new [colors] section to config file for tinting them. (issue 96)
0.6.4 - 2018-02-03¶
- Added playlist generation based on star ratings to the Library tab. (issue #84)
- Added replaygain toggle in settings popup. (issue 89)
- Changed commandline ‘convert’ usage in kmpcmanager to use pillow instead. (issue 94)
- Ratings popup now has larger buttons, and a ‘clear rating’ button. Manager app also uses the same code now. (issue #91)
- Restructured code and resources to break everything into smaller, separate files. (issue #93)
0.6.3.1 - 2018-02-02¶
- Bugfix release, found a bug in the format_song code.
0.6.3 - 2018-02-01¶
- Fixed a bug in advanced titles parsing.
- Split ratings sync into export and import sections to allow running each separately and in a specific order. (issue #82)
- Added new rebootcommand and poweroffcommand fields to config file to control what those buttons do.
- Added output from update command to popup on screen. (issue #83)
- Fixed stdout popups to scroll correctly. (issue #81)
0.6.2.1 - 2018-02-01¶
- Bugfix release, forgot an import.
0.6.2 - 2018-01-31¶
- Drastically rewrote sync handling. You can now run each part from the command line or the gui. No longer requires anything but mpd and ssh to work. (issue #75)
0.6.1 - 2018-01-29¶
- Added new ‘advanced titles’ feature which will attempt to parse information out of the track and album titles to format it better on the screen. A new config file option was added as well, defaulting to off. (issue #69)
- Changed the track slider update task to pause when not on the Now Playing tab. (issue #64)
- Added warning to prevent syncing synchost to itself. (issue #73)
- Changed sections in config file and updated docs accordingly to better account for which fields are used in each program. (issue #70)
0.6.0.1 - 2018-01-27¶
- Bugfix release, I missed a couple of config file changes, oops.
0.6.0 - 2018-01-27¶
- Added album name and release year(s) to cover popup.
- Load album covers from tags with PIL directly first, to allow for resizing in case it is too large for a texture to hold. (issue #7)
- Changed to a ReconnectingClientFactory to prevent issues when long-running mpd commands are run. (part of issue #9)
- Added a line to the mpd.conf file in the car install doc to prevent mpd crashing when loading a long playlist. (part of issue #9)
- Revamped the way config file handling works to use Kivy’s built-in Config class. You can now edit config settings from within the app. (issue #17)
0.5.9 - 2018-01-26¶
0.5.7 - 2018-01-26¶
0.5.6 - 2018-01-25¶
- Changed the scan all for art function in the manager to schedule the requests once per second for every row instead of skipping rows that already had some art. (issue #26)
- Changed the year display to on top of the cover art to save some space.
- Added a config file setting for originalyear display. (issue #16)
- Added new settings popup to house things as config tab is going to be used for actual config file editing eventually. (issue #6)
- Added ability to click on artist logo to change it to another one. (issue #5)
- Added sudo to reboot and shutdown commands. (issue #43)
- Added docs for full installation to car Pi!
0.5.4 - 2018-01-22¶
- Fixed a bug in the mpd module. This is why you should test things before releasing them to the public.
0.5.3 - 2018-01-22¶
- Fixed fanart.tv to use baked-in developer key and optional client key (issue #28)
- Fixed paths to use portable path separator instead of ‘/’ (issue #23)
- Changed musicbrainz access to use the musicbrainzngs library (issue #14)
- Pulling art for an artist will no longer re-download logos that have been manually moved to the badge folder
0.5.2 - 2018-01-21¶
0.5.1 - 2018-01-20¶
- First public release