Project Overview: Raspberry Pi Streaming and Recording Setup

This project aims to do one thing well and that is to stream to a rtmp endpoint with very little setup and effort.

Transform a Raspberry Pi into a powerful yet simple and convenient streaming and recording device using a USB capture card and a Web UI. The compact setup allows for seamless streaming to platforms like Twitch, Owncast, PeerTube, YouTube, and recording captured video and audio.

All you have to do is connect it to the internet, plug in your HDMI source from a console, Steam Deck, TV, or any device that can be captured via HDMI. When you are ready to stream, press the Start Stream button. Press the Stop Stream button when you are done. It can also record whatever is being captured with a different button.

You can also control the Raspi-Streamer using the Web UI from any web browser. Just visit http://<ip_address_of_pi>:5000 from your mobile device connected to the same network to start, stop, and manage your streams and recordings remotely.

I would compare this project to professional-grade devices like the LiveStream Broadcaster Pro or the BoxCaster, but without the hefty price tag and subscription fees. This setup can be used with a professional camera to stream and/or record live events, making it ideal for concerts, churches, conferences, and seminars. Additionally, it can be completely wireless when connected to a cellular hotspot and battery pack.

Key Features

• Streaming: Capture video via a USB capture device and stream it in real-time to an RTMP server, ensuring smooth and reliable video output.
• Audio Synchronization: Achieve perfect sync between audio and video using ALSA for audio input.
• Automated Control: A Python script runs as a system service, enabling the device to handle streaming and recording commands autonomously.
• Network Accessibility: With Samba configured, easily access and manage your recordings over the network from any device.
• Web UI: Control and configure Raspi-Streamer from any web browser. Just visit http://<ip_address_of_pi>:5000 from your mobile device connected to the same network.
• Versatile Use Cases: Ideal for streaming and recording gameplay, live events, concerts, GoPro cameras, and any other HDMI output devices.
• Compact and Convenient: The small form factor of the Raspberry Pi makes it easy to integrate into any setup, offering a simple and portable solution for streaming and recording.

Components Used

• Raspberry Pi 5: The core of the setup, handling all processing and control logic.
• USB Capture Device: Captures video from an external source.
• ALSA (Advanced Linux Sound Architecture): Handles audio input and audio capture.

Setup guide

Prerequisites before installing

• You have already installed the Lite version of Raspberry Pi OS.
• A user has been created.
• Your capture device is currently plugged into the Raspberry Pi.

Install necessary packages

sudo apt install git

Installer script

• Clone this repo to your Raspberry Pi.
• git clone https://github.com/teklynk/raspi-streamer
• cd raspi-streamer
• ./install.sh
• That's it. No need to manually install.
• Review the install.sh script if you would like to see what it installs and how.

Additional Notes

• Samba Setup:
  • Customize the Samba configuration (smb.conf) according to your security and network requirements.
  • Adjust permissions (create mask, directory mask) in the Samba share configuration as necessary for your use case.
• Audio Latency:
  • Audio latency may need adjustment depending on your capture device. Experiment with different -itsoffset values in stream_control.py. Start with: "-itsoffset", "0.1".
• Service Management:
  • If you make changes to the stream_control.py script or .env, restart the stream_control service to apply the updates.
• Performance Tips:
  • Raspberry Pi 5 will give you the best results.
  • The values in sample.env worked best for testing on a Raspberry Pi 4 8GB with Twitch and Owncast. Your experience may vary.
  • KEYFRAME_INTERVAL=60 corresponds to a 2-second keyframe interval, calculated as framerate * 2 (e.g., 30 fps * 2 = 60).
• Stream & Record:
  • If you would like to record a local copy while you stream you will need to set the m3u8 URL. The Stream & Record feature will not work if this is not set. This is becuase the stream & record feature is simply recording the stream using the m3u8 url. Keep in mind that if the stream goes does down, then so does the recording. Recordings are saved in the recordings directory. Some platforms like Twitch, Kick, YouTube, DLive will automatically save a stream/VOD that you can download. You may not even need to use this feature. I mainly use this feature with my Owncast server since Owncast does not automatically save the stream/VOD.
