Skip to content
This repository has been archived by the owner on Dec 12, 2021. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

PiFi Radio

PiFi Radio: A MPD web client to listen to radio.

Notice: This project was archived in July 2021 and shouldn't receive updates in the foreseeable future.

Table of contents

Meet PiFi Radio

PiFi Radio is a MPD web client to listen to radio.

If you have no idea what this means... You install it on a device such as the Raspberry Pi or anything with a speaker. Then, you open your browser from anywhere (e.g. your phone) to control it and listen to your favorite radio stations.

PiFi is an interface for MPD, so it has some advantages compared to other solutions, e.g. bluetooth or AirPlay. One of them is that the playback is completely independent from your phone. So you can continue to use it normally, play a video, lose connection or even turn it off, and your Pi will still continue to play the radio.

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

Some features

  • Responsive interface for phones, tablets and desktops.
  • Display stations clearly. No URLs or weird names.
  • Dark and light themes.
  • Easily search your radios.
  • Centralized list of stations. You get the same radios on every device.
  • Make some radios to be offered only to certain IPs. A use case for this is if there are tons of stations that only you listen and you don't want to pollute everyone else's list.
  • Organize your radios by categories.
  • Streaming URLs can be pasted directly from your web browser. Useful if you want to listen to a radio that was not previously added to the list.
  • Multi-language.
  • Usable by multiple people at the same time.


On phone:

Demo on mobile

On desktop:

Demo on desktop

Demo on desktop


While PiFi was imagined for the Pi, it should run on any computer with Ruby and MPD.

Check the installation guide.



$ sudo gem update pifi --no-document

Restart PiFi. If you are using the systemd service, this is done by:

$ sudo systemctl restart pifi


List of streams

PiFi needs a list of the radios you want to listen. A example is available here.

The list is read by default from /etc/pifi/streams.json. You can change this path creating a configuration file.

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": "",
     "Radio 2": ""

If you want to arrange the stations in categories, add a pair with the category name as the key and empty value, as shown below. This will add the headers "Talk radio" and "Classical" above each group of stations, such as "Spain" and "Christmas" in the demo.

     "Talk radio": "",
     "Radio 1": "",
     "Radio 2": ""

     "Classical": "",
     "Radio 3": "",
     "Radio 4": ""

PiFi configuration

It's now completely optional to have a configuration file for PiFi. You only need one if you want something different from the defaults.

The path is /etc/pifi/config.json and these are the options:

Key Default Description
mpd_host "" MPD host.
mpd_port 6600 MPD port.
mpd_password "" (none) MPD password.
streams_path "/etc/pifi/streams.json" Path to the JSON file containing the streams.
streams_path_priv "" (none) Path to JSON file containing additional streams. These will be shown only to the devices listed on special_ips.
special_ips [] (none) The IPs of the devices to show additional streams. Example: ["", ""]
serve_static true If we should serve static resources. Set it to false if your web server is already doing it.

If you want to change any of these options, download the sample file and edit it to your needs:

$ sudo mkdir -p /etc/pifi
$ sudo wget -O /etc/pifi/config.json
$ sudo -e /etc/pifi/config.json


PiFi can be run:

  • With the pifi command. Check pifi -h for the options available.
  • If you installed the systemd service, with sudo systemctl start pifi.
  • At boot enabling the systemd service with sudo systemctl enable pifi.

On your mobile browser, I suggest you add PiFi Radio to your home screen, for easier access.

Help me translate

You can help me adding a new language to PiFi or improving an existing translation. The translation files are placed here.

Improving an existing translation

The default language for PiFi is English, so you should use it as a reference.

  1. Open the translation file and the English file.
  2. Fill empty strings and fix any bad translations.
  3. Send a pull request.

Adding a new language

  1. Copy the en folder, renaming it to the new language code (e.g. es-ES).
  2. On translation.json, translate the strings. If you aren't sure of some, please make them empty.
  3. Send a pull request.

Some projects using PiFi Radio


Buy me a coffee

If you find PiFi useful, you can show your support here:

Buy Me A Coffee


Licensed under GPLv3

Copyright (C) 2017-2021 Rafael Cavalcanti