MANUAL

Phoniebox Manual

Before you can run the Phoniebox, you need to have it installed and configured. Make sure to go through the installation and configuration first.

In this manual you will learn:

• How to connect to the Phoniebox from any computer to add and edit audio files.
• How to register new RFID cards, assign them a human readable shortcut and add audio files for each card.
• How to add webradio stations and other web streams to the playout files - and even mix web based and local files.
• How to control the Phoniebox through the web app.
• How to assign cards specific tasks such as changing the volume level or shutting down the Phoniebox.

Sample content

... for kids

To get going, this will create a few (German) kids podcasts:

cd /home/pi/RPi-Jukebox-RFID/scripts/helperscripts/; ./CreatePodcastsKidsDeutsch.sh

... for testing

If you just finished your install and you want to see if it works, you can create some sample content with the following command in the terminal:

cd /home/pi/RPi-Jukebox-RFID/scripts/helperscripts/; ./CreateSampleAudiofoldersStreams.sh

This will create a collection of:

• podcasts
• sample audio files (.mp3, .wav, .aac, .flac, .ac3, .ogg, .m4a, .aiff, .wma)
• live streams
• nested folders

You can later delete these folders with the following command:

cd /home/pi/RPi-Jukebox-RFID/scripts/helperscripts/; ./DeleteSampleAudiofoldersStreams.sh

Changing Phoniebox settings

There is a folder called settings which contains audio and card settings. How to change the card settings, you will find below in this document. Here is a list of the other available settings.

settings/Audio_iFace_Name

This is a file containing a string, by default PCM.

Inside settings/Audio_iFace_Name is the iFace name of the sound card. By default for the RPi this would be PCM. But this does not work for every setup. If you are using phatbeat as a DAC for example, you need to change the content of Audio_iFace_Name from PCM to Master or Speaker. Other external sound cards might use different interface names. To see if PCM could work for you, type amixer sget PCM. To list all available iFace names, type amixer scontrols.

settings/Max_Volume_Limit

This is a file containing a number, by default 100. If one is using an audio amplifier (like the pHAT BEAT) without a physical volume limiter (like a potentiometer) your Phoniebox can get very loud "accidentally". The maximal volume can be set in settings/Max_Volume_Limit. Can be edited in the Settings page of the web app.

settings/Audio_Volume_Change_Step

This is a file containing a number, by default 3. Changing this number affects the volumeup and volumedown function in the web app or triggered by RFID cards. Increasing the number will result in larger volume jumps. Decreasing the number will result in smaller changes of the volume. Can be edited in the Settings page of the web app.

settings/Latest_RFID

Contains the latest RFID used, which could start an audio playout but might also control the system (e.g. volume up or shutdown). Created in script rfid_trigger_play.sh

settings/Latest_RFID_Played

Contains the latest RFID that triggered an audio folder piped to playout_controls.sh -c=playlistaddplay -v=... Created in script rfid_trigger_play.sh

settings/Latest_Folder_Played

Contains the last folder that was being played. Created in playout_controls.sh AND rfid_trigger_play.sh (currently all play triggers - webapp and RFID are piped through rfid_trigger_play.sh. So it seems redundant. But who knows if at a later dev stage some scripts might use only playout_controls.sh).

settings/Latest_Playlist_Played

Contains the last playlist name that was being played. Used in rfid_trigger_play.sh to establish if a second swipe on the same playlist was made.

settings/Playlists_Folders_Path

Contains the absolute path to the folder containing playlists. Default value: "/home/pi/RPi-Jukebox-RFID/playlists" Used in rfid_trigger_play.sh.

settings/Second_Swipe

Contains RESTART or PAUSE or NOAUDIOPLAY. This establises if a second swipe of the same RFID card either

• starts the playlist from the beginning (RESTART) or
• toggles pause and play (PAUSE) for the current playlist or
• ignores to play audio at all (NOAUDIOPLAY) only executes commands (like volume up or shutdown).

The behaviour can be edited in the Settings page of the web app.

