Metadata-Version: 2.4
Name: caramelldansen
Version: 1.0.1
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.
