Build a 4K Raspberry Pi Media Streamer with Tactile GPIO Control

The Raspberry Pi 5 (4GB variant) is the undisputed king of DIY home theater PCs in 2026. Thanks to its dedicated HEVC hardware decoder and dual 4Kp60 HDMI outputs, it handles high-bitrate 4K HDR streams without breaking a sweat. But running a standard desktop OS with a wireless mouse defeats the purpose of a dedicated living room appliance.

In this guide, we are building a headless raspberry pi media streamer that uses the mpv backend for flawless video rendering, a MAX98357A I2S DAC for jitter-free audiophile sound, and a KY-040 rotary encoder for physical, tactile playback control. No laggy Bluetooth remotes, no desktop environment overhead—just pure, hardware-accelerated streaming.

Hardware Spec Sheet & Parts List

Before we touch a breadboard, source these exact components. Substituting the DAC or the Pi variant will break the pin mapping and software overlays provided below.

GPIO Pin Mapping & Wiring

We are sharing the GPIO header between the I2S audio bus and the rotary encoder. The Raspberry Pi 5's 40-pin header remains backward compatible with Pi 4 I2S pinouts, but physical pin numbers must be verified against the BCM (Broadcom) GPIO numbering used in our Python script.

Software Setup & Compilable Control Code

This build targets the Raspberry Pi 5 4GB running Raspberry Pi OS (Bookworm, 64-bit Lite). We skip the desktop environment to save RAM and CPU cycles for video decoding.

First, enable the I2S hardware overlay and install our dependencies. SSH into your Pi and run:

# Enable I2S DAC overlay
sudo nano /boot/firmware/config.txt
# Add this line at the bottom: dtoverlay=hifiberry-dac

# Install media player and Python GPIO libraries
sudo apt update
sudo apt install mpv python3-gpiozero python3-evdev socat

Below is the complete, production-ready Python script. It uses gpiozero to read the encoder and communicates with mpv via its local Unix IPC socket. This is vastly superior to killing and restarting the player process, as it allows seamless volume and pause control without dropping the video stream.

#!/usr/bin/env python3
"""
Raspberry Pi Media Streamer Tactile Controller
Targets: Raspberry Pi 5 (Bookworm Lite)
Dependencies: gpiozero, mpv (running with --input-ipc-server)
"""
import subprocess
import socket
import json
import sys
import time
from gpiozero import RotaryEncoder, Button
from signal import pause

# --- PIN DEFINITIONS (BCM Numbering) ---
PIN_ENC_CLK = 5   # Physical Pin 29
PIN_ENC_DT = 6    # Physical Pin 31
PIN_ENC_SW = 13   # Physical Pin 33

IPC_SOCKET = '/tmp/mpvsocket'
STREAM_URL = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8' # Replace with your media

def send_mpv_command(command_list):
    """Sends a JSON-formatted command to the mpv IPC socket."""
    try:
        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        sock.connect(IPC_SOCKET)
        payload = json.dumps({'command': command_list}) + '\n'
        sock.sendall(payload.encode('utf-8'))
        sock.close()
    except FileNotFoundError:
        print('Error: mpv IPC socket not found. Is mpv running?')
    except Exception as e:
        print(f'IPC Error: {e}')

def on_encoder_turn():
    """Adjusts volume based on encoder rotation direction."""
    # encoder.value ranges from -1 to 1 based on max_steps
    # We map this to a volume percentage (0-100)
    new_vol = int((encoder.value + 1) * 50) 
    send_mpv_command(['set_property', 'volume', new_vol])
    print(f'Volume set to: {new_vol}%')

def on_button_press():
    """Toggles play/pause state."""
    send_mpv_command(['cycle', 'pause'])
    print('Toggled Play/Pause')

def start_mpv_process():
    """Launches mpv in the background with IPC enabled."""
    cmd = [
        'mpv', '--no-terminal', '--fullscreen',
        '--hwdec=auto', '--ao=alsa',
        f'--input-ipc-server={IPC_SOCKET}',
        STREAM_URL
    ]
    try:
        # Start mpv detached from the Python script's lifecycle
        process = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
        time.sleep(2) # Allow socket to initialize
        return process
    except FileNotFoundError as e:
        print(f'FATAL: {e}')
        sys.exit(1)

