Stream video files to an Ultimate 64 via its Web API.
Author: Garland Glessner gglessner@gmail.com
License: GNU General Public License v3.0
- Stream any video file to the Ultimate 64 in real-time
- Multiple display modes:
- Mono - Hi-res black & white (320x200, fastest)
- Hi-res Color - 2 colors per 8x8 cell (320x200)
- Multicolor - 4 colors per 4x8 cell (160x200)
- Floyd-Steinberg dithering for optimal visual quality
- Automatic conversion from any video format supported by OpenCV
- Automatic backup and restore of C64 display state
- Python 3.6+
- Ultimate 64 with network connectivity and Web API enabled
pip install -r requirements-videostream.txt
# Optional: Install numba for ~10x faster conversion
pip install numbapython C64U-VideoStream.py <IP_ADDRESS> <video_file> [options]
| Argument | Description |
|---|---|
IP_ADDRESS |
IP address of the Ultimate 64 |
video_file |
Path to video file (MP4, AVI, MKV, etc.) |
| Option | Mode | Resolution | Colors | Speed |
|---|---|---|---|---|
--mono |
Hi-res mono | 320x200 | 2 (B&W) | ~3.5 fps |
--hires |
Hi-res color | 320x200 | 2 per cell | ~0.7 fps |
--multicolor |
Multicolor | 160x200 | 4 per cell | ~0.9 fps |
| Option | Description |
|---|---|
--fps=N |
Target frame rate (default: 2) |
--skip=N |
Skip N seconds into video |
--frames=N |
Stop after N frames (useful for API limit) |
--loop |
Loop video continuously |
--help |
Show help message |
# Stream in mono mode (fastest)
python C64U-VideoStream.py 192.168.1.100 video.mp4 --mono --fps=3
# Stream in hi-res color (default mode)
python C64U-VideoStream.py 192.168.1.100 video.mp4 --hires
# Stream in multicolor mode
python C64U-VideoStream.py 192.168.1.100 video.mp4 --multicolor
# Skip to 1 minute into video
python C64U-VideoStream.py 192.168.1.100 video.mp4 --skip=60
# Loop video continuously
python C64U-VideoStream.py 192.168.1.100 video.mp4 --mono --loop- Freeze - Pause the C64 and backup current display state
- Setup - Configure VIC-II registers for the selected display mode
- Convert Frame - For each video frame:
- Resize to C64 resolution (320x200 or 160x200)
- Find optimal C64 colors for each cell
- Apply Floyd-Steinberg dithering
- Pack into C64 bitmap format
- Write via DMA - Send bitmap and color data directly to C64 memory
- Repeat - Continue until video ends or user presses Ctrl+C
- Restore - Put back original display state and resume C64
- Resolution: 320x200 pixels
- Colors: Black and white only
- Speed: ~3.5 fps (fastest mode)
- Best for: High detail, line art, text
The entire screen uses white foreground on black background. Each pixel is either on or off.
- Resolution: 320x200 pixels
- Colors: 2 colors per 8x8 cell (from 16 color palette)
- Speed: ~0.7 fps
- Best for: Colorful content with good detail
Each 8x8 pixel cell can have any 2 of the 16 C64 colors. The algorithm automatically selects the best 2 colors for each cell.
- Resolution: 160x200 pixels (double-wide pixels)
- Colors: 4 colors per 4x8 cell (from 16 color palette)
- Speed: ~0.9 fps
- Best for: Photos, gradients, colorful scenes
Each 4x8 pixel cell can have 4 colors: background (black) plus 3 selected colors. Lower resolution but more colors per cell.
The Ultimate 64's REST API has a limit of approximately 323 write operations before becoming unresponsive. This translates to:
| Mode | Writes/Frame | Max Frames | Playback Time (at max fps) |
|---|---|---|---|
| Mono | 1 | ~323 | ~90 seconds |
| Hi-res Color | 2 | ~161 | ~230 seconds |
| Multicolor | 3 | ~107 | ~120 seconds |
Workaround: Power cycle the Ultimate 64 to reset the counter. This is a firmware limitation, not a bug in this tool.
Frame conversion is CPU-intensive, especially for color modes:
| Mode | Conversion Time | Achievable FPS |
|---|---|---|
| Mono | ~300ms | ~3.5 fps |
| Hi-res Color | ~1300ms | ~0.7 fps |
| Multicolor | ~1100ms | ~0.9 fps |
The tool uses the standard C64 16-color palette:
| Index | Color | Index | Color |
|---|---|---|---|
| 0 | Black | 8 | Orange |
| 1 | White | 9 | Brown |
| 2 | Red | 10 | Light Red |
| 3 | Cyan | 11 | Dark Gray |
| 4 | Purple | 12 | Medium Gray |
| 5 | Green | 13 | Light Green |
| 6 | Blue | 14 | Light Blue |
| 7 | Yellow | 15 | Light Gray |
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Garland Glessner - gglessner@gmail.com
- C64U-Screenshot - Capture screenshots from the Ultimate 64