NOTE: in the web app you can set Resume for each folder, which means that the content of this folder starts from the time where it was last stopped. This can have implications when combining this behaviour with the second swipe: If you choose Restart for the Second Swipe AND Resume for a folder is enabled, swiping the card a second time will seem to do nothing - the playout continues. However, this is the correct behaviour: swiping the same card a second time triggers stop and play. The play command then checks if the folder has Resume enabled, if it does, it will play from the last stored stop position - which was the same second swipe.

settings/Idle_Time_Before_Shutdown

This feature is helpful for powerbank users who want to save battery power. It shuts down the idle Phoniebox after a specified number of minutes. If you want to use the idle shutdown feature, you can specify the number of minutes in this file, after which the Phoniebox will shut down when either the audio player is not playing and/or the sound has been muted. Can be edited in the Settings page of the web app.

IMPORTANT: if you do not want to use auto shutdown, the number in the file must be 0

Connecting to the Phoniebox to add files

You need to connect to the Phoniebox in order to manage audio files and register new RFID cards. There are two ways to connect to the Phoniebox.

1. Using SSH to log into the Phoniebox
2. Connect over the home network

Most of the Phoniebox management should be done with the second option: connecting over your home network. This is the easiest way to add and remove audio files, because you are using your file manager to copy and paste files onto the Phoniebox. Copying files to the Phoniebox using the SSH login is actually more complicated.

Connecting over SSH

Find out more about how to connect over SSH from Windows, Mac, Linux or Android on the official RPi page.

Connecting with Apple Mac OS X

• Start the Finder application.
• Select Go pulldown menu and go to Connect to server...
• As the server address, type smb:// followed by the IP address of your Phoniebox. In my case this would be: smb://192.168.178.199
• The following screen requires you to login as a Registered User. Name and password are the ones you specified when installing the Samba server. I suggested to use pi and raspberry.
• Selecting Remember this password... will connect to the Phoniebox automatically.
• Now, if you go to the finder, at the bottom left menu under Shared you will find the IP address of your Phoniebox.
• Clicking on the IP in the left menu will open the files on the Phoniebox. Under pi_network you should see: audiofolders, shotcuts, placeholder and once you registered RFID cards also the file latestID.txt (all of which will be explained later).

Connecting with Linux / Ubuntu

• Open the windows manager.
• Navigate to Network in the left menu or select File > Connect to server... from the pulldown menu.
• Clicking from Network to Windows Network will bring you to the Raspberry Pi home network.
• If you chose File > Connect to server..., type smb:// followed by the IP address of your Phoniebox. In my case this would be: smb://192.168.178.199
• In both cases, you will be exposed to the login screen eventually.

Registering a new RFID card or key fob

Registering a card means: linking the card ID to an action (like: volume up) or a folder (containing audio files or a link to a podcast or live stream). Then, when swiping the card, the audio folder is being played or the action performed.

Registering cards using the web app

The easiest way to add and edit cards is done using the web app. Let's start with an empty Phoniebox. This assumes that you might already have audio files on the Phoniebox. How that's done you can see below.

Link a new card to a folder or stream

