# 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

```bash
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):**
```bash
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):**
```bash
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):**
```bash
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):**
```bash
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):**
```bash
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):**
```bash
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