Building Custom Hardware Media Players for Raspberry Pi: GPIO Control & MPV IPC

If you are building embedded media players for Raspberry Pi, skip the bloated, 10-foot UI frontends like Kodi or LibreELEC. For a custom hardware-controlled build using physical GPIO buttons and an I2C display, the optimal stack is mpv controlled via its Unix domain socket IPC, paired with Python's gpiozero library. This approach yields frame-perfect playback control, minimal RAM overhead, and direct hardware integration without fighting a desktop environment.

The Verdict: Choosing the Right Media Player Backend

When designing a custom embedded media player, the backend engine dictates your IPC latency, memory footprint, and codec support. Below is the decision matrix for the three primary Linux media engines available on Raspberry Pi OS (Bookworm 64-bit).

Concrete Pick: We are using mpv. It strips away the GUI overhead, exposes a blazing-fast JSON IPC over a local Unix socket, and handles the Pi 5's hardware video decoding natively via ffmpeg.

Hardware BOM and Pin Mapping

This build targets the Raspberry Pi 5 (8GB variant) running Raspberry Pi OS Bookworm 64-bit. The 8GB model is specified to handle large local media libraries and prevent OOM kills when rendering high-bitrate 4K HEVC files while running the Python controller daemon.

GPIO Pin Mapping

Wiring, Assembly, and I2C Configuration

The Pi 5's internal I2C pull-up resistors are 1.8kΩ, which is sometimes too weak for the SSD1306 OLED if your wire run exceeds 5cm. We add external 4.7kΩ resistors to guarantee clean square waves on the SDA/SCL lines.

1. Enable I2C: Run sudo raspi-config, navigate to Interface Options > I2C, and enable it. Reboot.
2. Verify Bus: Run sudo i2cdetect -y 1. You should see 3c in the grid. If you see UU or nothing, check your SDA/SCL wiring.
3. Wire Buttons: Connect one leg of each tactile button to its respective GPIO pin, and the opposite leg to a common Ground (Physical Pin 9 or 14).
4. Wire OLED: Connect VCC to 3.3V (Pin 1), GND to Ground (Pin 6). Connect SDA to Pin 3, SCL to Pin 5. Solder the 4.7kΩ resistors between the 3.3V line and the SDA/SCL lines.
5. Install Dependencies:

   sudo apt update
   sudo apt install mpv python3-gpiozero python3-smbus python3-pil-font

Python Control Code: MPV IPC and GPIO Debouncing

This script targets the Raspberry Pi 5 (Bookworm 64-bit). It assumes mpv is launched as a background service listening on a Unix socket.
Launch mpv first: mpv --no-terminal --input-ipc-server=/tmp/mpvsocket --playlist=/home/pi/media/playlist.m3u

#!/usr/bin/env python3
"""
Raspberry Pi GPIO Media Controller for mpv via IPC Socket.
Targets: Pi 4 / Pi 5 running Bookworm 64-bit.
Dependencies: gpiozero, pillow, smbus2
"""

import socket
import json
import time
import sys
from gpiozero import Button

# --- Pin Definitions ---
BTN_PLAY_PAUSE = Button(17, bounce_time=0.05, pull_up=True)
BTN_NEXT = Button(27, bounce_time=0.05, pull_up=True)
BTN_PREV = Button(22, bounce_time=0.05, pull_up=True)
BTN_VOL_UP = Button(5, bounce_time=0.05, pull_up=True)
BTN_VOL_DOWN = Button(6, bounce_time=0.05, pull_up=True)

SOCKET_PATH = "/tmp/mpvsocket"

def send_ipc_command(command_list):
    """Sends a JSON array command to the mpv Unix socket."""
    try:
        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
            s.settimeout(0.5) # Prevent blocking if mpv hangs
            s.connect(SOCKET_PATH)
            # mpv IPC expects a JSON object with a 'command' key containing an array
            payload = json.dumps({"command": command_list}) + "\n"
            s.sendall(payload.encode('utf-8'))
    except ConnectionRefusedError:
        print("[ERROR] ConnectionRefused: mpv IPC socket not available. Is mpv running?")
    except socket.timeout:
        print("[ERROR] Socket timeout: mpv is not responding to IPC commands.")
    except FileNotFoundError:
        print("[ERROR] Socket file not found at /tmp/mpvsocket.")
    except Exception as e:
        print(f"[ERROR] Unexpected IPC failure: {e}")