• Go to the web app (i.e. open the Phoniebox's IP address in the browser of a connected device/PC).
• Near the top of the page you will find a button saying "Register new card ID". Click it.

• This will bring up a form looking like this: The card ID will be updated as you swipe a new card over the Phoniebox. Do not try to edit the card ID manually, it will revert to the last swiped ID.
• Either select an audio folder in the drop down menu near the top OR
• Add the URL of a webradio, podcast, live stream, select the type of stream and give this new stream a name.
• Press 'submit' and you are set.

Edit card through web app

On the home page you will find a link in the list of audio folders to the card that is registered to this folder. Click the card ID with the wrench next to it, so come to the edit form.

Registering cards manually (through samba without the web app)

This is how you figure out the ID of a RFID card:

1. Boot up the Phoniebox.
2. Swipe the RFID card across the Phoniebox (you should hear a 'beep' sound when the reader recognises the card).
3. Open the shared folder in your windows manager over the home network (see above for details on how to connect).
4. Open the file latestID.txt by double clicking it. This file contains the information you need.

The file contains information about the card like the following:

Card ID '0594672283' was used at '2017-02-02.12:26:08'.
This ID has been used before.
The shortcut points to audiofolder 'stop'.

The first line lists the ID of the card: 0594672283.

The second line tells us that the card has been used before. Note that every time you swipe a card, the file latestID.txt is being created. Therefore it is very likely this file notes a card has been used before.

The third line is giving us information about a human readable shortcut given to this ID. In this case, there is a folder named stop - which can contain audio files or text files with links to web streams.

Making a 'human readable' shortcut for a card

Imagine you have a card with a sticker of birds on it. Every time somebody swipes the bird card across the Phoniebox, you want it to play a lot of bird sounds. And when you add or delete birds from the playlist, you don't want to need to know the card ID. You just want to drop the files into a folder called birds.

This is why you can assign human readable names for card IDs. This is how you do it:

1. Swipe the card across the Phoniebox.
2. Open the file latestID.txt to find out the card ID (e.g. 0594672283).
3. Navigate to the folder shortcuts in your windows manager.
4. Open the file of the same name as the card ID with a text editor.
5. Change the content of that file to birds

Now you have told the Phoniebox that every time the card with the ID 0594672283 is swiped across, play what's in the folder birds. Let's continue and make that folder and the audio files inside.

Important:

• Make sure your editor does not add a line break at the end of the shortcuts file. It must only contain the folder name.
• If your folder contains white spaces (e.g. bird songs) do not escape the white spaces in the shortcuts file (e.g. do NOT write bird\ songs).
• If you are linking a subfolder, add the relative path to your audio folder. Correct: animal songs/bird songs. Not correct: home/pi/RPi-Jukebox-RFID/shared/audiofolders/animal songs/bird songs.

Adding new audio files and create a playlist for a new card

Following the previous step, we now have a card that triggers the Phoniebox to seek the folder birds and play the contents of that folder as an audio playlist. This is how you create the folder and fill it with content:

1. Open your windows manager and connect to the Phoniebox via the home network.
2. Navigate to the folder audiofolders.
3. Create a new folder inside this folder called birds.
4. Copy audio files into this folder.

That's it. If you swipe the card across the Phoniebox, it will play all the files in the folder birds.

Note: files are played in alphabetical order. If you want to change the order, rename the files accordingly.

Show covers in web app

If your audio folder contains a file called cover.jpg (lowercase!) it will be displayed in the web app above the player controls.

Playing audio files from a USB stick

If you have your audio files on an external USB stick, you need to point the folder audiofolders to the external USB device. The USB-stick is automatically mounted to /media/usb0.

You can do this by creating a symbolic link to the USB stick with the following command:

ln -s /media/usb0/* /home/pi/RPi-Jukebox-RFID/shared/audiofolders/

To make the USB stick fully accessible to the web app, too, here is what you need to do:

Read and write to USB via web app

Assuming your USB stick has been formatted to FAT32 (which is the common format allowing easy access in Windows and OSX), you need to install usbmount to mount the stick automatically.

sudo apt-get install usbmount

In Rasbian stretch change the config file:

sudo nano /lib/systemd/system/systemd-udevd.service

and change MountFlags=slave to MountFlags=shared. Now you can see the USB stick under /media/usb0. But it is read only, not writeable. To change that, edit the config:

sudo nano /etc/usbmount/usbmount.conf

And add the following:

FS_MOUNTOPTIONS="-fstype=vfat,flush,gid=users,uid=33,umask=007,iocharset=utf8"

The problem are the access rights for the user pi and www-data (the webserver). The above line fixes this, because:

• pi is part of gid=users
• www-data has the uid=33

This is work in progress, please share more insights in the issue section.

Adding webradio station and other online streams

In short:

• Create a folder inside shared/audiofolders/
• Add a textfile inside the new folder containing the URL of the stream (see below for naming conventions)
• Assign the new folder to a card ID (see above)

An audio stream from the web can mean two things:

1. A live stream that plays endlessly (e.g. webradio station).
2. A clip or file on the web that has a URL (e.g. soundcloud audio file).

These two are actually very different and will result in different behaviour of the Phoniebox. A live web stream never stops. This means that it will continue to play until you shut down the machine or start something else by swiping a different card across the Phoniebox.

A static file on the web is more or less the same as a local file. The Phoniebox will play the content of the file and once it's finished, it will be idle waiting for the next card or continue playing the next file in the folder (see about mixing audio files and web streams in the next section).

This is how you add a web stream to a specific card:

Firstly, you need to get the URL from the file or stream.

• Static files: these will point straight to the file and will look something like this: http://www(...)/filename.mp3
• Web radio streams: often, radio stations list their URL to the stream. In some cases, they link to a file ending with e.g. m3u or .pls. This would be a playlist which in turn will contain the stream URL. Save the file, open it with a text editor and use the last URL inside (sometimes the first URLs play jingles).

Now you are ready to add the stream to your Phoniebox.

1. Register the card, create a shortcut and the matching folder as described above.
2. Navigate to the folder you just created.
3. Create a text file ending with .txt. For streams use livestream.txt (because I am working on podcasts and podcast.txt will be processed differently, same goes for spotify.txt at a later stage).
4. Open the text file and copy the URL of the live stream (or static file) into the file.

That's it. Now, if you swipe with the card, the Phoniebox will open the matching folder, open the text file and send the content to the audio player.

Good to know: you can find a number of radio stations at the Community Radio Browser. When you find a station you like, click on the Save icon which will download a file radio.pls. You can open this file with a text editor and within the file find the URL of the live web radio stream.

Troubleshooting:

• if you are playing files with a high quality, they might break off and/or stutter. This is a buffering issue. See troubleshooting.
• if you add a web stream or URL which is invalid, this might create the audio player to revert to what it played the last time it was launched. If your Phoniebox seems to become erratic, check the URLs in your audio folder.

Mixing audio files and web streams

As described above, the media player will (attempt to) play any content it finds in a folder in alphabetical order. I decided to work with the audio player because it is very robust and really tries to play anything it can. This means it also mixes audio files and web streams.

If you want to create such a mix, simply mix the content inside the audio folder. The Phoniebox will play all content in alphabetical order. Keep this in mind if you plan the order of the playlist.

Note: if you add a URL from a live web station to the playlist, the Phoniebox will never get to play the files after this URL - because the live radio never stops.

Adding podcasts

The podcast feature allows you to play a podcast on your Phoniebox. The latest episode will be played automaticall. Using the previous and next option on the web app, with RFID cards or GPIO buttons, you can skip to other episodes as you would in any other playlist. The number of episodes the Phoniebox will play depends on the number of episodes listed in the podcast.

In short:

• Create a folder inside shared/audiofolders/
• Add a textfile named podcast.txt inside the new folder containing the podcast URL
• Assign the new folder to a card ID (see above)

Good to know: A podcast is an RSS-feed containing a list of items featuring the special enclosure tag. This special tag has the url attribute pointing to an audio file on the web. The file ending for a podcast is often .rss or .xml.

The Phoniebox Web App

You can control the Phoniebox with your mobile phone, smart TV or through a browser on a computer. On any device connected to the same WiFi home network as your Phoniebox, open the browser and type in the static IP address of your Phoniebox. If you do this on your phone, the web app should something look like this:

Change the volume level

At the top of the page, you can select the volume level in a pulldown menu. Hit Set volume and the volume on your Phoniebox will be changed. This change will remain active even after a reboot.

Play and list audio files

All the folders and containing audio files are listed in the web app. In case there are more folders on the Phoniebox than RFID cards in use, you can also play the audio files which have no corresponding RFID card using the web app.

Scroll to the folder you want to play and hit the Play icon left of the folder name. This will start the playout on the Phoniebox.

If you want to see the files contained inside an audio folder, click on the folder name. This will list the content beneath the folder name. A second click on the folder name will hide the list of files again.

Stop playout

At the top of the page you can see the Stop Player icon. If you are using a mobile device, this option might be hidden within the navigation, in which case, click the hamburger icon to see the Stop Player option.

Click on the Stop Player icon to stop the playout on the Phoniebox.

Shutdown the Phoniebox gracefully

At the top of the page, on the right side, you can see the option Shutdown. If you are using a mobile device, this option might be hidden within the navigation, in which case, click the hamburger icon to see the Shutdown option.

Click on Shutdown to shutdown the RPi gracefully. While it is perfectly save to shutdown the RPi the hard way by unplugging the power supply, it is being rumoured that a graceful shutdown extends the life expectancy of the SD card in your RPi. I have no clue if that is true and scientifically proven.

If you use the Shutdown option, unplug the RPi power supply after the machine has shut down to save energy.

Phoniebox controls using RFID cards

This requires you to connect to the Phoniebox over SSH, because it requires to edit a script on the machine. Find out more about how to connect over SSH from Windows, Mac, Linux or Android on the official RPi page.

If you are unsure about connecting over SSH, you can also take the Phoniebox and connect it to a monitor, keyboard and mouse and work on the machine directly.

The main file controlling the Phoniebox and the audio playout is called:

/home/pi/RPi-Jukebox-RFID/scripts/rfid_trigger_play.sh

This script operates in two stages. Firstly, it attempts to match the card ID with a command that controls the Phoniebox. If there is no match, it will move on and look for a folder which is associated with the card that contains audio material - and play the content.

If you want to assign certain control commands with RFID cards, firstly register the card to find out the unique ID (see above for details).

The commands which are available in the script are:

• CMDMUTE - will mute the Phoniebox. The file(s) continue to play, but there will be no sound coming out.

• CMDVOL30 to CMDVOL100 - sets the volume to the percentage passed on, being one of: 30%, 50%, 75%, 85%, 90%, 95%, 100%.

• CMDVOLUP and CMDVOLDOWN - increases or decreases the volume by the percentage step defined in

• CMDSTOP - stop the media player (without changing the volume).

• CMDSHUTDOWN - shutdown the Phoniebox. While you can switch off the RPi the hard way by unplugging it from the power source, in the long run using the proper shutdown method extends the life expectation of your Phoniebox. After the shutdown, you still should detach the power supply - if only to make sure the speakers don't drain power.

• CMDREBOOT - reboot the Phoniebox

• CMDNEXT and CMDPREV - to skip one track forward or backward

• CMDPAUSE and CMDPLAY - pause/toggle and resume audio playout

• STOPAFTER5 to STOPAFTER60 - timer to stop after x minutes

• SHUTDOWNAFTER5 to SHUTDOWNAFTER60 - timer to shutdown the Phoniebox after x minutes

• DISABLEWIFI and ENABLEWIFI - toggle wifi like with cellphones in airplane mode, to increase battery live and reduce radiation

• CMDSHUFFLE - toggle shuffle mode (not only for the current playlist)

Once you have logged in to the RPi over SSH or booted with monitor and keyboard attached, open the script in the nano editor:

$ nano /home/pi/RPi-Jukebox-RFID/settings/rfid_trigger_play.conf

Scroll down until you see the list of available commands:

CMDMUTE="%CMDMUTE%"
CMDVOL30="%CMDVOL30%"
CMDVOL50="%CMDVOL50%"
CMDVOL75="%CMDVOL75%"
CMDVOL80="%CMDVOL80%"
CMDVOL85="%CMDVOL85%"
CMDVOL90="%CMDVOL90%"
CMDVOL95="%CMDVOL95%"
CMDVOL100="%CMDVOL100%"
CMDVOLUP="%CMDVOLUP%"
CMDVOLDOWN="%CMDVOLDOWN%"
CMDSTOP="%CMDSTOP%"
CMDSHUTDOWN="%CMDSHUTDOWN%"
CMDREBOOT="%CMDREBOOT%"

Change the values of the commands you want to assign, leave the other ones unchanged. In our example, the changed list might look like this:

CMDMUTE="1352647584"
CMDVOL30="%CMDVOL30%"
CMDVOL50="%CMDVOL50%"
CMDVOL75="%CMDVOL75%"
CMDVOL80="%CMDVOL80%"
CMDVOL85="%CMDVOL85%"
CMDVOL90="%CMDVOL90%"
CMDVOL95="%CMDVOL95%"
CMDVOL100="%CMDVOL100%"
CMDVOLUP="984000025364"
CMDVOLDOWN="2636453782"
CMDSTOP="%CMDSTOP%"
CMDSHUTDOWN="%CMDSHUTDOWN%"
CMDREBOOT="%CMDREBOOT%"

Save the changes and close the editor. The changes takes effect immediately.

Note: if you (accidently) assign a command and an audio folder to the same card, the Phoniebox will not play the audio. It will only execute the command.

Troubleshooting / FAQ

... moved to a new document: Troubleshooting-FAQ.md