PiFi Radio: A MPD web client to listen to radio
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
app Fix volume OSD bug introduced on last refactoring Aug 24, 2018
resources Add video demo Aug 12, 2018
.gitignore Add screenshots Aug 12, 2018
.ruby-gemset Update gemset name Aug 12, 2018
.ruby-version Loose ruby version requirement Oct 27, 2017
Gemfile Move stations from rb file to json May 15, 2017
LICENSE Create LICENSE Aug 12, 2018
README.md Add a bunch of info to README Aug 12, 2018
config.ru Move most files to app/ Aug 3, 2018
pifiradio.conf.sample Update config sample Aug 12, 2018


PiFi Radio

PiFi Radio: A MPD web client to listen to radio

Table of contents


Read this blog post.

Meet PiFi Radio

What is PiFi Radio

PiFi Radio is a minimalist MPD web client to listen to radio. In other words, it makes your Raspberry Pi play Internet radio, while you control from any device, such as your phone.

As PiFi is just an interface for MPD, it has some advantages compared to other solutions, e.g. bluetooth or AirPlay. For example, the radio playback is completely independent from your phone. You can take calls, play videos, go to an area with poor WiFi signal, or even turn your phone off. Your Pi will still continue to play the radio you picked.

I started this project for my parents, in early 2017. At that time, I wanted to configure Raspbian so they could listen to radio with ease, but couldn't find any good solution for it.

Some of the goals of PiFi Radio were the following:

  • It should be easy for my parents to use.

  • Simple, straight-forward interface. Do the few things they need and in a clear way.

  • As fool-proof as possible. Don't show unnecessary options, minimize user interaction and try to predict what he wants.

  • Display both available and current stations clearly. No URLs or weird names.

  • Multi-platform, targeting primarily mobile phones.

  • In their language. I also translated it to English, and it's open to more.

Some features

Although PiFi tries to be minimal, there are some neat features, such as:

  • Organize the radios in categories, if you wish.

  • Select some radios to be shown only to certain IPs.

  • Paste a streaming URL for PiFi directly from your web browser. Useful if you want to listen to a radio that was not added to the list yet.

  • Add it to your Android home screen.

  • Multiple people can use it at the same time.

  • PiFi has two views (the List of Radios and Playback Controls). It tries to show one or another smartly so you tap less. For example, when you open PiFi and MPD is idle, the list of radios is shown, because you probably want to pick a station.

  • If you choose by mistake the same station that is currently playing, no request is sent to MPD, and the playback continues normally.

Beyond radio, the "Random" button:

  • By request, I added a button to play random music from the library. That's the "Random" button. Tapping it plays all your music in shuffle mode. To skip the current song, just press it again.

  • That's the only library related button. Library support is an after-thought on this app, not its main purpose. You can disable this button on the configuration.


Watch a video demo.

Radios list view

Controls view



While PiFi was created thinking about the Pi, it should run on any computer meeting the dependencies:

  • Ruby. Tested with Ruby 2.4. If you try another version, please edit .ruby-version.
  • Some Ruby gems.
  • MPD.
  • A web server to serve the static resources (optional).


Coming soon.


PiFi configuration

Configuration is read from the JSON file at /etc/pifiradio.conf. These are the options:

Key Value
cache_max_age Cache value used by Rack.
serve_static If Rack should serve static resources. Set to false if your web server is already doing it.
host MPD host.
port MPD port.
streams_file Path to file containing the streams list (see next section).
streamsp_file Path to other file containing streams list. The stations here will be merged with the other list and presented only to devices with IPs listed on special_ips. A use case for this is if you have tons of stations that only you listen and you don’t want to saturate everyone’s list. (If you don’t need this, just leave it empty.)
special_ips The IPs for which the additional streams will be shown. (If you don’t need this, just leave it empty.)
play_local If you don’t want PiFi to play songs from your local library, set it as false. This will remove the “Random” button.

List of streams

To keep it simple, the list of streams is just a JSON file with key-value pairs, where the key is the station name, and the value is the streaming URL. For example:

     “Radio 1”: “https://example.com/radio1”,
     “Radio 2”: “https://example.com/radio2”

If you want to arrange the stations in categories, add a pair with the category name, and empty value, as in:

     “Talk radio”: “”,
     “Radio 1”: “https://example.com/radio1”,
     “Radio 2”: “https://example.com/radio2”

     "Classical": "",
     “Radio 3”: “https://example.com/radio3”,
     “Radio 4”: “https://example.com/radio4”

This will add the headers “Talk radio” and "Classical" above each block of stations, identical to "Spain" in the demo.


Icon made by Webalys from www.flaticon.com


Released under GNU GPL v3.

Copyright 2017, 2018 Rafael Cavalcanti hi@rafaelc.org