if __name__ == '__main__':
    print('Initializing GPIO and Media Streamer...')
    
    # Initialize Hardware
    encoder = RotaryEncoder(PIN_ENC_CLK, PIN_ENC_DT, max_steps=2, wrap=False)
    play_pause_btn = Button(PIN_ENC_SW, bounce_time=0.05, pull_up=True)
    
    # Bind Events
    encoder.when_rotated = on_encoder_turn
    play_pause_btn.when_pressed = on_button_press
    
    # Launch Media Player
    mpv_proc = start_mpv_process()
    
    try:
        print('Controller active. Turning knob adjusts volume, pressing pauses.')
        pause() # Keep script alive
    except KeyboardInterrupt:
        print('\nShutting down streamer...')
        mpv_proc.terminate()
        sys.exit(0)

Debugging: First Three Things to Check When It Fails

Headless Linux audio and IPC sockets are notorious for failing silently. If your script crashes or the media doesn't play, check these three things in order.

1. The Exact Error: FileNotFoundError: [Errno 2] No such file or directory: 'mpv'

Ranked Causes:

1. mpv is not installed: Raspberry Pi OS Lite does not include media players by default. Run sudo apt install mpv.
2. Virtual Environment Isolation: If you are running this inside a Python venv, the environment might not inherit the system $PATH. Use the absolute path in the subprocess call: /usr/bin/mpv.
3. Corrupted Package: If apt threw network errors during install, purge and reinstall: sudo apt --purge autoremove mpv && sudo apt install mpv.

2. Audio is Stuttering or Outputting via HDMI Instead of I2S

If sound is coming from your TV instead of your MAX98357A speakers, the I2S overlay failed to load. Check dmesg | grep -i i2s. If you see errors, ensure your /boot/firmware/config.txt contains dtoverlay=hifiberry-dac and that you have completely removed the default dtparam=audio=on line, which forces the PWM audio driver to claim the hardware.

3. IPC Socket Connection Refused

If the Python script throws ConnectionRefusedError: [Errno 111], mpv hasn't finished initializing the socket before the GPIO event fired. Increase the time.sleep(2) delay in the start_mpv_process() function to 4 seconds, especially if you are streaming from a slow network mount (SMB/NFS) where mpv hangs on buffering before opening the IPC server.

Extending or Simplifying the Build

Not everyone wants to maintain custom Python scripts. Here is how to adapt this project to your specific maintenance tolerance.

To Simplify (The Appliance Route):
If you don't care about custom GPIO control and just want a Netflix/YouTube machine, ditch Raspberry Pi OS and flash LibreELEC. It is a bare-minimum Linux distribution built solely to run Kodi. You lose the Python GPIO knob control, but you gain a polished UI, automatic updates, and native CEC support (allowing your TV remote to control the Pi via HDMI).

To Extend (The Smart Home Route):
Replace the rotary encoder with an MQTT subscriber. By installing paho-mqtt, your Python script can listen to a Home Assistant topic like homeassistant/media/livingroom/set. This allows you to trigger the streamer from a wall-mounted smart switch or an automation when you enter the room, turning the Pi into a fully integrated smart home audio endpoint.

Frequently Asked Questions

Can a Raspberry Pi 5 stream 4K HDR without dropping frames?

Yes, but with a caveat regarding the codec. The Raspberry Pi 5 features a dedicated hardware video decoder that flawlessly handles H.265 (HEVC) 4Kp60 streams, which covers 95% of modern streaming services and local Plex/Jellyfin libraries. However, it lacks hardware decoding for AV1. If your media library uses AV1 encoding, the Pi 5 will fall back to software decoding, which will max out the CPU and drop frames at 4K. Stick to HEVC or H.264 for guaranteed smooth playback.

How do I fix audio stuttering on my Raspberry Pi media streamer?

Audio stuttering on I2S DACs is almost always a clock jitter or ALSA buffer issue. First, ensure you are using a high-quality 5V power supply; voltage ripple on the 5V rail directly injects noise into the MAX98357A's clock generator. Second, increase the ALSA buffer size in your mpv launch arguments by adding --audio-buffer=0.2. If the issue persists, verify your I2S jumper wires are under 6 inches long to prevent signal degradation on the BCLK line.

Is LibreELEC better than Raspberry Pi OS for a media streamer?

It depends on your definition of 'better.' LibreELEC is better if you want a plug-and-play appliance with Kodi's UI, native TV remote (CEC) support, and zero Linux maintenance. Raspberry Pi OS Lite is better if you want to build a custom, headless backend (like this mpv project), integrate MQTT smart home controls, or run background tasks like Pi-hole or a Home Assistant server alongside your media streaming. For pure DIY makers, Pi OS offers vastly more flexibility.