Metadata-Version: 2.4
Name: bad-apple-in-terminal
Version: 1.1.2
Summary: Bad Apple!! Terminal ASCII & Unicode Player with hardware-accelerated audio and responsive resizing.
Author: Ohualtex
License-Expression: MIT
Project-URL: Homepage, https://github.com/Ohualtex/bad-apple
Project-URL: Repository, https://github.com/Ohualtex/bad-apple.git
Project-URL: Issues, https://github.com/Ohualtex/bad-apple/issues
Keywords: bad-apple,terminal,ascii-art,braille,cli,pygame,opencv
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video :: Display
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.5.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: numpy>=1.24.0
Dynamic: license-file

# Bad Apple!! Terminal Player 🍎

[![PyPI version](https://img.shields.io/pypi/v/bad-apple-in-terminal.svg)](https://pypi.org/project/bad-apple-in-terminal/)
[![Python Version](https://img.shields.io/pypi/pyversions/bad-apple-in-terminal.svg)](https://pypi.org/project/bad-apple-in-terminal/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Flicker-free, audio-synced Bad Apple!! player for your terminal.

## Features

- **3 Rendering Modes:**
  - `ascii` (Default): Classic nostalgic ASCII shading (` .:-=+*#%@`).
  - `braille`: Ultra high-resolution rendering using Unicode Braille (2x4 matrix) characters.
  - `halfblock`: 2x vertical resolution using half-block characters (`▀`, `▄`) for crystal-clear silhouettes.
- **Zero-Setup & Featherlight Footprint:** Installs in seconds without bloated dependencies! Automatically provisions media assets with MD5 checksum verification.
- **Zero-CPU Binary Cache Engine (BAPB v1):** Plays from a pre-rendered, zlib-compressed 1-bit binary cache (`bad_apple.bin`, ~7.7 MB) for <0.5% CPU consumption and instantaneous (0.04 ms) seeking!
- **Cross-Platform Audio Engine:** Backed by `pygame.mixer` for distortion-free pause/resume and zero-latency seeking, with fallback to native OS drivers on Windows (`winmm.dll` MCI), macOS (`afplay`), and Linux (`ffplay`/`mpv`/`aplay`).
- **Flicker-Free & Ghost-Free Rendering:** Employs Alternate Screen Buffer (`\033[?1049h`), scrollback buffer purging, and dynamic resizing for a pristine, clean display at 30 FPS.
- **Dynamic Sizing & Visual Scrubber:** Automatically senses terminal dimensions, preserves the 4:3 aspect ratio, centers output, and displays an interactive progress bar.

## Controls

| Key | Action |
|-----|--------|
| **Space** | Pause / Resume |
| **M** | Cycle render modes (`ascii` → `braille` → `halfblock`) |
| **Right Arrow (→)** | Seek forward 5 seconds |
| **Left Arrow (←)** | Seek backward 5 seconds |
| **R** | Restart playback |
| **Q / Esc** | Quit |

## Installation & Quick Start

### Option 1: Install via pip (Recommended)

```bash
pip install bad-apple-in-terminal
```

Run it directly from anywhere in your terminal:
```bash
bad-apple
# or
badapple
```

### Option 2: Run from Source (Zero-Setup)

Just clone and run! Required dependencies and media files are automatically prepared on first launch:

```bash
git clone https://github.com/Ohualtex/bad-apple.git
cd bad-apple
python main.py
```

### Options & Flags

```bash
# Start with a specific render mode (ascii, braille, halfblock)
bad-apple --mode ascii

# Pre-render compact binary cache for zero-CPU playback and instantaneous seek
bad-apple --build-cache

# Force real-time OpenCV decoding instead of binary cache
bad-apple --no-cache

# Disable audio
bad-apple --no-audio

# Set specific terminal width/height
bad-apple --width 100 --height 35
```

### macOS Tips

- **Gapless Half-Block Display:**  
  The default macOS Terminal.app adds vertical font leading (line spacing) between lines. To achieve a seamless, OLED-smooth display:
  1. Open **Terminal** → **Settings** (`Cmd + ,`) → **Profiles** → **Text**.
  2. Click **Change...** under Font.
  3. Expand the font window downward if needed, and set the **Line Spacing** slider to **`0.80`**.
  4. Alternatively, press **`M`** to switch to **Braille mode** (which is naturally immune to line spacing), or use modern terminals like [iTerm2](https://iterm2.com/), [Ghostty](https://ghostty.org/), or [Kitty](https://sw.kovidgoyal.net/kitty/).


