axol8002/hoopoe-player

What's Changed

New features

--legacy-color — 16-color ANSI palette for terminals without true color support

Terminals that don't support 24-bit RGB can now render with a standard 16-color palette. Two mapping modes are available:

hoopoe --legacy-color https://www.youtube.com/watch?v=xxxxx        # RGB distance (fast, default)
hoopoe --legacy-color lab https://www.youtube.com/watch?v=xxxxx    # CIE LAB distance (perceptual)

Works with any character mode and --highlight. The HUD shows LEGACY-RGB or LEGACY-LAB when active.

--no-color — disable all color output

Replaces the former -m nocolor mode. Now works independently of the character mode — any -m can be combined with --no-color.

hoopoe --no-color -m braille https://www.youtube.com/watch?v=xxxxx

Breaking change: -m nocolor has been removed. Use --no-color instead.

Image rendering (-i) — by @dinikai in https://github.com/axol8002/hoopoe-player/pull/6

Render a local image as ASCII art directly in the terminal.

hoopoe -i photo.jpg
hoopoe -i --highlight -m braille photo.png

Output to file (--output)

Save the full render as an ANSI .ans file instead of single screenshots. Accepts a file path or a directory.

hoopoe --output render.ans https://www.youtube.com/watch?v=xxxxx
hoopoe --webcam --output ~/recordings/
hoopoe -i --output render.ans photo.jpg

ANSI playback (--play)

Replay a previously recorded .ans file at the original framerate. Supports pause and FPS override.

hoopoe --play render.ans
hoopoe --play --fps 5 render.ans

TUI launcher (tui/hoopoe-tui) — by @landnthrn in https://github.com/axol8002/hoopoe-player/pull/11

Interactive Bash menu for running hoopoe without memorizing CLI flags. Stores your preferences in ~/.config/hoopoe-launcher.conf.

chmod +x tui/hoopoe-tui
./tui/hoopoe-tui

Broader URL support

Twitch, Vimeo, direct video URLs (.mp4, .webm, .m3u8), and any of the 1800+ sites supported by yt-dlp work out of the box — no flags needed.

hoopoe https://www.twitch.tv/videos/xxxxxxxxx
hoopoe https://vimeo.com/xxxxxxxxx
hoopoe https://example.com/video.mp4

Bug fixes

--fps now rejects 0 and negative values

Previously, passing --fps 0 or --fps -5 would silently misbehave. It now exits immediately with a clear error message.

New Contributors

• @landnthrn made their first contribution in https://github.com/axol8002/hoopoe-player/pull/11

Full Changelog: https://github.com/axol8002/hoopoe-player/blob/main/CHANGELOG.md