Basic implementation

First public commit.

This is a rollup of about 2.5 weeks worth of tinkering, and contains
the player, parser, encoder, and two sample projects.

This was originally composed of many, many more commits, but it wasn't
until this point that I cleaned up and organized everything, added
license and copyright information, etc.

The emulator patches, hardware designs, and server details are still
works-in-progress.

There are still a couple of bugs in the player, and missing features
in the streaming interface.

.gitignore

@@ -0,0 +1,2 @@
+# Swap files for ViM.
+*.sw*

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joey Parrish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,83 @@
+# ![Kinetoscope](logo.svg)
+
+A Sega Genesis / Mega Drive Video Player
+
+
+## Overview
+
+Kinetoscope can either play video embedded in a standard ROM, or it can stream
+video over WiFi using special hardware in a custom cartridge.  It uses a custom
+video format detailed in `player/inc/segavideo_format.h` and encoded by
+`encoder/encode_sega_video.py`.
+
+Kinetoscope takes its name from the [first moving picture
+device](https://www.britannica.com/technology/Kinetoscope), invented in 1891 by
+Thomas Edison and William Dickson.  While the 1891 original Kinetoscope was
+able to display 46 frames per second, this project can only push 10.
+
+The default format is displayed at ~320x240p analog SD resolution at 10fps,
+with 8-bit PCM audio at 13kHz.  The encoded pixels are not square.  The encoded
+frames use a 256x224 resolution due to hardware limitations, and are displayed
+at a different ratio by the Sega's Video Display Processor (VDP).
+
+If video is embedded in the ROM, you can only fit about 13.6 seconds in a 4MB
+cartridge/ROM.
+
+Schematics and board layouts for special streaming hardware can be found in the
+`hardware/` folder.  I may also be able to build and mail you a cartridge for a
+fee.  See my contact info at https://joeyparrish.github.io/
+
+
+## Prerequisites
+
+The encoder requires:
+ - Python 3
+ - ImageMagick
+ - a copy of FFmpeg with PNG output support
+
+The [SGDK][] compiler requires:
+ - Docker
+
+On Ubuntu, you can install these with:
+
+```sh
+sudo apt install python3 imagemagick ffmpeg docker.io
+```
+
+If the video is embedded in the ROM with the player, nothing else is required.
+A standard flash cart or ROM will work fine.
+
+To stream video over WiFi, special hardware is required.
+
+
+## Project Folders
+
+ - `player/`: The player library, written for [SGDK][], which you can import
+   into your own projects if you wish.
+ - `encoder/`: The video encoder, which generates videos in an appropriate
+   format for embedding or streaming.
+ - `embed-video-in-rom/`: A sample project using [SGDK][] and the player
+   library that allows you to easily embed a video stream into a ROM and play
+   it back when the program starts.  This works fine in a standard ROM+emulator
+   or in a flash cart.
+ - `hardware/`: The schematics and board layouts for a custom cartridge with
+   special streaming hardware.
+ - `stream-with-special-hardware/`: A project using [SGDK][] that builds a
+   small ROM that can communicate with the streaming hardware from `hardware/`,
+   stream video over WiFi, and play back a virtually unlimited stream.  This
+   will not work in a standard emulator without special emulation for this
+   hardware.  See also `emulator-patches/`.
+ - `emulator-patches/`: Patches for OSS emulators to emulate the streaming
+   hardware.
+ - `server/`: Details on running a server for Sega video streams.
+
+
+## Links
+
+ - [SGDK][]: A free and open development kit for the Sega Genesis / Mega Drive
+ - The logo font is [Kode Mono](https://kodemono.com/)
+ - Presentation slides coming soon
+ - [Slide viewer for Sega Genesis](https://github.com/joeyparrish/sega-slides/)
+
+
+[SGDK]: https://github.com/Stephane-D/SGDK

build.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Kinetoscope: A Sega Genesis Video Player
+#
+# Copyright (c) 2024 Joey Parrish
+#
+# See MIT License in LICENSE.txt
+
+# Universal build script, symlinked into each project folder.
+# If you run this from the project root, you will get an error message with
+# instructions.
+
+set -e
+
+# The folder this script is in.
+this_dir="$(dirname "$0")"
+# The repo root.
+repo_root="$(git rev-parse --show-toplevel)"
+# this_dir, relative to repo_root.
+relative_dir="$(realpath -s --relative-to="$repo_root" "$this_dir")"
+
+if [[ ! -L "$0" ]]; then
+  echo "This universal build script is meant to run as a symlink from a project folder."
+  echo "Please run the build for a specific project, such as:"
+  echo ""
+  echo "  ./stream-with-special-hardware/build.sh"
+  echo ""
+  echo "See also the README.md files at the root and in each project folder."
+  exit 1
+fi
+
+if [[ ! -d "$this_dir/src" ]]; then
+  echo "Sources not found in this folder!"
+  exit 1
+fi
+
+# Run docker.
+# Delete the container afterward (--rm).
+# Mount the repo root into /src (-v ...) so that symlinks work within the repo.
+# Run as the local user (-u) so that the container doesn't output as root.
+# Set the working directory to within /src (-w) to build a specific sample.
+# Pull the SGDK compiler docker image from GitHub.
+docker run \
+  --rm \
+  -v "$repo_root":/src \
+  -u $(id -u):$(id -g) \
+  -w "/src/$relative_dir" \
+  ghcr.io/joeyparrish/sgdk
+
+# Show the size of the output.
+ls -sh out/rom.bin

embed-video-in-rom/.gitignore

@@ -0,0 +1,12 @@
+# Generated by SGDK, but we don't customize it.
+# Also it's written in assembly, so, like, yuck.
+src/boot/sega.s
+
+# Video resource files.  Generated by you!
+res/video_data.*
+
+# Generated header for the tilemap resources.
+res/trivial_tilemap.h
+
+# All build outputs go here.
+out/

embed-video-in-rom/README.md

@@ -0,0 +1,43 @@
+# Embedded video in the ROM
+
+
+## Prerequisites
+
+The encoder requires:
+ - Python 3
+ - ImageMagick
+ - a copy of FFmpeg with PNG output support
+
+The SGDK compiler requires:
+ - Docker
+
+On Ubuntu, you can install these with:
+
+```sh
+sudo apt install python3 imagemagick ffmpeg docker.io
+```
+
+
+## Instructions
+
+To make a 10-second clip, from time 0 to time 10, run:
+
+```sh
+../encoder/encode_sega_video.py \
+  -i /path/to/never-gonna-give-you-up.mp4 \
+  -s 0 -e 10 \
+  -o res/video_data.segavideo \
+  --generate-resource-file
+```
+
+Adjust the input file (`-i`), start time (`-s`), and end time (`-e`) however
+you like, but you can only fit about 13.6 seconds on a 4MB ROM with enough room
+left for the player.
+
+After generating the video, build the ROM with the build script:
+
+```sh
+./build.sh
+```
+
+The output will be in `out/rom.bin`.

embed-video-in-rom/build.sh

@@ -0,0 +1 @@
+../build.sh

embed-video-in-rom/inc/segavideo_format.h

@@ -0,0 +1 @@
+../../player/inc/segavideo_format.h

embed-video-in-rom/inc/segavideo_parser.h

@@ -0,0 +1 @@
+../../player/inc/segavideo_parser.h

embed-video-in-rom/inc/segavideo_player.h

@@ -0,0 +1 @@
+../../player/inc/segavideo_player.h

embed-video-in-rom/res/trivial_tilemap.res

@@ -0,0 +1 @@
+../../player/res/trivial_tilemap.res

embed-video-in-rom/res/trivial_tilemap_0.bin

@@ -0,0 +1 @@
+../../player/res/trivial_tilemap_0.bin

embed-video-in-rom/res/trivial_tilemap_1.bin

@@ -0,0 +1 @@
+../../player/res/trivial_tilemap_1.bin

embed-video-in-rom/src/boot/rom_head.c

@@ -0,0 +1,47 @@
+// Kinetoscope: A Sega Genesis Video Player
+//
+// Copyright (c) 2024 Joey Parrish
+//
+// See MIT License in LICENSE.txt
+
+// ROM header for the project.
+
+#include <genesis.h>
+
+__attribute__((externally_visible))
+const ROMHeader rom_header = {
+  // Standard header, which emulators will use to emulate a standard Sega with
+  // a plain ROM chip plugged in.
+  "SEGA MEGA DRIVE ",
+  // Copyright line.
+  "(C) Joey Parrish",
+  // Game title.
+  "Kinetoscope Embedded                            ",
+  // Localized game title.
+  "Kinetoscope Embedded                            ",
+  // Serial number. GM prefix means "game". The rest is meaningless.
+  "GM 04390116-23",
+  // ROM checksum.
+  0x0000,
+  // Device support.  "J" means 3-button controller.
+  "J               ",
+  // Cartridge ROM/RAM address range.
+  0x00000000,
+  0x003FFFFF,
+  // RAM address range.
+  0x00FF0000,
+  0x00FFFFFF,
+  // No SRAM.
+  "  ",
+  // A0 = 16-bit SRAM, 20 = reserved.
+  0xA020,
+  // SRAM address range.
+  0x00000000,
+  0x00000000,
+  // No modem support.
+  "            ",
+  // Reserved, just spaces.
+  "                                        ",
+  // Region support: Japan, US, Europe.
+  "JUE             "
+};

embed-video-in-rom/src/main.c

@@ -0,0 +1,36 @@
+// Kinetoscope: A Sega Genesis Video Player
+//
+// Copyright (c) 2024 Joey Parrish
+//
+// See MIT License in LICENSE.txt
+
+// Sample project that plays embedded video from the ROM.
+
+#include <genesis.h>
+
+#include "segavideo_player.h"
+#include "video_data.h"
+
+static void onJoystickEvent(u16 joystick, u16 changed, u16 state) {
+  if (segavideo_isPlaying()) {
+    if (state & BUTTON_START) {
+      segavideo_togglePause();
+    }
+  }
+}
+
+int main(bool hardReset) {
+  JOY_setEventHandler(onJoystickEvent);
+
+  segavideo_init();
+
+  segavideo_play(video_data, /* loop= */ true);
+
+  while (true) {
+    // This order reduces screen tearing:
+    segavideo_processFrames();
+    SYS_doVBlankProcess();
+  }
+
+  return 0;
+}

embed-video-in-rom/src/segavideo_parser.c

@@ -0,0 +1 @@
+../../player/src/segavideo_parser.c

embed-video-in-rom/src/segavideo_player.c

@@ -0,0 +1 @@
+../../player/src/segavideo_player.c