Skip to content

README.md

Latest commit

 

History

History
344 lines (247 loc) · 12.5 KB

README.md

File metadata and controls

344 lines (247 loc) · 12.5 KB

ConsoleImage CLI

Unified command-line tool for rendering images, GIFs, videos, and playing cidz/json documents as ASCII art.

Part of the ConsoleImage project.

NuGet License: Unlicense

Features

  • Images - JPG, PNG, BMP, WebP, TIFF with shape-matched ASCII rendering
  • Animated GIFs - Smooth flicker-free playback with DECSET 2026
  • Videos - Any FFmpeg-supported format (MP4, MKV, AVI, WebM, etc.)
  • Document playback - Play saved .cidz/.json documents without original source
  • Four render modes - ASCII, ColorBlocks (▀▄), Braille, Matrix rain
  • GIF output - Convert any input to animated GIF
  • Compressed documents - Save rendered output as .cidz for sharing/playback

Example Output

ASCII Mode ColorBlocks Mode Braille Mode
ASCII Blocks Braille

Installation

Download from GitHub Releases:

Platform Download
Windows x64 consoleimage-win-x64.zip
Linux x64 consoleimage-linux-x64.tar.gz
Linux ARM64 consoleimage-linux-arm64.tar.gz
macOS ARM64 consoleimage-osx-arm64.tar.gz

Requirements

  • Terminal with ANSI support - Windows Terminal, iTerm2, any modern terminal
  • FFmpeg - Only needed for video files (auto-downloads on first video use)
    • Images, GIFs, and cidz documents work without FFmpeg

Quick Start

# === IMAGES (braille mode is default in v3.0+) ===
consoleimage photo.jpg                    # Braille mode (default)
consoleimage photo.jpg --ascii            # Classic ASCII characters
consoleimage photo.png --blocks           # High-fidelity color blocks (▀▄)
consoleimage photo.png --matrix           # Matrix digital rain effect
consoleimage https://example.com/img.jpg  # Load from URL

# === ANIMATED GIFs ===
consoleimage animation.gif                # Play animation
consoleimage animation.gif --speed 1.5    # Speed up playback
consoleimage animation.gif --loop 3       # Play 3 times then stop

# === VIDEOS (FFmpeg auto-downloads on first use) ===
consoleimage movie.mp4                    # Play video as ASCII
consoleimage movie.mkv --blocks -w 120    # Color blocks, 120 chars wide
consoleimage movie.mp4 --ss 60 -t 30      # Start at 60s, play 30 seconds

# === SAVE TO DOCUMENT ===
consoleimage animation.gif -o output.cidz # Save as compressed document
consoleimage movie.mp4 -o movie.cidz -b   # Save video in blocks mode

# === PLAY DOCUMENTS ===
consoleimage output.cidz                  # Play saved document
consoleimage movie.cidz --speed 2.0       # Playback with 2x speed

# === CONVERT TO GIF ===
consoleimage animation.gif -o output.gif  # GIF to ASCII GIF
consoleimage movie.mp4 -o movie.gif       # Video to ASCII GIF
consoleimage movie.cidz -o movie.gif      # Document to GIF

Render Modes

Mode CLI Option Description Best For
Braille (default) Braille patterns (2×4 dots/cell) DEFAULT - Maximum resolution
ASCII -a, --ascii Shape-matched ASCII characters Widest compatibility
ColorBlocks -b, --blocks Unicode half-blocks (▀▄) High fidelity, photos
Matrix -M, --matrix Digital rain effect Stylized output

CLI Options

Input/Output

Option Description Default
input Image, GIF, video, or cidz/json document Required
-o, --output Output file (.gif, .cidz, .json) Console

Dimensions

Option Description Default
-w, --width Output width in characters Auto (console width)
-h, --height Output height in characters Auto
--max-width Maximum output width Console width
--max-height Maximum output height Console height

Render Mode

Option Description
-a, --ascii Use classic ASCII characters (v2.x default)
-b, --blocks Use colored Unicode half-blocks
-B, --braille Use braille characters (DEFAULT)
-M, --matrix Use Matrix digital rain effect
--no-color Disable color output

Playback Control

Option Description Default
-s, --speed Playback speed multiplier 1.0
-l, --loop Loop count (0 = infinite) 0
-S, --status Show status line with progress OFF
--no-animate Show first frame only OFF
--dejitter Reduce color flickering in animations OFF

Video Options (requires FFmpeg)

Option Description Default
--start, --ss Start time in seconds 0
-t, --duration Duration to play Full video
--end End time in seconds Video end
-r, --fps Target framerate Video native
--frame-step Skip frames (2 = every 2nd) 1
--no-hw Disable hardware acceleration HW enabled
--ffmpeg-path Path to FFmpeg installation Auto-download

Raw Frame Extraction

Extract actual video/GIF frames without ASCII rendering. Supports multiple output formats:

