Metadata-Version: 2.4
Name: clmp
Version: 4.0.1
Summary: CLI Movie Package — Turn MP4 videos into colored ASCII terminal animations with audio
Project-URL: Homepage, https://github.com/1ypi/clmp
Project-URL: Repository, https://github.com/1ypi/clmp
Project-URL: Issues, https://github.com/1ypi/clmp/issues
Author: CLMP Contributors
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: animation,ascii,cli,movie,player,terminal,video
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: sounddevice
Description-Content-Type: text/markdown

# CLMP — CLI Movie Package

Turn any MP4 video into a high-performance colored ASCII animation that plays entirely in your terminal — with audio.

## Installation

```bash
pip install clmp
```

## Requirements

- Python 3.8+
- [FFmpeg](https://ffmpeg.org/download.html) — must be on your PATH (used for audio extraction and decoding)

> **Note:** CLMP will offer to install FFmpeg for you automatically if it's not found.

## Features

- **Blazing Fast Delta-Rendering** — Uses a virtual back-buffer to only update changed characters, enabling 120+ FPS playback in native terminals.
- **Colored ASCII art** — each character is tinted with the original pixel color using 24-bit ANSI truecolor.
- **Frame-Dropping Audio Sync** — Professional audio-led synchronization that automatically drops video frames to stay perfectly locked to the audio clock.
- **Embedded audio** — audio is extracted as OGG Vorbis and played back in sync via `sounddevice`.
- **Full playback controls** — pause, speed up/down, seek, volume, quit.
- **Persistent Settings** — Customize your experience (jump size, volume steps) via `clmp set`.
- **Auto-scaling** — fits to any terminal size using nearest-neighbor resampling.
- **Compact format** — frames are zlib-compressed, audio stored as OGG Vorbis.
- **Cross-platform** — works on Windows, macOS, and Linux.

## Usage

### Encode

Convert an MP4 to a `.clmp` file:

```bash
clmp encode input.mp4 output.clmp
```

Options:

| Flag | Default | Description |
|------|---------|-------------|
| `--fps` | `12` | Target playback framerate |
| `--width` | `160` | ASCII columns |
| `--height` | `45` | ASCII rows |

### Play

```bash
clmp play output.clmp
```

Options:

| Flag | Description |
|------|-------------|
| `--speed 1.0` | Initial playback speed multiplier |
| `--loop` | Loop the video |
| `--no-scale` | Disable auto terminal scaling |
| `--no-color` | Disable colored output |
| `--no-audio` | Disable audio playback |

### Configure

Use `clmp set` to customize your playback experience. Settings are saved in `~/.clmp/settings.json`.

```bash
# Set jump distance to 5 seconds
clmp set --jump 5

# Set volume increments to 5%
clmp set --vol-step 5

# Set default starting volume
clmp set --volume 50
```

### Controls

| Key | Action |
|-----|--------|
| `Space` | Pause / resume |
| `+` / `-` | Speed up / slow down (±0.25x) |
| `↑` / `↓` | Volume up / down (Customizable step) |
| `←` / `→` | Seek backward / forward (Customizable seconds) |
| `q` | Quit |

## .clmp Format (v4)

Binary file layout (little-endian):

```
┌─────────────────────────────────────────┐
│ Header (79 bytes)                       │
│   4s   magic          "CLMP"            │
│   B    version        4                 │
│   H    cols           ASCII width       │
│   H    rows           ASCII height      │
│   f    fps            playback fps      │
│   I    frame_count    number of frames  │
│   64s  source_name    original filename │
├─────────────────────────────────────────┤
│ Frames (repeated × frame_count)         │
│   I    ascii_size     compressed size   │
│   ...  ascii_data     zlib(ASCII text)  │
│   I    color_size     compressed size   │
│   ...  color_data     zlib(RGB bytes)   │
├─────────────────────────────────────────┤
│ Audio                                   │
│   I    audio_size     0 = no audio      │
│   ...  audio_data     raw OGG bytes     │
└─────────────────────────────────────────┘
```

## License

GNU General Public License v3 (GPLv3) (GPL-3.0-only)
