Raspberry Pi Teleprompter

A simple, robust teleprompter system built on Raspberry Pi 3 that automatically launches PDF files from USB drives using the Zathura PDF viewer. Designed for reliable operation with hot-pluggable USB drives and foot pedal/numpad controls, essentially as a better alternative to using an iPad on stage for song lyrics. It is built for reliable use during live performances.

Features

• Hot-pluggable USB drives: Simply insert a USB drive with a PDF to start reading
• Automatic PDF detection: Finds and opens the first PDF file on any inserted USB drive
• Custom configurations: Support for per-drive Zathura configuration files
• Portrait mode display: Automatically rotates screen to 1280x720 portrait orientation
• Read-only filesystem: Uses overlayroot for reliability - safe to power off anytime
• Foot pedal support: Configured for foot pedal and numpad navigation controls
• Automatic cleanup: Kills PDF viewer when USB drive is removed

Hardware Requirements

• Raspberry Pi 3 (or newer)
• MicroSD card (16GB+ recommended)
• HDMI display
• USB flash drives for content delivery
• Optional: USB foot pedal for hands-free operation

Software Requirements

• Raspbian Debian 12 (bookworm)
• Wayland compositor (for wlr-randr)
• Zathura PDF viewer
• xdotool for window management

Quick Start

1. Flash Raspbian to your SD card
2. Clone this repository to /home/pi/
3. Run the setup script: ./setup/install.sh
4. Reboot the system
5. Insert a USB drive with a PDF file in the root directory

Installation

1. Prepare the Raspberry Pi

Raspberry Pi Imager.app was used to get the Raspberry Pi OS (64-bit), which is a port of Debian Bookworm with the Raspberry Pi Desktop, onto an SD card. An 8GB SD card was not large enough, the minimum might be 16GB (what I tested with was 128GB).

# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install zathura xdotool wlr-randr overlayroot -y

2. Clone and Install

cd /home/pi
git clone https://github.com/yourusername/raspberry-pi-teleprompter.git
cd raspberry-pi-teleprompter
chmod +x setup/install.sh
./setup/install.sh

3. Enable Overlayroot (Optional but Recommended)

sudo raspi-config
# Navigate to Advanced Options → Overlay File System → Enable

Usage

Basic Operation

1. Power on the Raspberry Pi
2. Insert USB drive containing PDF files
3. PDF automatically opens in Zathura
4. Navigate using foot pedal or numpad
5. Remove USB drive to close PDF and return to standby

USB Drive Setup

Your USB drive should contain:

• PDF files: Place any PDF in the root directory (first one found will be opened)
• zathurarc (optional): Custom Zathura configuration for this specific drive

Example USB Drive Structure

/media/pi/YOUR_DRIVE/
├── my-lyrics-for-the-show.pdf
└── zathurarc (optional)

Custom Configuration

See the zathura documentation for details on how to configure this. Note: The manpage for zathurarc is not as detailed as what is available on the website at https://pwmt.org/projects/zathura/documentation/

Create a zathurarc file on your USB drive to customize:

• Colors and themes
• Key bindings
• Display settings

Example zathurarc:

set default-bg "#000000"
set default-fg "#FFFFFF"
set recolor true
set recolor-lightcolor "#000000"
set recolor-darkcolor "#FFFFFF"

# Foot pedal mappings
map <space> navigate next
map <BackSpace> navigate previous
map <Right> navigate next
map <Left> navigate previous

File Structure

• scripts/: Core monitoring and PDF launch scripts
• autostart/: Desktop entry files for automatic startup
• config/: Default configuration files
• docs/: Additional documentation
• setup/: Installation and setup scripts

Key Components

Scripts

• zathura-autostart.sh: Monitors for USB drive insertion and launches PDF viewer
• zathura-usb-monitor.sh: Monitors for USB drive removal and closes PDF viewer

Autostart Files

• rotate-display.desktop: Rotates display to portrait mode, sets resolution
• zathura-autostart.desktop: Starts the PDF autostart monitor
• zathura-usb-monitor.desktop: Starts the USB removal monitor

Navigation Controls

Default key bindings for PDF navigation:

• Space/Right Arrow: Next page
• Backspace/Left Arrow: Previous page
• Home: First page
• End: Last page
• +: Zoom in
• -: Zoom out
• q: Quit (or remove USB drive)

Troubleshooting

PDF Not Opening

• Ensure PDF is in the root directory of the USB drive
• Check that the file has a .pdf extension (case-insensitive)
• Verify the USB drive is properly mounted under /media/pi/

Display Issues

• Check HDMI connection
• Verify display mode with: wlr-randr
• Ensure display supports 1280x720 resolution (at 60 frames per second)

Script Not Running

• Check autostart files are in /home/pi/.config/autostart/
• Verify script permissions: chmod +x scripts/*.sh
• Check system logs: journalctl -u user@1000

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test on actual Raspberry Pi hardware
5. Submit a pull request

License

MIT License - See LICENSE file for details