Esp32TV/tools/README.md

Channel3 ESP32 Streaming Tools

stream_video.py

Stream video files to the ESP32 Channel3 RF Broadcast over WiFi.

Requirements

• Python 3.6+
• NumPy (pip install numpy)
• FFmpeg installed and in PATH

Basic Usage

ffmpeg -i video.mp4 -vf "scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py <ESP32_IP>

Examples

Stream a video file (with correct aspect ratio):

ffmpeg -i myvideo.mp4 -vf "scale=293:220:force_original_aspect_ratio=decrease,pad=293:220:(ow-iw)/2:(oh-ih)/2,scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100

Note: The TV has wide pixels (PAR ~2.53:1). We first scale to 293x220 (116×2.53=293) to preserve aspect ratio, then squash to 116x220 for the physical pixels.

Stream at a specific frame rate (e.g., 15 fps):

ffmpeg -i myvideo.mp4 -vf "scale=116:220,fps=15" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100 -f 15

Stream webcam (Windows):

ffmpeg -f dshow -i video="Your Webcam Name" -vf "scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100

Stream webcam (Linux):

ffmpeg -f v4l2 -i /dev/video0 -vf "scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100

Stream desktop (Windows):

ffmpeg -f gdigrab -i desktop -vf "scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100

Stream desktop (Linux):

ffmpeg -f x11grab -i :0.0 -vf "scale=116:220" -f rawvideo -pix_fmt rgb24 - | python stream_video.py 192.168.1.100

Options

Option	Description
-p, --port PORT	TCP port (default: 5000)
-f, --fps FPS	Target frame rate (default: 30)
--no-dither	Disable Floyd-Steinberg dithering (faster but lower quality)

How it Works

1. FFmpeg decodes the video and scales it to 116x220 pixels, outputting raw RGB24 frames
2. The Python script reads each frame, applies Floyd-Steinberg dithering to reduce to 16 colors
3. Frames are packed as 4 bits per pixel (two pixels per byte)
4. Packed frames (12,760 bytes each) are sent to the ESP32 over TCP
5. The ESP32 displays each frame on the analog TV broadcast

Troubleshooting

"Connection refused"

• Make sure the ESP32 is powered on and connected to WiFi
• Check that you're using the correct IP address
• The stream server runs on port 5000 by default

Low frame rate

• Try --no-dither for faster processing
• Reduce target FPS with -f 15
• Make sure your WiFi connection is stable

Video looks stretched

• Use the aspect ratio preservation ffmpeg filter shown above
• The display is 116x220 pixels with approximately 2.5:1 pixel aspect ratio