• Twitch Streaming:
  • Visit Twitch list of ingest servers to find the rtmp url needed to stream to Twitch.
• File Stream:
  • File streaming can stream a mp4 or playlist.txt file. The stream will loop the file or playlist. File streaming does not re-encoded the file (I tried but the Pi could not handle it. CPU=100%). Use files that are properly converted and able to stream. If streaming a playlist.txt of files, be sure that all of the files are a consistent format, bitrate, resolution... Do not try to stream a 4k or Bluray quality file. Convert the file down to 1280x720 with a program like HandBrake.
  • PLAYLIST: Place files inside a folder called media and run the create_playlist.sh script. This will generate a playlist.txt file inside the /home/<user>/raspi-streamer/ directory. In the web UI you can set the File Stream Path to: /home/<user>/raspi-streamer/playlist.txt

Troubleshooting

Test recording before doing a stream

You can do a test recording before doing a stream to check if the capture device is working and the quality. Recordings are saved in the recordings directory. You can access the recording from the smb share or directly from the sd card.

Find out what resolutions your capture device is capable of

v4l2-ctl --list-formats-ext

ffmpeg -list_formats all -f v4l2 -i /dev/video0

Choose a Format option that your capture card supports (mjpeg, yuyv422, nv12).

Update device firmware

In my case with the EVGA XR1 Lite usb capture device, I had to update its firmware in order for v4l2-ctl --list-formats-ext to show resolutions above 1280x720 30fps. After the firmware update it now shows 1080p and 720p at 60fps. It also allowed me to disable HDCP. Check if your device has a firmware update.

USB 3.0 Devices

Make sure that your capture device is connected to the (blue) USB 3.0 port and that you are using a USB 3.0 cable.

Service status

Check the status of stream_control for errors.

sudo service stream_control status

Remove and add capture device from the command line

This is handy if the device seems to be in a hung state or it is producing strange results. Capture devices are not perfect or consistent.

sudo modprobe -r uvcvideo && sudo modprobe uvcvideo

Overclocking

You can try to overclock the Raspberry Pi 4 to squeeze a bit more processing power out of it. This may help improve streaming and recording.

sudo nano /boot/firmware/config.txt

Raspberry Pi 4

Add this to the end of config.txt.

over_voltage=6
arm_freq=2000

Raspberry Pi 5

Add this the end of config.txt.

arm_freq=2600
gpu_freq=1000
over_voltage_delta=40000

Static IP Address

nmcli connection show

sudo nmcli connection modify "Wired connection 1" ipv4.addresses 192.168.0.100/24 ipv4.gateway 192.168.0.1 ipv4.dns "192.168.0.1 8.8.8.8" ipv4.method manual

sudo nmcli connection down "Wired connection 1" && sudo nmcli connection up "Wired connection 1"

nmcli connection show "Wired connection 1"

Re-install to re-configure

Run the install.sh script again to pull down the latest updates, reconfigure smb share, set a new username and password, set a new capture device.

Screenshots

Here is my setup:

• Raspberry Pi 4 8gb
• EVGA XR1 USB Capture card
• HDMI Splitter 1 in 2 Out

This is all stored under my entertainment center and powered on when I want to stream from my game consoles. I use the Web UI from my phone to control Raspi-Streamer.

Here is a more compact setup using a cheap ($14) USB capture device and 2 right angled USB 3 connectors. All purchased from Amazon. The capture device is held in place with heavy duty double sided tape.

Web UI

Future Plans

This project is ongoing, with exciting future enhancements in the pipeline:

• Web UI:
  • Ability to create multiple config files for various platforms and/or stream settings and choose a config to use for streaming or recording.
  • Schedule a stream (regularly recurring streams)