Option Description Default
--raw Extract raw frames (no ASCII) OFF
--raw-width Output width in pixels 320
--raw-height Output height in pixels Auto
--smart-keyframes Use scene detection OFF
--scene-threshold Scene sensitivity (0.0-1.0) 0.4
-q, --quality Output quality 1-100 85

Supported output formats:

  • .gif - Animated GIF (default)
  • .webp - Animated WebP
  • .png, .jpg, .bmp - Image sequence (frame_001.png, etc.)
  • .mp4, .webm, .mkv, .avi, .mov - Re-encoded video
# Extract frames to GIF
consoleimage movie.mp4 --raw -o frames.gif

# Extract to animated WebP (better quality)
consoleimage movie.mp4 --raw -o frames.webp --quality 90

# Smart keyframe extraction (scene detection)
consoleimage movie.mp4 --raw --smart-keyframes -o scenes.gif --gif-frames 8

# Extract to image sequence
consoleimage movie.mp4 --raw -o frame.png --gif-frames 10

# Re-encode video clip
consoleimage movie.mp4 --raw -o clip.mp4 --ss 30 -t 5 --raw-width 480

GIF Output Options

Option Description Default
--gif-fps GIF framerate 10
--gif-colors Palette size (16-256) 64
--gif-font-size Font size in pixels 10
--gif-scale Scale factor 1.0

Image Adjustment

Option Description Default
--contrast Contrast power (1.0 = none) 2.5
--gamma Gamma correction (<1 brighter) 0.85
-a, --aspect-ratio Character aspect ratio 0.5
--colors Color palette size (4, 16, 256) Full

Calibration

# Show calibration pattern (should appear as circle)
consoleimage --calibrate

# Adjust until circle looks round
consoleimage --calibrate --aspect-ratio 0.48

# Save calibration for this mode
consoleimage --calibrate --aspect-ratio 0.48 --save

# Calibrate different modes separately
consoleimage --calibrate --blocks --aspect-ratio 0.5 --save
consoleimage --calibrate --braille --aspect-ratio 0.52 --save

Document Formats

Compressed (.cidz) - Recommended

  • GZip compressed with delta encoding
  • ~7:1 compression ratio vs raw JSON
  • Best for animations and videos
  • Supports playback speed override
consoleimage animation.gif -o output.cidz
consoleimage output.cidz --speed 1.5

JSON (.json)

  • Uncompressed, human-readable
  • Useful for debugging or small outputs
consoleimage image.png -o output.json

Streaming NDJSON (.ndjson)

  • JSON Lines format for long videos
  • Auto-finalizes on Ctrl+C
  • Frames written incrementally
consoleimage long_movie.mp4 -o movie.ndjson

FFmpeg - Zero Setup Required

FFmpeg is automatically downloaded on first video use:

$ consoleimage video.mp4
FFmpeg not found. Downloading...
Cache location: C:\Users\you\AppData\Local\consoleimage\ffmpeg

Downloading FFmpeg...                              75%

Custom FFmpeg Path

consoleimage video.mp4 --ffmpeg-path "C:\tools\ffmpeg\bin"

Manual Installation (Optional)

# Windows
winget install FFmpeg

# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

Examples

Create ASCII Art GIF from Video

# Basic conversion
consoleimage movie.mp4 -o output.gif -w 80

# Specific section with color blocks
consoleimage movie.mp4 -o clip.gif --ss 30 -t 10 --blocks

# Braille mode, slower playback
consoleimage movie.mp4 -o output.gif --braille --speed 0.5

Archive Video as Document

# Save video as compressed document
consoleimage movie.mp4 -o movie.cidz --blocks -w 100

# Play it back anytime without the original video
consoleimage movie.cidz

# Convert to GIF later
consoleimage movie.cidz -o movie.gif

Matrix Rain Effect

# Classic green matrix
consoleimage photo.png --matrix

# Red matrix
consoleimage photo.png --matrix --matrix-color red

# Full color from source image
consoleimage photo.png --matrix --matrix-fullcolor

Performance Tips

  1. Reduce resolution - Use -w 80 for faster rendering
  2. Skip frames - Use --frame-step 2 for videos on slow systems
  3. Use ColorBlocks - Faster than ASCII for similar quality
  4. Hardware acceleration - Enabled by default for videos

Troubleshooting

Choppy video playback

  • Try --no-hw to disable hardware acceleration
  • Reduce dimensions with -w 80 -h 40
  • Skip frames with --frame-step 2

Colors look wrong

  • Ensure terminal supports 24-bit color
  • Try --blocks mode for best color support

Video stretched/squashed

  • Run calibration: consoleimage --calibrate --save

cidz file won't load

  • Ensure it was created with a recent version
  • Try uncompressed JSON: -o output.json

License

This is free and unencumbered software released into the public domain. See UNLICENSE for details.