# --- Button Callbacks ---
def toggle_play():
    send_ipc_command(["cycle", "pause"])

def next_track():
    send_ipc_command(["playlist-next", "force"])

def prev_track():
    send_ipc_command(["playlist-prev", "force"])

def volume_up():
    send_ipc_command(["add", "volume", 5])

def volume_down():
    send_ipc_command(["add", "volume", -5])

# --- Bind Events ---
BTN_PLAY_PAUSE.when_pressed = toggle_play
BTN_NEXT.when_pressed = next_track
BTN_PREV.when_pressed = prev_track
BTN_VOL_UP.when_pressed = volume_up
BTN_VOL_DOWN.when_pressed = volume_down

def main():
    print("GPIO Media Controller Active. Listening for button presses...")
    print("Press Ctrl+C to exit.")
    try:
        while True:
            time.sleep(1) # Keep main thread alive
    except KeyboardInterrupt:
        print("\nShutting down GPIO controller.")
        sys.exit(0)

if __name__ == "__main__":
    main()

Debugging: Socket Refusals and I2C Bus Errors

Embedded media builds fail at the intersection of hardware buses and software daemons. Here are the exact error strings you will encounter and how to resolve them.

Error 1: ConnectionRefusedError: [Errno 111] Connection refused

This occurs when the Python script attempts to connect to /tmp/mpvsocket but the OS rejects it.

• Cause 1 (Most Likely): mpv is not running, or it crashed due to a missing video output driver. Check systemctl status mpv or run it manually in the terminal to see the stdout errors.
• Cause 2: The socket path in the Python script does not match the --input-ipc-server flag used when launching mpv.
• Cause 3: Permissions issue. If mpv is running as a systemd service under the root user, but your Python script runs as pi, the socket will be inaccessible. Fix by adding --input-ipc-server=/tmp/mpvsocket and ensuring the service runs as the pi user.

Error 2: OSError: [Errno 121] Remote I/O error

This occurs when reading from the SSD1306 OLED display via I2C.

• Cause 1: Missing external pull-up resistors on SDA/SCL, causing signal degradation.
• Cause 2: The I2C interface was disabled in raspi-config after a system update.
• Cause 3: A cold solder joint on the OLED header pins. Reflow the VCC and GND pins.

Extending and Simplifying the Build

Once the base IPC controller is stable, you can adapt the hardware to fit your specific enclosure constraints.

How to Simplify

If you are building a headless audio-only streamer (e.g., a Spotify Connect or local FLAC player) and want to reduce BOM cost and wiring complexity:
Drop the OLED display entirely. Remove the I2C wiring and the pillow dependency. Rely on a web interface (like mpv's built-in websockets via a third-party UI) for track metadata, and keep only the Play/Pause and Volume GPIO buttons. This reduces the script's memory footprint by ~15MB and eliminates I2C bus debugging entirely.

How to Extend

For a premium audiophile build, replace the Volume Up/Down tactile buttons with a Rotary Encoder (e.g., KY-040 or a Bourns PEC11R).
Using gpiozero.RotaryEncoder, you can map clockwise rotation to ["add", "volume", 2] and counter-clockwise to ["add", "volume", -2]. This provides tactile, analog-style volume control that feels vastly superior to mashing a tactile button. Ensure you add 0.1µF ceramic capacitors across the encoder's A and B pins to ground to debounce the mechanical contacts in hardware, saving CPU cycles in Python.

For further reading on Pi hardware integration, consult the official Raspberry Pi GPIO and I2C documentation, and refer to the gpiozero API reference for advanced button debouncing techniques.