Caramelldansen in Terminal 🍭✨

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

Installation & Quick Start

Option 1: Install from PyPI (Recommended)

pip install caramelldansen

Run directly from any terminal:

caramelldansen

Option 2: Run from Source

# Clone the repository
git clone https://github.com/Ohualtex/caramelldansen.git
cd caramelldansen

# Install dependencies
pip install -r requirements.txt

# Start playback (plays full music video from 00:00)
python main.py

# Start directly in infinite Dansen Loop mode
python main.py --loop

# Select rendering mode
python main.py --mode color-ascii

CLI Options

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
  --full                Play full music video from start to finish (default)
  --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, iTerm2, or Kitty.

Windows Terminal

Runs out of the box in Windows Terminal, PowerShell, and Command Prompt with 24-bit TrueColor enabled via Win32 Virtual Terminal Processing.

License

MIT License. See LICENSE for details.