axol8002/hoopoe-player

What changed

Bug fixes

Audio/video desync after pause/resume [#2] ⚠️ experimental

Previously, resuming from pause restarted audio from the beginning regardless of the current position. Now audio restarts with -ss <offset> pointing exactly to the current frame timestamp, and the sync clock resets at the same instant.

# Before: resume at 01:30 → audio rewinds to 00:00
# After:  resume at 01:30 → audio seeks to 01:30

Note: the fix works correctly in most cases but may still drift on long videos or slow network streams. Further tuning is planned.

Terminal does not rescale while paused [#3]

The pause loop now checks terminal dimensions on every tick. If the size changed, the last frame is re-rendered immediately at the new width/height.

New features

--sync flag — opt-in A/V frame dropping ⚠️ experimental

Without --sync, every frame is rendered with a simple sleep(1/fps) budget — smooth playback, no dropped frames, but can drift from audio over time.

With --sync, a monotonic clock tracks the expected frame number at each moment. If rendering falls behind, frames are skipped to catch up. If it's ahead, it waits precisely.

# Smooth (default) — renders every frame, may drift from audio
hoopoe -s https://www.youtube.com/watch?v=xxxxx

# Synced — drops frames when slow, stays locked to audio
hoopoe -s --sync https://www.youtube.com/watch?v=xxxxx

The HUD shows 🔗SYNC when active. Note: on slower machines the frame-drop logic can be aggressive and skip too many frames at once. This will be tuned in a future release.

Real-time FPS counter in HUD

--hud now shows the actual render FPS as a rolling average over the last 30 frames, making it easy to see how hard your terminal is working.

▶ PLAY  01:23/04:56  23.4fps  [invert] 🔊50% 🔗SYNC

Screenshot to file (P)

Press P at any moment to save the current frame as a timestamped .ans file with full ANSI color codes. A confirmation appears in the HUD for 3 seconds.

# View the saved screenshot
cat hoopoe_screenshot_20260317_142301.ans

# Preserve colors when piping or if cat strips escapes
less -R hoopoe_screenshot_20260317_142301.ans

Loop mode (--loop)

Video and audio both restart automatically from the beginning when the video ends.

hoopoe --loop -s https://www.youtube.com/watch?v=xxxxx

⚠️ Known issues

Audio does not play on live streams [#1]

Partial progress was made: is_live is now detected from yt-dlp metadata, the HUD shows LIVE, and ffplay is launched with low-latency flags (-fflags nobuffer -flags low_delay). However, audio still fails to start for most HLS/DASH live URLs. Video renders correctly. Fix ongoing.

Upgrade

pip install --upgrade hoopoe-player