The On Stage Lyrics Browser is a footswitch-controlled teleprompter system for live performance. Its based on the Raspberry Pi and provides a simple curses-based interface to list text files from a USB flash drive directory and display their content.
The collection of scripts here, installed on a Raspberry Pi, will produce a basic, text-based browser for lyrics on a USB device.
Setup is fairly straightforward, and preparing the files/USB flashdrive are simple. Interfacing pedals with the Raspberry PI takes a little bit of work to operate properly, but is not an overly complex task.
The following screenshots show the two views available: Set List and Lyrics View:
- a udev rule to auto mount/umount USB upon insertion/removal
- a script that controls the interface display functions
- a script that sends mount information to the interface
- a script that sends umount information to the interface
You will also find schematics in the img directory to assist with building debounce circuits, or to illustrate how to connect footswitches without hardware debouncing.
This assumes a recent copy of Raspian is installed and everything is default.
Connect your PI to a network and be sure you can access APT repositories. This does not need to persist beyond initial setup.
$ sudo apt install -y python3-rpi.gpio git$ cd ~
$ git clone https://github.com/joshuabettigole/on-stage-lyrics-browser.git
$ chmod +x on-stage-lyrics-browser/bin/*This works best with the screen orientation rotated 90° or 270°
$ sudo nano /boot/config.txtAdd one of the following:
display_rotate=1
display_rotate=3
$ sudo ln -s ~/on-stage-lyrics-browser/etc/udev/rules.d/* /etc/udev/rules.d/Add the following to ~/.profile
setfont /usr/share/consolefonts/Lat15-TerminusBold32x16.psf.gz
LDIR=$(find /media -maxdepth 2 -type d -name 'lyrics' -print0 -quit 2> /dev/null)
if [ -d $LDIR ]; then
echo -n $LDIR | ~/on-stage-lyrics-browser/bin/lyricsbrowser.py
else
~/on-stage-lyrics-browser/bin/lyricsbrowser.py
fi
This sets the font size to something reasonably large - feel free to modify. It also looks to see if a USB was present and mounted during boot, checks for a lyrics directory, and passes that directory along to start the interface script upon login.
$ sudo raspi-config\To boot directly to the lyrics browser, enable autologin
Boot Options -> Desktop/CLI -> Console Autologin
To save time on bootup, disable networking
Boot Options -> Wait for Network at Boot -> No
Reboot your Pi and if all worked, you should see the lyrics browser after a few moments.
- The USB flash drive you use should be FAT formatted, with or without partitioning.
- On the flash drive, you should have a lyrics directory (all lowercase)
- Within the lyrics directory, the lyrics files need to be placed in alphabetical order. The easiest way to do this is to number them.
pi@raspberry:/media/usbhd-sda $ ls -l lyrics
total 64
-rwxrwxr-x 1 root users 1679 Oct 3 2018 01 - The Song That Never Ends.txt
-rwxrwxr-x 1 root users 869 Oct 11 2018 02 - Mary Had A Little Lamb.txt
-rwxrwxr-x 1 root users 11886 Oct 11 2018 03 - 99 Bottles of Beer.txt
-rwxrwxr-x 1 root users 735 Oct 11 2018 04 - Never Gonna Give You Up.txt
-rwxrwxr-x 1 root users 414 Oct 11 2018 05 - Spongebob Theme Song.txtFiles must be in .txt format (.rtf and .doc do not work). At some point in the future, support for adding colors will be considered.
If lyric lines are too long to fit within the width of the page, line breaks will be added and additional lines will be prefixed with " - ".
If lyrics for one song are too long to fit on one page, subsequent pages will be added, as necessary, for browsing. The lower right corner of the screen will display "Next Page ->" and the upper right corner displays the current page number: "Page #/##"
Upon bootup, if a USB device is present, it should be mounted and the lyrics directory path (if it exists) passed to the browser script.
If no USB device is present at boot, the browser should alert you to Insert USB Media. When a USB device is inserted, the browser will be notified and will automatically display the set list.
A USB device can be removed and reconnected at any point. The browser will be notified and act accordingly. Since the USB filesystem is mounted Read-Only, there should be no ill-effect from removal without proper unmounting.
The browser depends on GPIO interrupts for navigation. There is no facility for keyboard browsing. Three buttons/pedals are necessary to use the full features of the program, Previous, Menu/Select, and Next. The Previous button/pedal can be omitted at the cost of ease of navigation. See the Hardware section for details.
When using the browser, the bar across the bottom of the screen displays what each of the three buttons would do in any given context. When lyrics are displayed for a specific song, the top bar displays the song title and page information.
Interface language is in English (sorry, that's all I know). If you care to modify the language for your locale, modify the strings in the _e dictionary within the bin/lyricsbrowser.py file:
# Setup language strings
_e = {
'welcome': "Welcome",
'load_media': "Insert USB Media",
'select': "Select",
'menu': "Menu",
'next': "Next",
'prev': "Prev",
'first': "First",
'last': "Last",
'prev_page': "Prev Page",
'prev_song': "Prev Song",
'next_page': "Next Page",
'next_song': "Next Song",
'page': "Page"
}The browser runs a socket server that listens for the lyrics directory path to be passed in. It's possible to script Next, Previous, and Menu/Select with 3rd-party software or custom scripts of your choosing. By sending 'n', 'p', or 'm' to /tmp/lyricsbrowser.sock, the browser responds accordingly.
NEXT command
echo -n 'n' | nc -w1 -U /tmp/lyricsbrowser.sock PREVIOUS command
echo -n 'p' | nc -w1 -U /tmp/lyricsbrowser.sock MENU/SELECT command
echo -n 'm' | nc -w1 -U /tmp/lyricsbrowser.sock A properly configured Raspberry Pi attached to a widescreen monitor is a start. A keyboard and network connection is required to get past the installation process, but then should not be required at all.
A three button/pedal box of your own choosing. Buttons/pedals should be normally open (normally closed untested).
While some attempts are made in code to handle switch debouncing, there is still risk that one button cycle can advance multiple pages. It is HIGHLY recommend that a simple debounce circuit be added between the PI and the pedals/buttons. The following schematic outlines a fairly effective debounce circuit:
Without a hardware debounce circuit, the pedals/buttons should be connected from ground (pin 39) to:
- Previous: GPIO 13
- Menu: GPIO 19
- Next: GPIO 26
(these are pins 33,35,37)
The exact GPIO pins can be altered in the bin/lyricsbrowser.py file
gpiopin_prev = 13
gpiopin_next = 26
gpiopin_menu = 19- Work on a way to format text with color/bold. There is still no plan to use anything but .txt files, however.
- Build a shell script to simplify install.
- Preconfigured Raspberry PI OS image
- Provide a hardware list
- Offer pre-built debounce interface
The On Stage Lyrics Browser is licensed under the terms of the GNU Affero General Public License v3.0 and is available for free. See the License for details.
udev rules adapted from:
https://www.axllent.org/docs/view/auto-mounting-usb-storage/
switch debounce circuit from:
https://www.logiswitch.net/switch-debounce-diy_tutorial/method-4-hardware-debounce-for-spst-switches
rotating the raspberry pi screen from:
https://www.raspberrypi-spy.co.uk/2017/11/how-to-rotate-the-raspberry-pi-display-output/