rv565 1.1.0__tar.gz

rv565-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayushman Bhattacharya and Elixpo
+
+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.

rv565-1.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: rv565
+Version: 1.1.0
+Summary: Read, write and check RV565 frame-independent RGB565 video files; Pillow plugin included.
+Author-email: Ayushman Bhattacharya <ayushman.elixpo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/elixpo/rv565
+Project-URL: Documentation, https://github.com/elixpo/rv565/tree/main/python#readme
+Project-URL: Paper, https://arxiv.org/abs/2610.35935
+Project-URL: Issues, https://github.com/elixpo/rv565/issues
+Keywords: rgb565,video,esp32,st7789,microcontroller,pillow,arduino
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pillow
+Requires-Dist: Pillow>=10.1; extra == "pillow"
+Dynamic: license-file
+
+# rv565 for Python
+
+Read, write and check [RV565](https://github.com/elixpo/rv565) video files:
+independently zlib-compressed RGB565 frames, the format the RV565 library
+plays at 24 FPS on ESP32-S3 SPI displays
+([arXiv:2610.35935](https://arxiv.org/abs/2610.35935)).
+
+```bash
+pip install rv565            # core and the `rv565` command, no dependencies
+pip install "rv565[pillow]"  # plus the Pillow plugin
+```
+
+## Command line
+
+```bash
+rv565 encode input.mp4 clip.rv565 --size 180x135 --fps 24   # needs FFmpeg
+rv565 info clip.rv565        # sizes and predicted missed frames on ESP32-S3
+rv565 verify clip.rv565
+rv565 c-array clip.rv565 clip.h   # for Arduino sketches
+```
+
+## Library
+
+```python
+import rv565
+
+clip = rv565.open("clip.rv565")
+print(clip.width, clip.height, clip.fps, len(clip))
+frame = clip.frame(0)                     # RGB565 big-endian bytes, O(1) seek
+report = clip.check_schedule(overlap=True)
+print(report.late_frames)                 # 0: plays without misses (ESP32-S3 model)
+
+rv565.write("out.rv565", 180, 135, 24, frames)   # frames: RGB565BE bytes each
+```
+
+## Pillow
+
+```python
+import rv565.pillow                       # registers the format
+from PIL import Image, ImageSequence
+
+with Image.open("clip.rv565") as im:      # mode "RGB", im.n_frames, im.info["fps"]
+    frames = [f.copy() for f in ImageSequence.Iterator(im)]
+
+frames[0].save("out.rv565", save_all=True, append_images=frames[1:], fps=24)
+```
+
+Any image sequence Pillow can open (GIF, APNG, WebP) can be saved as RV565 the
+same way; colours are reduced to RGB565.
+
+## License
+
+MIT.

rv565-1.1.0/README.md

@@ -0,0 +1,53 @@
+# rv565 for Python
+
+Read, write and check [RV565](https://github.com/elixpo/rv565) video files:
+independently zlib-compressed RGB565 frames, the format the RV565 library
+plays at 24 FPS on ESP32-S3 SPI displays
+([arXiv:2610.35935](https://arxiv.org/abs/2610.35935)).
+
+```bash
+pip install rv565            # core and the `rv565` command, no dependencies
+pip install "rv565[pillow]"  # plus the Pillow plugin
+```
+
+## Command line
+
+```bash
+rv565 encode input.mp4 clip.rv565 --size 180x135 --fps 24   # needs FFmpeg
+rv565 info clip.rv565        # sizes and predicted missed frames on ESP32-S3
+rv565 verify clip.rv565
+rv565 c-array clip.rv565 clip.h   # for Arduino sketches
+```
+
+## Library
+
+```python
+import rv565
+
+clip = rv565.open("clip.rv565")
+print(clip.width, clip.height, clip.fps, len(clip))
+frame = clip.frame(0)                     # RGB565 big-endian bytes, O(1) seek
+report = clip.check_schedule(overlap=True)
+print(report.late_frames)                 # 0: plays without misses (ESP32-S3 model)
+
+rv565.write("out.rv565", 180, 135, 24, frames)   # frames: RGB565BE bytes each
+```
+
+## Pillow
+
+```python
+import rv565.pillow                       # registers the format
+from PIL import Image, ImageSequence
+
+with Image.open("clip.rv565") as im:      # mode "RGB", im.n_frames, im.info["fps"]
+    frames = [f.copy() for f in ImageSequence.Iterator(im)]
+
+frames[0].save("out.rv565", save_all=True, append_images=frames[1:], fps=24)
+```
+
+Any image sequence Pillow can open (GIF, APNG, WebP) can be saved as RV565 the
+same way; colours are reduced to RGB565.
+
+## License
+
+MIT.

rv565-1.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rv565"
+dynamic = ["version"]
+description = "Read, write and check RV565 frame-independent RGB565 video files; Pillow plugin included."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ayushman Bhattacharya", email = "ayushman.elixpo@gmail.com" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["rgb565", "video", "esp32", "st7789", "microcontroller", "pillow", "arduino"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Conversion",
+    "Topic :: Software Development :: Embedded Systems",
+]
+
+[project.optional-dependencies]
+pillow = ["Pillow>=10.1"]
+
+[project.scripts]
+rv565 = "rv565.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/elixpo/rv565"
+Documentation = "https://github.com/elixpo/rv565/tree/main/python#readme"
+Paper = "https://arxiv.org/abs/2610.35935"
+Issues = "https://github.com/elixpo/rv565/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "rv565.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

rv565-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rv565-1.1.0/src/rv565/__init__.py

@@ -0,0 +1,286 @@
+"""RV565: frame-independent RGB565 video files.
+
+Read, write and check RV565 files (container version 6), the format played by
+the RV565 microcontroller library (arXiv:2610.35935):
+
+    import rv565
+
+    clip = rv565.open("clip.rv565")
+    print(clip.width, clip.height, clip.fps, len(clip))
+    frame = clip.frame(0)          # bytes, RGB565 big-endian
+
+    rv565.write("out.rv565", 180, 135, 24, frames)
+
+With Pillow installed (``pip install rv565[pillow]``), ``import rv565.pillow``
+lets ``PIL.Image`` open and save RV565 files as animations.
+"""
+
+import struct
+import zlib
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "RV565Error", "Header", "Clip", "CostModel", "ScheduleReport",
+    "COST_ESP32S3_180x135", "open", "write", "encode_frames",
+    "rgb888_to_rgb565be", "rgb565be_to_rgb888",
+]
+
+__version__ = "1.1.0"
+
+MAGIC = b"RV5"
+VERSION = 6
+MAX_FPS = 30
+MAX_FRAMES = 0xFFFF
+HEADER = struct.Struct("<3sBHHBBH")  # magic, version, width, height, fps, flags, frames
+LENGTH = struct.Struct("<I")
+
+
+class RV565Error(ValueError):
+    """The data is not a valid RV565 file, or an argument is out of range."""
+
+
+@dataclass(frozen=True)
+class Header:
+    width: int
+    height: int
+    fps: int
+    flags: int
+    frames: int
+
+    @property
+    def frame_bytes(self):
+        """Decoded size of one frame: 2 * width * height."""
+        return 2 * self.width * self.height
+
+    @property
+    def duration(self):
+        """Length in seconds."""
+        return self.frames / self.fps
+
+
+def parse_header(data):
+    """Parse and range-check the 12-byte header."""
+    if len(data) < HEADER.size:
+        raise RV565Error("file too short")
+    magic, version, width, height, fps, flags, frames = HEADER.unpack_from(data)
+    if magic != MAGIC:
+        raise RV565Error("not an RV565 file")
+    if version != VERSION:
+        raise RV565Error("unsupported RV565 version %d" % version)
+    if not (width and height and 1 <= fps <= MAX_FPS and frames):
+        raise RV565Error("invalid header")
+    return Header(width, height, fps, flags, frames)
+
+
+class Clip:
+    """An RV565 file held in memory, with an O(1) frame index.
+
+    The whole container is validated on open: every length must be nonzero and
+    inside the data, and nothing may follow the last frame.
+    """
+
+    def __init__(self, data):
+        self.data = bytes(data)
+        self.header = parse_header(self.data)
+        offsets, offset = [], HEADER.size
+        for i in range(self.header.frames):
+            if len(self.data) - offset < LENGTH.size:
+                raise RV565Error("truncated frame table at frame %d" % i)
+            (length,) = LENGTH.unpack_from(self.data, offset)
+            offset += LENGTH.size
+            if length == 0 or len(self.data) - offset < length:
+                raise RV565Error("invalid length for frame %d" % i)
+            offsets.append((offset, length))
+            offset += length
+        if offset != len(self.data):
+            raise RV565Error("trailing bytes after the last frame")
+        self._index = offsets
+
+    width = property(lambda self: self.header.width)
+    height = property(lambda self: self.header.height)
+    fps = property(lambda self: self.header.fps)
+
+    def __len__(self):
+        return self.header.frames
+
+    def payload_sizes(self):
+        """Compressed length of every frame, in order."""
+        return [length for _, length in self._index]
+
+    def payload(self, i):
+        """The zlib payload of frame i."""
+        offset, length = self._index[self._check(i)]
+        return self.data[offset:offset + length]
+
+    def frame(self, i):
+        """Frame i as RGB565 big-endian bytes (2 * width * height of them)."""
+        try:
+            frame = zlib.decompress(self.payload(i))
+        except zlib.error as exc:
+            raise RV565Error("frame %d does not inflate: %s" % (i, exc)) from None
+        if len(frame) != self.header.frame_bytes:
+            raise RV565Error("frame %d inflates to %d bytes, expected %d"
+                             % (i, len(frame), self.header.frame_bytes))
+        return frame
+
+    def __iter__(self):
+        return (self.frame(i) for i in range(len(self)))
+
+    def verify(self):
+        """Inflate every frame; raises RV565Error on the first bad one."""
+        for i in range(len(self)):
+            self.frame(i)
+        return len(self)
+
+    def check_schedule(self, model=None, transfer_us=31312.0, overlap=True):
+        """Predict missed deadlines from the payload sizes alone.
+
+        ``transfer_us`` is the display transfer per frame (31312 us is 320x240
+        at 40 MHz SPI). With ``overlap`` the next frame inflates on another
+        core during the transfer, so frame work is max(transfer, inflate);
+        otherwise it is transfer + inflate.
+        """
+        model = model or COST_ESP32S3_180x135
+        period = 1e6 / self.fps
+        sizes = self.payload_sizes()
+        work = [max(transfer_us, model.predict(s)) if overlap else transfer_us + model.predict(s)
+                for s in sizes]
+        return ScheduleReport(late_frames=sum(w > period for w in work),
+                              max_payload=max(sizes), worst_frame_us=max(work),
+                              period_us=period)
+
+    def _check(self, i):
+        if not 0 <= i < len(self):
+            raise IndexError("frame %d out of range (0-%d)" % (i, len(self) - 1))
+        return i
+
+
+@dataclass(frozen=True)
+class CostModel:
+    """T_inflate(L) = intercept_us + slope_us_per_byte * L."""
+    intercept_us: float
+    slope_us_per_byte: float
+
+    def predict(self, payload_len):
+        return self.intercept_us + self.slope_us_per_byte * payload_len
+
+
+@dataclass(frozen=True)
+class ScheduleReport:
+    late_frames: int
+    max_payload: int
+    worst_frame_us: float
+    period_us: float
+
+
+# Pooled fit from the RV565 paper: ESP32-S3 at 240 MHz, ROM tinfl, 180x135
+# frames. Refit for other chips, clocks or frame sizes.
+COST_ESP32S3_180x135 = CostModel(4858.0, 0.1515)
+
+
+def open(source):  # noqa: A001 - mirrors the module-level open() idiom
+    """Open an RV565 file from a path, bytes, or a binary file object."""
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        return Clip(source)
+    if hasattr(source, "read"):
+        return Clip(source.read())
+    return Clip(Path(source).read_bytes())
+
+
+def encode_frames(frames, width, height, level=1):
+    """Yield the zlib payload of each RGB565BE frame (level 1 is what the
+    paper measured; higher levels give smaller files, slower to encode)."""
+    frame_bytes = 2 * width * height
+    for i, frame in enumerate(frames):
+        if len(frame) != frame_bytes:
+            raise RV565Error("frame %d has %d bytes, expected %d" % (i, len(frame), frame_bytes))
+        yield zlib.compress(bytes(frame), level)
+
+
+def write(target, width, height, fps, frames, level=1):
+    """Write RGB565BE frames (an iterable of bytes) as an RV565 file.
+
+    ``target`` is a path or a seekable binary file object. Returns the number
+    of frames written.
+    """
+    if not (0 < width <= 0xFFFF and 0 < height <= 0xFFFF):
+        raise RV565Error("size %dx%d out of range" % (width, height))
+    if not 1 <= fps <= MAX_FPS:
+        raise RV565Error("fps must be 1-%d" % MAX_FPS)
+    if hasattr(target, "write"):
+        return _write(target, width, height, fps, frames, level)
+    with Path(target).open("wb") as out:
+        return _write(out, width, height, fps, frames, level)
+
+
+def _write(out, width, height, fps, frames, level):
+    start = out.tell()
+    out.write(HEADER.pack(MAGIC, VERSION, width, height, fps, 0, 0))
+    count = 0
+    for payload in encode_frames(frames, width, height, level):
+        count += 1
+        if count > MAX_FRAMES:
+            raise RV565Error("more than %d frames" % MAX_FRAMES)
+        out.write(LENGTH.pack(len(payload)))
+        out.write(payload)
+    if count == 0:
+        raise RV565Error("no frames")
+    end = out.tell()
+    out.seek(start + 10)
+    out.write(struct.pack("<H", count))
+    out.seek(end)
+    return count
+
+
+# Pixel conversion -----------------------------------------------------------
+
+_R5 = bytes(v & 0xF8 for v in range(256))
+_G_HI = bytes(v >> 5 for v in range(256))
+_G_LO = bytes((v & 0x1C) << 3 for v in range(256))
+_B5 = bytes(v >> 3 for v in range(256))
+
+
+def _or_bytes(a, b):
+    return (int.from_bytes(a, "big") | int.from_bytes(b, "big")).to_bytes(len(a), "big")
+
+
+def rgb888_to_rgb565be(rgb):
+    """Convert packed RGB888 bytes to RGB565 big-endian bytes."""
+    rgb = bytes(rgb)
+    if len(rgb) % 3:
+        raise RV565Error("RGB data length is not a multiple of 3")
+    r, g, b = rgb[0::3], rgb[1::3], rgb[2::3]
+    hi = _or_bytes(r.translate(_R5), g.translate(_G_HI))
+    lo = _or_bytes(g.translate(_G_LO), b.translate(_B5))
+    out = bytearray(2 * len(r))
+    out[0::2] = hi
+    out[1::2] = lo
+    return bytes(out)
+
+
+def _expand(bits):
+    top = (1 << bits) - 1
+    return [(v * 255 + top // 2) // top for v in range(1 << bits)]
+
+
+_E5, _E6 = _expand(5), _expand(6)
+_HI_R = bytes(_E5[v >> 3] for v in range(256))
+_LO_B = bytes(_E5[v & 0x1F] for v in range(256))
+_HI_G = bytes((v & 0x07) << 3 for v in range(256))
+_LO_G = bytes(v >> 5 for v in range(256))
+_G6 = bytes(_E6[v & 0x3F] for v in range(256))
+
+
+def rgb565be_to_rgb888(data):
+    """Convert RGB565 big-endian bytes to packed RGB888 bytes."""
+    data = bytes(data)
+    if len(data) % 2:
+        raise RV565Error("RGB565 data length is odd")
+    hi, lo = data[0::2], data[1::2]
+    r = hi.translate(_HI_R)
+    b = lo.translate(_LO_B)
+    g = _or_bytes(hi.translate(_HI_G), lo.translate(_LO_G)).translate(_G6)
+    out = bytearray(3 * len(hi))
+    out[0::3], out[1::3], out[2::3] = r, g, b
+    return bytes(out)

rv565-1.1.0/src/rv565/cli.py

@@ -0,0 +1,173 @@
+"""rv565: encode, inspect, verify and export RV565 video files.
+
+  rv565 encode SOURCE OUT.rv565 [--start S] [--seconds N] [--fps F] [--size WxH] [--level L]
+  rv565 info FILE.rv565 [--transfer-us T]
+  rv565 verify FILE.rv565
+  rv565 c-array FILE.rv565 OUT.h [--name NAME]
+  rv565 testpattern OUT.rv565 [--frames N] [--fps F] [--size WxH]
+
+`encode` needs FFmpeg on PATH. Everything else uses only the standard library.
+"""
+
+import argparse
+import hashlib
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import COST_ESP32S3_180x135, HEADER, VERSION, RV565Error, open as open_clip, write
+
+
+def parse_size(text):
+    try:
+        width, height = (int(v) for v in text.lower().split("x"))
+    except ValueError:
+        raise argparse.ArgumentTypeError("size must look like 180x135")
+    if not (0 < width <= 1024 and 0 < height <= 1024):
+        raise argparse.ArgumentTypeError("size out of range")
+    return width, height
+
+
+def ffmpeg_frames(source, start, seconds, fps, width, height):
+    vf = ("fps=%d,scale=%d:%d:force_original_aspect_ratio=increase:flags=lanczos,"
+          "crop=%d:%d,format=rgb565be" % (fps, width, height, width, height))
+    cmd = ["ffmpeg", "-v", "error", "-ss", str(start), "-i", str(source),
+           "-t", str(seconds), "-an", "-vf", vf, "-pix_fmt", "rgb565be",
+           "-f", "rawvideo", "-"]
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+    frame_bytes = width * height * 2
+    try:
+        while True:
+            frame = proc.stdout.read(frame_bytes)
+            if not frame:
+                break
+            if len(frame) != frame_bytes:
+                raise SystemExit("ffmpeg returned a partial frame")
+            yield frame
+    finally:
+        proc.stdout.close()
+        if proc.wait() != 0:
+            raise SystemExit("ffmpeg failed")
+
+
+def cmd_encode(args):
+    if shutil.which("ffmpeg") is None:
+        raise SystemExit("ffmpeg is required for encode")
+    width, height = args.size
+    count = write(args.output, width, height, args.fps,
+                  ffmpeg_frames(args.source, args.start, args.seconds, args.fps, width, height),
+                  args.level)
+    print("encoded %d frames, %dx%d, %d FPS -> %s (%d bytes)" % (
+        count, width, height, args.fps, args.output, Path(args.output).stat().st_size))
+
+
+def cmd_info(args):
+    clip = open_clip(args.file)
+    h, sizes = clip.header, clip.payload_sizes()
+    raw = HEADER.size + h.frame_bytes * h.frames
+    print("file      %s" % args.file)
+    print("sha256    %s" % hashlib.sha256(clip.data).hexdigest())
+    print("format    RV565 v%d, %dx%d, %d FPS, %d frames (%.2f s)" % (
+        VERSION, h.width, h.height, h.fps, h.frames, h.duration))
+    print("size      %d bytes (raw %d, ratio %.2fx)" % (len(clip.data), raw, raw / len(clip.data)))
+    print("payloads  min %d, mean %.0f, max %d bytes" % (
+        min(sizes), sum(sizes) / len(sizes), max(sizes)))
+    if (h.width, h.height) != (180, 135):
+        print("schedule  cost model fitted for 180x135; refit before trusting it")
+    for label, overlap in (("serial", False), ("overlap", True)):
+        r = clip.check_schedule(COST_ESP32S3_180x135, args.transfer_us, overlap)
+        print("schedule  %-7s worst %.2f ms, %d/%d frames late at %d FPS (ESP32-S3 model)" % (
+            label, r.worst_frame_us / 1e3, r.late_frames, h.frames, h.fps))
+
+
+def cmd_verify(args):
+    count = open_clip(args.file).verify()
+    print("ok: %d frames verified" % count)
+
+
+def cmd_c_array(args):
+    clip = open_clip(args.file)
+    h, data, name = clip.header, clip.data, args.name
+    lines = ["/* Generated by tools/rv565.py from %s: %dx%d, %d FPS, %d frames. */" % (
+        Path(args.file).name, h.width, h.height, h.fps, h.frames),
+        "#pragma once", "#include <stddef.h>", "#include <stdint.h>", "",
+        "static const uint8_t %s[] __attribute__((aligned(4))) = {" % name]
+    for i in range(0, len(data), 16):
+        lines.append("    " + ", ".join("0x%02x" % b for b in data[i:i + 16]) + ",")
+    lines += ["};", "static const size_t %s_size = sizeof(%s);" % (name, name), ""]
+    Path(args.output).write_text("\n".join(lines))
+    print("wrote %s (%d bytes of data)" % (args.output, len(data)))
+
+
+def testpattern_frames(count, width, height):
+    """Scrolling colour bars: deterministic and highly compressible."""
+    bars = [(0xFF, 0xFF, 0xFF), (0xFF, 0xFF, 0x00), (0x00, 0xFF, 0xFF), (0x00, 0xFF, 0x00),
+            (0xFF, 0x00, 0xFF), (0xFF, 0x00, 0x00), (0x00, 0x00, 0xFF), (0x00, 0x00, 0x00)]
+
+    def rgb565be(r, g, b):
+        v = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
+        return bytes((v >> 8, v & 0xFF))
+
+    for f in range(count):
+        shift = f * width // count
+        row = b"".join(rgb565be(*bars[((x + shift) % width) * len(bars) // width])
+                       for x in range(width))
+        yield row * height
+
+
+def cmd_testpattern(args):
+    width, height = args.size
+    count = write(args.output, width, height, args.fps,
+                  testpattern_frames(args.frames, width, height), 9)
+    print("wrote %d-frame test pattern %dx%d -> %s (%d bytes)" % (
+        count, width, height, args.output, Path(args.output).stat().st_size))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="rv565", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("encode", help="encode a video with FFmpeg")
+    p.add_argument("source", type=Path)
+    p.add_argument("output", type=Path)
+    p.add_argument("--start", type=float, default=0.0, help="offset into the source, in seconds")
+    p.add_argument("--seconds", type=float, default=10.0)
+    p.add_argument("--fps", type=int, default=24, choices=range(1, 31), metavar="1-30")
+    p.add_argument("--size", type=parse_size, default=(180, 135))
+    p.add_argument("--level", type=int, default=1, choices=range(1, 10), metavar="1-9",
+                   help="zlib level; 1 is what the paper measured")
+    p.set_defaults(func=cmd_encode)
+
+    p = sub.add_parser("info", help="print header, sizes and a schedule prediction")
+    p.add_argument("file", type=Path)
+    p.add_argument("--transfer-us", type=float, default=31312.0,
+                   help="display transfer per frame (31312 us: 320x240 at 40 MHz SPI)")
+    p.set_defaults(func=cmd_info)
+
+    p = sub.add_parser("verify", help="check that every frame inflates to its RGB565 size")
+    p.add_argument("file", type=Path)
+    p.set_defaults(func=cmd_verify)
+
+    p = sub.add_parser("c-array", help="export a file as a C header for Arduino sketches")
+    p.add_argument("file", type=Path)
+    p.add_argument("output", type=Path)
+    p.add_argument("--name", default="rv565_clip")
+    p.set_defaults(func=cmd_c_array)
+
+    p = sub.add_parser("testpattern", help="write a synthetic scrolling colour-bar clip")
+    p.add_argument("output", type=Path)
+    p.add_argument("--frames", type=int, default=24)
+    p.add_argument("--fps", type=int, default=24, choices=range(1, 31), metavar="1-30")
+    p.add_argument("--size", type=parse_size, default=(180, 135))
+    p.set_defaults(func=cmd_testpattern)
+
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except RV565Error as exc:
+        raise SystemExit("rv565: %s" % exc)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rv565-1.1.0/src/rv565/pillow.py

@@ -0,0 +1,113 @@
+"""Pillow plugin: open and save RV565 files as animations.
+
+    import rv565.pillow  # registers the format with Pillow
+    from PIL import Image, ImageSequence
+
+    with Image.open("clip.rv565") as im:
+        print(im.size, im.n_frames, im.info["fps"])
+        for frame in ImageSequence.Iterator(im):
+            ...
+
+    frames[0].save("out.rv565", save_all=True, append_images=frames[1:], fps=24)
+
+Frames decode to mode "RGB". Saving converts to RGB565, so colours keep 5-6-5
+bits. ``fps`` (1-30) defaults to 24, or is taken from ``duration`` (ms) if
+given; ``level`` sets the zlib level (default 1).
+"""
+
+from array import array
+
+from PIL import Image, ImageFile
+
+from . import MAGIC, RV565Error, open as open_clip, rgb888_to_rgb565be, write
+
+
+def _accept(prefix):
+    return prefix[:3] == MAGIC
+
+
+class RV565ImageFile(ImageFile.ImageFile):
+    format = "RV565"
+    format_description = "RV565 frame-independent RGB565 video"
+
+    def _open(self):
+        try:
+            self._clip = open_clip(self.fp.read())
+        except RV565Error as exc:
+            raise SyntaxError(str(exc)) from None
+        h = self._clip.header
+        self._mode = "RGB"
+        self._size = (h.width, h.height)
+        self.info["fps"] = h.fps
+        self.info["duration"] = 1000.0 / h.fps
+        self.info["loop"] = 0
+        self.n_frames = h.frames
+        self.is_animated = h.frames > 1
+        self._frame = -1
+        self.tile = []
+        self._load_frame(0)
+
+    def _load_frame(self, index):
+        swapped = array("H")
+        swapped.frombytes(self._clip.frame(index))
+        swapped.byteswap()  # big-endian pairs -> the little-endian layout "BGR;16" unpacks
+        self.im = Image.core.new(self.mode, self.size)
+        self.frombytes(swapped.tobytes(), "raw", "BGR;16")
+        self._frame = index
+
+    def seek(self, frame):
+        if not self._seek_check(frame):
+            return
+        self._load_frame(frame)
+
+    def tell(self):
+        return self._frame
+
+
+def _frames(im, append_images):
+    seen = [im] + list(append_images or [])
+    for image in seen:
+        for i in range(getattr(image, "n_frames", 1)):
+            if getattr(image, "n_frames", 1) > 1:
+                image.seek(i)
+            yield image.convert("RGB")
+
+
+def _fps(info, encoderinfo):
+    if "fps" in encoderinfo:
+        fps = encoderinfo["fps"]
+    elif "duration" in encoderinfo:
+        duration = encoderinfo["duration"]
+        if isinstance(duration, (list, tuple)):
+            duration = duration[0]
+        fps = round(1000.0 / duration)
+    else:
+        fps = info.get("fps", 24)
+    return max(1, min(30, int(fps)))
+
+
+def _save(im, fp, filename, save_all=False):
+    enc = im.encoderinfo
+    frames = _frames(im, enc.get("append_images")) if save_all else [im.convert("RGB")]
+    width, height = im.size
+
+    def packed():
+        for frame in frames:
+            if frame.size != (width, height):
+                raise ValueError("all frames must be %dx%d" % (width, height))
+            yield rgb888_to_rgb565be(frame.tobytes())
+
+    write(fp, width, height, _fps(im.info, enc), packed(), enc.get("level", 1))
+
+
+def _save_all(im, fp, filename):
+    _save(im, fp, filename, save_all=True)
+
+
+Image.register_open(RV565ImageFile.format, RV565ImageFile, _accept)
+Image.register_save(RV565ImageFile.format, _save)
+Image.register_save_all(RV565ImageFile.format, _save_all)
+Image.register_extension(RV565ImageFile.format, ".rv565")
+Image.register_mime(RV565ImageFile.format, "video/x-rv565")
+
+__all__ = ["RV565ImageFile"]

rv565-1.1.0/src/rv565.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: rv565
+Version: 1.1.0
+Summary: Read, write and check RV565 frame-independent RGB565 video files; Pillow plugin included.
+Author-email: Ayushman Bhattacharya <ayushman.elixpo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/elixpo/rv565
+Project-URL: Documentation, https://github.com/elixpo/rv565/tree/main/python#readme
+Project-URL: Paper, https://arxiv.org/abs/2610.35935
+Project-URL: Issues, https://github.com/elixpo/rv565/issues
+Keywords: rgb565,video,esp32,st7789,microcontroller,pillow,arduino
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pillow
+Requires-Dist: Pillow>=10.1; extra == "pillow"
+Dynamic: license-file
+
+# rv565 for Python
+
+Read, write and check [RV565](https://github.com/elixpo/rv565) video files:
+independently zlib-compressed RGB565 frames, the format the RV565 library
+plays at 24 FPS on ESP32-S3 SPI displays
+([arXiv:2610.35935](https://arxiv.org/abs/2610.35935)).
+
+```bash
+pip install rv565            # core and the `rv565` command, no dependencies
+pip install "rv565[pillow]"  # plus the Pillow plugin
+```
+
+## Command line
+
+```bash
+rv565 encode input.mp4 clip.rv565 --size 180x135 --fps 24   # needs FFmpeg
+rv565 info clip.rv565        # sizes and predicted missed frames on ESP32-S3
+rv565 verify clip.rv565
+rv565 c-array clip.rv565 clip.h   # for Arduino sketches
+```
+
+## Library
+
+```python
+import rv565
+
+clip = rv565.open("clip.rv565")
+print(clip.width, clip.height, clip.fps, len(clip))
+frame = clip.frame(0)                     # RGB565 big-endian bytes, O(1) seek
+report = clip.check_schedule(overlap=True)
+print(report.late_frames)                 # 0: plays without misses (ESP32-S3 model)
+
+rv565.write("out.rv565", 180, 135, 24, frames)   # frames: RGB565BE bytes each
+```
+
+## Pillow
+
+```python
+import rv565.pillow                       # registers the format
+from PIL import Image, ImageSequence
+
+with Image.open("clip.rv565") as im:      # mode "RGB", im.n_frames, im.info["fps"]
+    frames = [f.copy() for f in ImageSequence.Iterator(im)]
+
+frames[0].save("out.rv565", save_all=True, append_images=frames[1:], fps=24)
+```
+
+Any image sequence Pillow can open (GIF, APNG, WebP) can be saved as RV565 the
+same way; colours are reduced to RGB565.
+
+## License
+
+MIT.

rv565-1.1.0/src/rv565.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/rv565/__init__.py
+src/rv565/cli.py
+src/rv565/pillow.py
+src/rv565.egg-info/PKG-INFO
+src/rv565.egg-info/SOURCES.txt
+src/rv565.egg-info/dependency_links.txt
+src/rv565.egg-info/entry_points.txt
+src/rv565.egg-info/requires.txt
+src/rv565.egg-info/top_level.txt
+tests/test_rv565.py

rv565-1.1.0/src/rv565.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rv565-1.1.0/src/rv565.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rv565 = rv565.cli:main

rv565-1.1.0/src/rv565.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[pillow]
+Pillow>=10.1

rv565-1.1.0/src/rv565.egg-info/top_level.txt

@@ -0,0 +1 @@
+rv565

rv565-1.1.0/tests/test_rv565.py

@@ -0,0 +1,127 @@
+"""Tests for the rv565 package. Run from the repository root:
+
+    python3 -m unittest discover -s python/tests
+"""
+
+import io
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "python" / "src"))
+
+import rv565  # noqa: E402
+from rv565.cli import testpattern_frames  # noqa: E402
+
+VECTOR = ROOT / "tests" / "data" / "testpattern.rv565"
+
+try:
+    from PIL import Image, ImageSequence
+    import rv565.pillow  # noqa: F401
+except ImportError:  # Pillow is optional
+    Image = None
+
+
+class CoreTests(unittest.TestCase):
+    def test_vector(self):
+        clip = rv565.open(VECTOR)
+        self.assertEqual((clip.width, clip.height, clip.fps, len(clip)), (180, 135, 24, 24))
+        self.assertEqual(clip.verify(), 24)
+        self.assertEqual(len(clip.frame(5)), 180 * 135 * 2)
+
+    def test_round_trip(self):
+        frames = list(testpattern_frames(6, 32, 16))
+        buf = io.BytesIO()
+        self.assertEqual(rv565.write(buf, 32, 16, 12, frames), 6)
+        clip = rv565.open(buf.getvalue())
+        self.assertEqual(list(clip), frames)
+        self.assertEqual(clip.header.duration, 0.5)
+
+    def test_matches_committed_vector_frames(self):
+        # zlib output can differ between versions, so compare decoded frames.
+        clip = rv565.open(VECTOR)
+        self.assertEqual(list(clip), list(testpattern_frames(24, 180, 135)))
+
+    def test_rejects_malformed(self):
+        data = VECTOR.read_bytes()
+        cases = {
+            "not an RV565 file": b"XYZ" + data[3:],
+            "unsupported RV565 version": data[:3] + b"\x05" + data[4:],
+            "trailing bytes": data + b"\x00",
+            "invalid length": data[:-1],
+            "file too short": data[:5],
+        }
+        for message, bad in cases.items():
+            with self.subTest(message):
+                with self.assertRaisesRegex(rv565.RV565Error, message):
+                    rv565.open(bad)
+
+    def test_write_validates(self):
+        with self.assertRaises(rv565.RV565Error):
+            rv565.write(io.BytesIO(), 4, 4, 31, [bytes(32)])
+        with self.assertRaises(rv565.RV565Error):
+            rv565.write(io.BytesIO(), 4, 4, 24, [bytes(31)])
+        with self.assertRaises(rv565.RV565Error):
+            rv565.write(io.BytesIO(), 4, 4, 24, [])
+
+    def test_schedule_matches_paper_model(self):
+        report = rv565.open(VECTOR).check_schedule(overlap=True)
+        self.assertEqual(report.late_frames, 0)
+        self.assertAlmostEqual(report.worst_frame_us, 31312.0)
+
+    def test_pixel_conversion(self):
+        rgb = bytes([255, 0, 0, 0, 255, 0, 0, 0, 255, 255, 255, 255, 0, 0, 0])
+        be = rv565.rgb888_to_rgb565be(rgb)
+        self.assertEqual(be.hex(), "f80007e0001fffff0000")
+        self.assertEqual(rv565.rgb565be_to_rgb888(be), rgb)
+
+
+class CliTests(unittest.TestCase):
+    def run_cli(self, *args):
+        return subprocess.run([sys.executable, "-I", str(ROOT / "tools" / "rv565.py"), *args],
+                              capture_output=True, text=True, check=True).stdout
+
+    def test_info_and_verify(self):
+        self.assertIn("180x135, 24 FPS, 24 frames", self.run_cli("info", str(VECTOR)))
+        self.assertIn("24 frames verified", self.run_cli("verify", str(VECTOR)))
+
+    def test_c_array(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            out = os.path.join(tmp, "clip.h")
+            self.run_cli("c-array", str(VECTOR), out)
+            self.assertIn("rv565_clip_size", Path(out).read_text())
+
+
+@unittest.skipIf(Image is None, "Pillow not installed")
+class PillowTests(unittest.TestCase):
+    def test_open(self):
+        with Image.open(VECTOR) as im:
+            self.assertEqual(im.format, "RV565")
+            self.assertEqual((im.size, im.mode, im.n_frames), ((180, 135), "RGB", 24))
+            self.assertEqual(im.info["fps"], 24)
+            first = im.getpixel((0, 0))
+            im.seek(23)
+            self.assertEqual(im.tell(), 23)
+        self.assertEqual(first, (255, 255, 255))
+
+    def test_save_all_round_trip(self):
+        with Image.open(VECTOR) as im:
+            frames = [f.copy() for f in ImageSequence.Iterator(im)]
+        buf = io.BytesIO()
+        frames[0].save(buf, format="RV565", save_all=True, append_images=frames[1:], fps=24)
+        clip = rv565.open(buf.getvalue())
+        self.assertEqual(list(clip), list(rv565.open(VECTOR)))
+
+    def test_save_from_duration(self):
+        frames = [Image.new("RGB", (8, 8), c) for c in ("red", "blue")]
+        buf = io.BytesIO()
+        frames[0].save(buf, format="RV565", save_all=True, append_images=frames[1:], duration=100)
+        self.assertEqual(rv565.open(buf.getvalue()).fps, 10)
+
+
+if __name__ == "__main__":
+    unittest.main()