see

README

See

Terminal-first media viewer that decodes anything ffmpeg understands and plays it right inside your shell. See converts frames to Unicode cells using tcell, streams raw pixels when your terminal supports inline graphics, and pushes audio through malgo.

Features

• Multiple render modes – one[1x1], half[1x2], quarter[2x2], full[4x8], gray/color mixes, with palette tricks to squeeze more detail into braille/half-block cells.
• Inline “super” mode – for iTerm2, Kitty, WezTerm, Ghostty… frames are sent as OSC 1337 (kitty-compatible) images instead of text.
• Audio playback & visualization – PCM S16 output plus waveform rendering when you feed an audio-only file.
• Responsive controls – space to pause/resume, arrows to seek ±15 s, works in ASCII + inline modes.
• Perf logging – render/draw/demux stats every second to help tune terminals or ffmpeg filters.

Requirements

• Go 1.24+ with CGO_ENABLED=1.
• ffmpeg available in PATH.
• A C toolchain (Xcode Command Line Tools, GCC, etc.) so cgo can build malgo.
• Optional: a supported audio device (miniaudio handles the backends).

Install (manual)

1. Download an archive from Releases.
2. Untar it: tar xzf see-linux-amd64.tar.gz.
3. Drop see/see.exe somewhere on your PATH.

Install via script

curl -fsSL https://raw.githubusercontent.com/svanichkin/see/main/scripts/install-release.sh | bash
# or
wget -qO- https://raw.githubusercontent.com/svanichkin/see/main/scripts/install-release.sh | bash

The script detects OS/arch, grabs the latest release, and installs to:

• $HOME/.local/bin for non-root macOS/Linux/BSD users (otherwise /usr/local/bin)
• %USERPROFILE%\AppData\Local\Programs\see on Windows/MSYS shells

Override the target with INSTALL_DIR=/custom ./scripts/install-release.sh, pin a specific version using VERSION=v0.2.0, or fetch from another fork via REPO=myuser/see.

Install via Go

Linux / macOS:

CGO_ENABLED=1 go install github.com/svanichkin/see@latest
~/go/bin/see clip.mp4

Windows (PowerShell):

$env:CGO_ENABLED = "1"
go install github.com/svanichkin/see@latest
C:\Users\YOU\go\bin\see.exe demo.gif

Build from source

git clone https://github.com/svanichkin/see.git
cd see
make                   # builds into bin/see
CGO_ENABLED=1 go run . 1.mp4

Usage

see <media-file> [extra ffmpeg args]
see demo.gif -cols 160 -rows 80 -fullcolor
see clip.mp4 -super                          # inline graphics
see song.mp3 -filter_complex "showwaves=s=640x360:mode=line"

When no mode is specified, fullcolor is used. Extra CLI tokens after the file are passed to ffmpeg, so you can attach -filter_complex, -stream_loop, etc.

Controls

• Space – pause / resume
• ← / → – seek backward / forward 15 seconds
• q, Esc, Ctrl+C – quit

Flags & shortcuts

• -cols, -rows – ASCII canvas size
• -super – enable inline renderer (falls back to ASCII if unsupported)
• -version – print build version
• -support – print GitHub link
• -donate – show donation address
• Mode shortcuts: -one, -half, -quarter, -full, -onegray, -halfgray, -quartergray, -onecolor, -halfcolor, -quartercolor, -fullgray, -fullcolor. Bare tokens like one, fullcolor also switch modes.

Still images, gifs/webp, and audio inputs loop forever. Inline mode currently encodes JPEG frames for speed; ASCII mode keeps a diff cache to minimize writes.

Support & Donate

• GitHub: https://github.com/svanichkin/see (see -support)
• Monero: 41uoDd1PNKm7j4LaBHHZ77ZPbEwEJzaRHhjEqFtKLZeWjd4sNfs3mtpbw1mcQrnNLBKWSJgui9ELEUz217Ui6kF13SmF4t5 (see -donate)

License

MIT – see LICENSE.