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 by kmpcmanager.

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 to false otherwise. Defaults to false.

originalyear

Set this to true to display an mp3’s originalyear tag as well as the regular year tag. Defaults to true.

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 to false.

[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:

Main Tab Navigation

Across the top are the various tabs you can switch to. Each of these will be explained in following sections.

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:

1. First letter of album artist name
2. Album artist
3. 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:

1. The entire fanart directory is rsynced from synchost:syncfanartpath to fanartpath on the Pi.

Music:

1. The musicpath directory on the Pi is walked, and any file not existing in the synclist is deleted.
2. All empty directories in musicpath are deleted.
3. rsync is run with the synclist as input to copy any new/updated files from the synchost to the Pi.
4. The mpd database is updated.
5. All files in the synclist are added to a playlist called ‘root’ on the Pi.

Ratings:

1. All song rating stickers are exported from the Pi to the synchost.
2. 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

1. 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.

2. Unzip the downloaded file and flash it to a MicroSD card. I recommend using Etcher. Boot your Pi with this card.

3. 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.

   1. Change the line:

      wpa-ssid pipaos
      

      to:

      wpa-ssid <whatever-your-ssid-is>
      

   2. Change the line:

      wpa-psk pipa123pass
      

      to:

      wpa-psk <whatever-your-passphrase-is>
      

   3. Save the changes, eject the SD card, put it back in the Pi and boot.

4. 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.

5. 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
   

6. 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.

7. If you don’t want the rainbow screen to show on boot, edit the file /boot/config.txt and add disable_splash=1 to the end of it.

8. Run this to update your packages:

   sudo apt-get update
   

9. 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
   

10. Reboot.

Step 2: Install kmpc

1. 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
   

2. 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
   

3. Run the following to install kmpc and pull in the Pi-specific dependencies:

   sudo pip install kmpc[rpi]
   

4. Run:

   kmpc --newconfig
   

   This will generate the default config file.

5. 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

1. 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>.

2. Make sure your audio connection is working. Run amixer sset 'PCM' 0 to turn the audio volume up, then run speaker-test and listen for some output.

3. Run the following to install mpc, as it is needed for testing and by the sync function:

   sudo apt-get -y install mpc
   

4. 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
   

5. 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.

6. Restart mpd:

   sudo systemctl restart mpd
   

7. Run the following to update the mpd database:

   mpc update
   

8. Edit the file ~/.kmpc/config.ini and set the musicpath variable to <musicpath>

9. 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

1. Edit the file ~/.kmpc/config.ini and change the fanartpath variable to <fanartpath>.

2. 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:

1. 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.

2. Have mpd running on it, and fully updated.

3. Use kmpcmanager to automatically download all the fanart and manage the ratings and copy_flags for all your tracks.

4. 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.

5. Run ssh-keygen and hit enter on all the defaults. This creates a public key for this user.

6. 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.

7. 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”.

8. Test that your connection is working by running:

   ssh <synchost>
   

9. Stop the kmpc service and test the sync manually by going to the Config tab and clicking Sync:

   systemctl --user stop kmpc
   kmpc
   

10. 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)

Script Plugins

These are plugins that just run another program. It might cover up the kmpc interface, it might just do stuff in the background. They are defined in bash.

plugin.sh

This is just a normal bash script that does whatever.

Running

When you click on a GUI plugin in kmpc to run it, the following things happen:

1. The Choose Plugin to Run popup is closed.
2. A new full screen popup is opened, with a Close button at the bottom.
3. 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:

1. The chosen script is executed, with control returning to kmpc only after the script exits.
2. 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

• Added -V/–version command line option to print version number. (issue #55)
• Added -n/–newconfig command line option to generate default config file. (issue #38)
• Issue #57 wasn’t actually fixed, just masked. Pretty sure it’s fixed now.

0.5.8 - 2018-01-26

• Missed a few lines in the mpd revamp, this fixes it. (issue #57)

0.5.7 - 2018-01-26

• Revamped mpd connection handling to be less crashy. (issue #35)
• Documented permissions change necessary to control Pi screen backlight. (issue #45)
• Added setuptools>=30.3.0 to the setup_requires section of setup.cfg. (issue #36)
• Added artblacklist section to config.ini. (issue #27)

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.5 - 2018-01-24

• Fixed a bug in how the sync method was handling unicode filenames. (issue #39)

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

• Added exception handling for non-existent artist cache file (issue #13)
• Added -q/–quiet command line option (issue #21)
• Fixed all temp files to honor config.ini values (issue #12)
• Changed artlog.txt in kmpcmanager to be optional (issue #4)

0.5.1 - 2018-01-20

• First public release