caramelldansen 1.0.0__tar.gz

caramelldansen-1.0.0/LICENSE

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

caramelldansen-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: caramelldansen
+Version: 1.0.0
+Summary: Caramell Dansen Terminal Player — High Performance TrueColor & Unicode with Dansen Loop
+Author: Ohualtex
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ohualtex/caramelldansen
+Project-URL: Repository, https://github.com/Ohualtex/caramelldansen.git
+Project-URL: Bug Tracker, https://github.com/Ohualtex/caramelldansen/issues
+Keywords: caramelldansen,terminal,ascii-art,truecolor,braille,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video :: Display
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: pygame>=2.5.0
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file
+
+# Caramelldansen in Terminal 🍭✨
+
+[![PyPI version](https://img.shields.io/pypi/v/caramelldansen.svg)](https://pypi.org/project/caramelldansen/)
+[![Python Version](https://img.shields.io/pypi/pyversions/caramelldansen.svg)](https://pypi.org/project/caramelldansen/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg)](https://github.com/Ohualtex/caramelldansen)
+
+High-performance, flicker-free, 24-bit TrueColor **Caramelldansen** terminal player featuring **Dansen Loop** mode!
+
+Built with a modular **Platform Abstraction Layer (PAL)** and **Audio Master Clock** architecture, providing zero-configuration, cross-platform audio and rendering on **macOS, Windows, and Linux**.
+
+---
+
+## Features
+
+- **24-bit TrueColor Rendering:**
+  - `halfblock` (Default): Uses half-block characters (`▀`, `▄`) with 24-bit TrueColor for near-square pixels and stunning visual fidelity.
+  - `color-ascii`: Classic ASCII character brightness ramp combined with full RGB color.
+  - `braille`: High-resolution Unicode Braille (2x4 dot matrix) rendering.
+  - `ascii`: Nostalgic monochrome ASCII shading.
+- **Dansen Loop Mode (Infinite Loop):**
+  - Starts directly in the iconic Mai & Mii chorus dance sequence and loops seamlessly without stutter or glitches.
+  - Toggle between the dance loop and the full music video using the `L` key or CLI flags.
+- **Audio Master Clock Engine:**
+  - Video rendering is strictly synchronized to hardware audio playback time for flawless rhythm alignment and zero audio-video drift.
+- **Zero-CPU Binary Cache Engine (CDBP v1):**
+  - Streams from a pre-rendered, zlib-compressed RGB binary container (`caramell_dansen.bin`) for <1% CPU consumption and instantaneous seek times.
+- **Automatic Asset Provisioning:**
+  - Installs in seconds as a featherlight (<40 KB) PyPI wheel! Video and audio assets are automatically downloaded on first launch with live progress bar and MD5 verification.
+- **Flicker-Free Terminal Experience:**
+  - Uses Alternate Screen Buffer (`\033[?1049h`), cursor hiding, Win32 VT100 processing, and non-blocking I/O.
+- **Responsive Sizing & Interactive Scrubber:**
+  - Automatically respects 16:9 aspect ratio, centers video in any terminal window, and renders an adaptive live HUD status bar.
+
+---
+
+## Controls
+
+| Key | Action |
+| :--- | :--- |
+| **Space** | Pause / Resume |
+| **M** | Cycle Render Mode (`halfblock` → `color-ascii` → `braille` → `ascii`) |
+| **C** | Toggle Color Mode (TrueColor RGB ↔ Monochrome) |
+| **L** | Toggle **Dansen Loop** mode |
+| **Right Arrow ($\rightarrow$)** | Seek forward 5 seconds |
+| **Left Arrow ($\leftarrow$)** | Seek backward 5 seconds |
+| **R** | Restart playback |
+| **Q / Esc** | Quit cleanly |
+
+---
+
+## Installation & Quick Start
+
+### Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install caramelldansen
+```
+
+Run directly from any terminal:
+```bash
+caramelldansen
+```
+
+### Option 2: Run from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/Ohualtex/caramelldansen.git
+cd caramelldansen
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Start playback (starts directly in Dansen Loop mode)
+python main.py
+
+# Play full music video from start
+python main.py --full
+
+# Select rendering mode
+python main.py --mode color-ascii
+```
+
+---
+
+## CLI Options
+
+```text
+usage: caramelldansen [-h] [--mode {halfblock,color-ascii,braille,ascii}] [--no-color] [--loop] [--full] [--no-audio] [--build-cache]
+
+options:
+  -h, --help            show this help message and exit
+  --mode {halfblock,color-ascii,braille,ascii}
+                        Rendering mode (default: halfblock)
+  --no-color, --mono    Disable TrueColor rendering and run in monochrome
+  --loop                Start in infinite Dansen Loop mode (default: True)
+  --full                Play full music video from start to finish
+  --no-audio            Mute audio and run on internal clock
+  --build-cache         Force rebuild CDBP binary cache
+```
+
+---
+
+## Terminal Display Tips
+
+### macOS Terminal.app (Gapless Half-Block Display)
+The default macOS `Terminal.app` adds vertical line leading (font spacing) between character rows. For a gapless, seamless display:
+1. Open **Terminal** → **Settings** (`Cmd + ,`) → **Profiles** → **Text**.
+2. Click **Change...** under Font.
+3. Set the **Line Spacing** slider to **`0.80`**.
+4. Alternatively, press **`M`** in-player to switch to **Braille mode** (which is naturally immune to line spacing), or use modern GPU-accelerated terminals like [Ghostty](https://ghostty.org/), [iTerm2](https://iterm2.com/), or [Kitty](https://sw.kovidgoyal.net/kitty/).
+
+### Windows Terminal
+Runs out of the box in [Windows Terminal](https://github.com/microsoft/terminal), PowerShell, and Command Prompt with 24-bit TrueColor enabled via Win32 Virtual Terminal Processing.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

caramelldansen-1.0.0/README.md

@@ -0,0 +1,121 @@
+# Caramelldansen in Terminal 🍭✨
+
+[![PyPI version](https://img.shields.io/pypi/v/caramelldansen.svg)](https://pypi.org/project/caramelldansen/)
+[![Python Version](https://img.shields.io/pypi/pyversions/caramelldansen.svg)](https://pypi.org/project/caramelldansen/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg)](https://github.com/Ohualtex/caramelldansen)
+
+High-performance, flicker-free, 24-bit TrueColor **Caramelldansen** terminal player featuring **Dansen Loop** mode!
+
+Built with a modular **Platform Abstraction Layer (PAL)** and **Audio Master Clock** architecture, providing zero-configuration, cross-platform audio and rendering on **macOS, Windows, and Linux**.
+
+---
+
+## Features
+
+- **24-bit TrueColor Rendering:**
+  - `halfblock` (Default): Uses half-block characters (`▀`, `▄`) with 24-bit TrueColor for near-square pixels and stunning visual fidelity.
+  - `color-ascii`: Classic ASCII character brightness ramp combined with full RGB color.
+  - `braille`: High-resolution Unicode Braille (2x4 dot matrix) rendering.
+  - `ascii`: Nostalgic monochrome ASCII shading.
+- **Dansen Loop Mode (Infinite Loop):**
+  - Starts directly in the iconic Mai & Mii chorus dance sequence and loops seamlessly without stutter or glitches.
+  - Toggle between the dance loop and the full music video using the `L` key or CLI flags.
+- **Audio Master Clock Engine:**
+  - Video rendering is strictly synchronized to hardware audio playback time for flawless rhythm alignment and zero audio-video drift.
+- **Zero-CPU Binary Cache Engine (CDBP v1):**
+  - Streams from a pre-rendered, zlib-compressed RGB binary container (`caramell_dansen.bin`) for <1% CPU consumption and instantaneous seek times.
+- **Automatic Asset Provisioning:**
+  - Installs in seconds as a featherlight (<40 KB) PyPI wheel! Video and audio assets are automatically downloaded on first launch with live progress bar and MD5 verification.
+- **Flicker-Free Terminal Experience:**
+  - Uses Alternate Screen Buffer (`\033[?1049h`), cursor hiding, Win32 VT100 processing, and non-blocking I/O.
+- **Responsive Sizing & Interactive Scrubber:**
+  - Automatically respects 16:9 aspect ratio, centers video in any terminal window, and renders an adaptive live HUD status bar.
+
+---
+
+## Controls
+
+| Key | Action |
+| :--- | :--- |
+| **Space** | Pause / Resume |
+| **M** | Cycle Render Mode (`halfblock` → `color-ascii` → `braille` → `ascii`) |
+| **C** | Toggle Color Mode (TrueColor RGB ↔ Monochrome) |
+| **L** | Toggle **Dansen Loop** mode |
+| **Right Arrow ($\rightarrow$)** | Seek forward 5 seconds |
+| **Left Arrow ($\leftarrow$)** | Seek backward 5 seconds |
+| **R** | Restart playback |
+| **Q / Esc** | Quit cleanly |
+
+---
+
+## Installation & Quick Start
+
+### Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install caramelldansen
+```
+
+Run directly from any terminal:
+```bash
+caramelldansen
+```
+
+### Option 2: Run from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/Ohualtex/caramelldansen.git
+cd caramelldansen
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Start playback (starts directly in Dansen Loop mode)
+python main.py
+
+# Play full music video from start
+python main.py --full
+
+# Select rendering mode
+python main.py --mode color-ascii
+```
+
+---
+
+## CLI Options
+
+```text
+usage: caramelldansen [-h] [--mode {halfblock,color-ascii,braille,ascii}] [--no-color] [--loop] [--full] [--no-audio] [--build-cache]
+
+options:
+  -h, --help            show this help message and exit
+  --mode {halfblock,color-ascii,braille,ascii}
+                        Rendering mode (default: halfblock)
+  --no-color, --mono    Disable TrueColor rendering and run in monochrome
+  --loop                Start in infinite Dansen Loop mode (default: True)
+  --full                Play full music video from start to finish
+  --no-audio            Mute audio and run on internal clock
+  --build-cache         Force rebuild CDBP binary cache
+```
+
+---
+
+## Terminal Display Tips
+
+### macOS Terminal.app (Gapless Half-Block Display)
+The default macOS `Terminal.app` adds vertical line leading (font spacing) between character rows. For a gapless, seamless display:
+1. Open **Terminal** → **Settings** (`Cmd + ,`) → **Profiles** → **Text**.
+2. Click **Change...** under Font.
+3. Set the **Line Spacing** slider to **`0.80`**.
+4. Alternatively, press **`M`** in-player to switch to **Braille mode** (which is naturally immune to line spacing), or use modern GPU-accelerated terminals like [Ghostty](https://ghostty.org/), [iTerm2](https://iterm2.com/), or [Kitty](https://sw.kovidgoyal.net/kitty/).
+
+### Windows Terminal
+Runs out of the box in [Windows Terminal](https://github.com/microsoft/terminal), PowerShell, and Command Prompt with 24-bit TrueColor enabled via Win32 Virtual Terminal Processing.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

caramelldansen-1.0.0/cache.py

@@ -0,0 +1,342 @@
+"""
+CDBP (Caramell Dansen Binary Pre-rendered) cache engine.
+
+Provides zero-CPU, instant random-access playback of color Caramelldansen frames
+by storing RGB video frames compressed with zlib alongside an indexed lookup table
+and loop-point markers.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import struct
+import subprocess
+import time
+import zlib
+from typing import Callable, Optional, Tuple
+import numpy as np
+
+# Header specification (Total: 32 bytes)
+# <4s : Magic bytes (b"CDBP")
+# H   : Version (uint16 = 1)
+# H   : Width (uint16)
+# H   : Height (uint16)
+# f   : FPS (float32)
+# I   : Total frames (uint32)
+# B   : Color format (1 = RGB24 zlib)
+# I   : Loop start frame (uint32)
+# I   : Loop end frame (uint32)
+# 3s  : Reserved padding
+CDBP_MAGIC = b"CDBP"
+CDBP_VERSION = 1
+COLOR_FORMAT_RGB24 = 1
+
+HEADER_STRUCT = struct.Struct("<4sHHHfIBII3s")
+INDEX_ENTRY_STRUCT = struct.Struct("<IH")  # offset (uint32), compressed_size (uint16)
+
+
+class BinaryCacheError(Exception):
+    """Exception raised for cache corruption or builder errors."""
+    pass
+
+
+class BinaryCacheBuilder:
+    """Encodes MP4 video frames into a high-speed CDBP binary container using ffmpeg."""
+
+    @staticmethod
+    def build_cache(
+        video_path: str,
+        output_path: str,
+        target_width: int = 160,
+        target_height: int = 90,
+        fps: float = 25.0,
+        loop_start_sec: float = 30.5,
+        loop_end_sec: float = 59.5,
+        progress_callback: Optional[Callable[[int, int, float], None]] = None,
+    ) -> None:
+        """
+        Extracts RGB frames from source video using ffmpeg, compresses each frame
+        with zlib, and builds an indexed CDBP binary cache file.
+        """
+        if not os.path.exists(video_path):
+            raise BinaryCacheError(f"Source video not found at '{video_path}'.")
+
+        os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+        temp_output = output_path + ".tmp"
+        if os.path.exists(temp_output):
+            try:
+                os.remove(temp_output)
+            except OSError:
+                pass
+
+        has_ffmpeg = shutil.which("ffmpeg") is not None and shutil.which("ffprobe") is not None
+
+        if has_ffmpeg:
+            # Get video duration using ffprobe
+            probe_cmd = [
+                "ffprobe",
+                "-v",
+                "error",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "default=noprint_wrappers=1:nokey=1",
+                video_path,
+            ]
+            try:
+                dur_str = subprocess.check_output(probe_cmd, text=True).strip()
+                duration = float(dur_str)
+            except Exception as e:
+                raise BinaryCacheError(f"Failed to probe video duration: {e}")
+
+            total_frames = int(duration * fps)
+            loop_start_frame = int(loop_start_sec * fps)
+            loop_end_frame = int(loop_end_sec * fps)
+
+            frame_bytes_len = target_width * target_height * 3
+            ffmpeg_cmd = [
+                "ffmpeg",
+                "-v",
+                "error",
+                "-i",
+                video_path,
+                "-vf",
+                f"scale={target_width}:{target_height}",
+                "-r",
+                str(fps),
+                "-f",
+                "rawvideo",
+                "-pix_fmt",
+                "rgb24",
+                "-",
+            ]
+
+            proc = subprocess.Popen(
+                ffmpeg_cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                bufsize=frame_bytes_len * 4,
+            )
+
+            index_entries: list[tuple[int, int]] = []
+            start_time = time.perf_counter()
+
+            try:
+                with open(temp_output, "wb") as f:
+                    f.write(b"\x00" * HEADER_STRUCT.size)
+                    current_frame = 0
+                    while True:
+                        raw_frame = proc.stdout.read(frame_bytes_len)
+                        if not raw_frame or len(raw_frame) < frame_bytes_len:
+                            break
+
+                        compressed = zlib.compress(raw_frame, level=6)
+                        offset = f.tell()
+                        comp_size = len(compressed)
+
+                        if comp_size > 65535:
+                            raise BinaryCacheError(
+                                f"Compressed frame {current_frame} exceeded uint16 max size ({comp_size} bytes)."
+                            )
+
+                        f.write(compressed)
+                        index_entries.append((offset, comp_size))
+                        current_frame += 1
+
+                        if progress_callback and (current_frame % 25 == 0 or current_frame == total_frames):
+                            elapsed = time.perf_counter() - start_time
+                            progress_callback(current_frame, total_frames, elapsed)
+
+                    actual_total_frames = len(index_entries)
+                    if actual_total_frames == 0:
+                        raise BinaryCacheError("No frames were extracted from the video stream.")
+
+                    index_table_offset = f.tell()
+                    for offset, comp_size in index_entries:
+                        f.write(INDEX_ENTRY_STRUCT.pack(offset, comp_size))
+
+                    f.seek(0)
+                    f.write(
+                        HEADER_STRUCT.pack(
+                            CDBP_MAGIC,
+                            CDBP_VERSION,
+                            target_width,
+                            target_height,
+                            fps,
+                            actual_total_frames,
+                            COLOR_FORMAT_RGB24,
+                            loop_start_frame,
+                            loop_end_frame,
+                            b"\x00" * 3,
+                        )
+                    )
+            finally:
+                if proc.poll() is None:
+                    proc.terminate()
+                    proc.wait()
+
+        else:
+            # Fallback to OpenCV (cv2)
+            try:
+                import cv2
+            except ImportError:
+                raise BinaryCacheError(
+                    "Neither ffmpeg/ffprobe CLI tools nor opencv-python (cv2) is available to process video."
+                )
+
+            cap = cv2.VideoCapture(video_path)
+            if not cap.isOpened():
+                raise BinaryCacheError(f"OpenCV failed to open video file at '{video_path}'.")
+
+            src_fps = cap.get(cv2.CAP_PROP_FPS) or fps
+            src_frame_count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
+            duration = src_frame_count / max(1.0, src_fps)
+            total_frames = int(duration * fps)
+
+            loop_start_frame = int(loop_start_sec * fps)
+            loop_end_frame = int(loop_end_sec * fps)
+
+            index_entries = []
+            start_time = time.perf_counter()
+
+            try:
+                with open(temp_output, "wb") as f:
+                    f.write(b"\x00" * HEADER_STRUCT.size)
+                    current_frame = 0
+
+                    while True:
+                        ret, frame = cap.read()
+                        if not ret or frame is None:
+                            break
+
+                        resized = cv2.resize(frame, (target_width, target_height), interpolation=cv2.INTER_AREA)
+                        rgb_frame = cv2.cvtColor(resized, cv2.COLOR_BGR2RGB)
+                        raw_bytes = rgb_frame.tobytes()
+
+                        compressed = zlib.compress(raw_bytes, level=6)
+                        offset = f.tell()
+                        comp_size = len(compressed)
+
+                        if comp_size > 65535:
+                            raise BinaryCacheError(
+                                f"Compressed frame {current_frame} exceeded uint16 max size ({comp_size} bytes)."
+                            )
+
+                        f.write(compressed)
+                        index_entries.append((offset, comp_size))
+                        current_frame += 1
+
+                        if progress_callback and (current_frame % 25 == 0 or current_frame == total_frames):
+                            elapsed = time.perf_counter() - start_time
+                            progress_callback(current_frame, total_frames, elapsed)
+
+                    actual_total_frames = len(index_entries)
+                    if actual_total_frames == 0:
+                        raise BinaryCacheError("No frames were extracted from OpenCV stream.")
+
+                    index_table_offset = f.tell()
+                    for offset, comp_size in index_entries:
+                        f.write(INDEX_ENTRY_STRUCT.pack(offset, comp_size))
+
+                    f.seek(0)
+                    f.write(
+                        HEADER_STRUCT.pack(
+                            CDBP_MAGIC,
+                            CDBP_VERSION,
+                            target_width,
+                            target_height,
+                            fps,
+                            actual_total_frames,
+                            COLOR_FORMAT_RGB24,
+                            loop_start_frame,
+                            loop_end_frame,
+                            b"\x00" * 3,
+                        )
+                    )
+            finally:
+                cap.release()
+
+        # Atomic rename
+        if os.path.exists(output_path):
+            os.remove(output_path)
+        os.rename(temp_output, output_path)
+
+
+class BinaryCacheReader:
+    """Reads CDBP binary cache files with instant seek and low memory overhead."""
+
+    def __init__(self, cache_path: str):
+        self.cache_path = os.path.abspath(cache_path)
+        if not os.path.exists(self.cache_path):
+            raise BinaryCacheError(f"Cache file not found at '{self.cache_path}'.")
+
+        self._file = open(self.cache_path, "rb")
+        header_data = self._file.read(HEADER_STRUCT.size)
+        if len(header_data) < HEADER_STRUCT.size:
+            raise BinaryCacheError("Incomplete cache header.")
+
+        (
+            magic,
+            version,
+            self.width,
+            self.height,
+            self.fps,
+            self.total_frames,
+            self.color_format,
+            self.loop_start_frame,
+            self.loop_end_frame,
+            _,
+        ) = HEADER_STRUCT.unpack(header_data)
+
+        if magic != CDBP_MAGIC:
+            raise BinaryCacheError(f"Invalid magic bytes '{magic!r}', expected '{CDBP_MAGIC!r}'.")
+        if version != CDBP_VERSION:
+            raise BinaryCacheError(f"Unsupported CDBP version {version}.")
+
+        self.duration = float(self.total_frames) / float(self.fps) if self.fps > 0 else 0.0
+        self.loop_start_sec = float(self.loop_start_frame) / float(self.fps) if self.fps > 0 else 0.0
+        self.loop_end_sec = float(self.loop_end_frame) / float(self.fps) if self.fps > 0 else self.duration
+
+        # Read index table
+        index_table_size = self.total_frames * INDEX_ENTRY_STRUCT.size
+        self._file.seek(-index_table_size, os.SEEK_END)
+        index_data = self._file.read(index_table_size)
+        if len(index_data) < index_table_size:
+            raise BinaryCacheError("Incomplete index table.")
+
+        # Unpack index table: offsets (uint32) and sizes (uint16)
+        table = np.frombuffer(index_data, dtype=[("offset", "<u4"), ("size", "<u2")])
+        self._offsets = table["offset"]
+        self._sizes = table["size"]
+
+    def get_frame(self, frame_index: int) -> np.ndarray:
+        """Retrieves and decompresses an RGB frame as numpy array (H, W, 3)."""
+        idx = max(0, min(self.total_frames - 1, frame_index))
+        offset = int(self._offsets[idx])
+        size = int(self._sizes[idx])
+
+        self._file.seek(offset)
+        compressed = self._file.read(size)
+        raw_rgb = zlib.decompress(compressed)
+
+        frame = np.frombuffer(raw_rgb, dtype=np.uint8).reshape((self.height, self.width, 3))
+        return frame
+
+    def get_frame_for_time(self, seconds: float) -> Tuple[np.ndarray, int]:
+        """Returns the frame corresponding to the specified playback time."""
+        seconds = max(0.0, seconds)
+        idx = int(seconds * self.fps)
+        idx = min(self.total_frames - 1, idx)
+        return self.get_frame(idx), idx
+
+    def close(self) -> None:
+        """Closes the underlying binary file."""
+        if hasattr(self, "_file") and self._file:
+            self._file.close()
+
+    def __enter__(self) -> "BinaryCacheReader":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()