ascii-motion

Python package · OpenCV · NumPy · ANSI terminals

Video-to-ASCII playback for the terminal.

ascii-motion turns video files and camera streams into real-time ASCII animation. It captures frames with OpenCV, processes whole matrices with NumPy, and renders with ANSI sequences that avoid clearing the screen on every frame.

Install ascii-motion View commands
$ pipx install ascii-motion
$ ascii-motion video.mp4 --width 120 --color 256
ghostty · zsh · ascii-motion

Demo generated from the same processing path used by the CLI. Open GIF fallback.

Package overview

A focused CLI for terminal-native video rendering.

The package is built for developers who want visual playback, snapshots, exports, and repeatable demos without a GUI, audio layer, or browser canvas. Output is text written to stdout or files.

Input

Read video files, camera indexes such as 0, timestamps, durations, and loops.

Processing

Resize, luminance, Sobel edges, hybrid mode, ordered dithering, and character LUTs.

Output

Interactive playback, one-frame snapshots, text animation, ANSI animation, or frame directories.

Installation

Install it as a real command-line tool.

Use pipx for an isolated CLI install, pip for Python environments, Homebrew on macOS, or editable mode when developing locally.

Recommended

$ pipx install ascii-motion

Best for normal CLI usage because dependencies stay isolated from project environments.

PyPI

$ pip install ascii-motion

Use inside a virtual environment or any Python environment where OpenCV is acceptable.

Homebrew

$ brew install c4rl0s04/ascii-motion/ascii-motion

macOS-friendly install path for users who prefer Homebrew-managed tools.

Development

$ pip install -e ".[dev]"
$ python -m ascii_motion video.mp4

Editable install includes tests, linting, package build tools, and demo generation support.

Backend architecture

The rendering loop is split by responsibility.

The codebase separates video I/O, frame processing, timing, keyboard controls, and terminal output. That keeps the CLI understandable and leaves room for future processor backends.

VideoCapture OpenCV source frames in BGR order
Resize Terminal-aware aspect correction
Luminance / Edges Vectorized NumPy and Sobel transforms
Dither + LUT Matrix-to-character mapping
ANSI render / export Cursor-home output or file writing

Frame processing

OpenCV provides BGR arrays. FrameProcessor resizes frames, applies Rec. 709 luminance (0.2126R + 0.7152G + 0.0722B), optionally emphasizes edges, applies ordered dithering, then maps the matrix to an ASCII lookup table.

Terminal rendering

TerminalRenderer writes one frame payload at a time. It moves the cursor home with ANSI, clears line suffixes to remove stale text, hides the cursor during playback, and restores terminal state in finally paths.

Timing and controls

FrameClock targets accumulated frame deadlines to avoid drift. Keyboard controls handle quit, pause, seek, and help toggles without introducing a GUI or curses dependency.

Command reference

Every public option, grouped by workflow.

Each block shows what to type and what to expect. Commands are copyable and designed to work from a normal shell once ascii-motion is installed.

Source and sizing

Choose file/webcam input, target width/height, or fit the current terminal.

ascii-motion video.mp4
ascii-motion video.mp4 --width 120
ascii-motion video.mp4 --height 40
ascii-motion video.mp4 --fit-terminal
ascii-motion 0 --width 100

Result: live ASCII output sized for the terminal, with character aspect correction.

Playback timing

Control FPS, start point, duration, loop behavior, and frame skipping.

ascii-motion video.mp4 --fps 60
ascii-motion video.mp4 --start 10 --duration 5
ascii-motion video.mp4 --loop
ascii-motion video.mp4 --real-time
ascii-motion video.mp4 --no-frame-skip

Result: playback stays close to source duration by default, or renders every frame with --no-frame-skip.

Keyboard controls

Customize quit, pause, seek, help, and seek distance for interactive playback.

ascii-motion video.mp4 --quit-key x
ascii-motion video.mp4 --pause-key p
ascii-motion video.mp4 --backward-key j --forward-key k
ascii-motion video.mp4 --help-key !
ascii-motion video.mp4 --seek-seconds 10

Result: q, space, arrow keys, h/l, and ? can be remapped for the terminal you use.

Terminal UI

Control HUD, progress, controls overlay, alternate screen, and performance reporting.

ascii-motion video.mp4 --no-hud
ascii-motion video.mp4 --no-progress
ascii-motion video.mp4 --show-controls
ascii-motion video.mp4 --no-alt-screen
ascii-motion video.mp4 --benchmark

Result: playback can be clean, inspectable, or benchmarked depending on the terminal workflow.

Visual modes and characters

Switch between luminance, edge, hybrid, dithered, inverted, dense, block, or custom ramps.

ascii-motion video.mp4 --charset dense
ascii-motion video.mp4 --charset blocks
ascii-motion video.mp4 --charset custom --chars " .oO@"
ascii-motion video.mp4 --invert
ascii-motion video.mp4 --mode edges
ascii-motion video.mp4 --mode hybrid --dither ordered
ascii-motion --list-charsets

Result: output can emphasize tones, contours, or high-density terminal detail.

ANSI color

Choose plain text for speed or richer ANSI color for live playback and exports.

ascii-motion video.mp4 --color none
ascii-motion video.mp4 --color truecolor
ascii-motion video.mp4 --color 256
ascii-motion video.mp4 --color grayscale

Result: none is fastest, 256 is a practical color mode, and truecolor is richest.

Preview and export

Use non-interactive modes for docs, snapshots, terminal recordings, and file workflows.

ascii-motion video.mp4 --preview
ascii-motion video.mp4 --frame-at 5 --width 100 > frame.txt
ascii-motion video.mp4 --export output.txt --duration 5
ascii-motion video.mp4 --export-ansi output.ans --color 256
ascii-motion video.mp4 --export-frames frames --start 2 --duration 4

Result: export modes skip alternate screen and keyboard control, producing stdout or file output.

Metadata

Inspect installed version or print the built-in CLI help.

ascii-motion --version
ascii-motion --help

Result: confirm the installed release and discover all available flags.

Video demo

See the terminal output before installing.

The video shows a generated demo source moving through the same ASCII processor used by playback. It is intentionally local-first: no hosted player, no tracking script, no external runtime.

$ ascii-motion demo.mp4 --width 74 --color truecolor
Open GIF fallback

Compatibility

Terminal performance depends on output size and color mode.

The Python pipeline is vectorized, but terminals still need to draw the resulting text. Wider output and truecolor sequences increase stdout volume.

Terminal Status Notes
Ghostty Tested Best current validation target for high-FPS playback.
iTerm2, Alacritty, WezTerm Expected Modern ANSI support, still worth validating per machine.
Terminal.app, VS Code terminal Expected Standard paths should work, high widths may reduce effective FPS.
tmux Needs validation Depends on truecolor and terminal-overrides configuration.