Skip to content

hitvid v1.0.0

Choose a tag to compare

View all tags
@caokai674 caokai674 released this 30 May 08:50
· 91 commits to main since this release
1.0.0
84f5874

hitvid Terminal Video Player Summary

hitvid is a Bash script-based terminal video player that leverages ffmpeg to extract video frames and chafa to render them as ASCII art, enabling direct video playback within your terminal.

Key Features

  • In-Terminal Playback: Watch videos directly in your terminal window.
  • Multiple Rendering Options: Supports custom FPS, scaling modes, color counts, dithering algorithms, and character sets.
  • Two Playback Modes:
    • preload (Default): Extracts and converts all video frames into Chafa text frames before playback begins, offering the smoothest experience but with a longer initial processing time.
    • stream: Starts playback while converting frames in the background. This allows for quicker initiation but might cause stuttering if rendering can't keep up.
  • Parallel Processing: Utilizes multi-core CPUs to speed up frame rendering.
  • Loop Playback and Quiet Mode are supported.
  • Automatic Cleanup of temporary files upon script exit.

Dependencies

You'll need ffmpeg, chafa, and tput installed. nproc and xargs are recommended for optimized performance.

Usage

Run the script using ./hitvid.sh [VIDEO_PATH] [OPTIONS]. It supports both local video file paths and direct video URLs.

Core Workflow

  1. General Steps: Parses arguments, checks dependencies, sets up a temporary directory, retrieves video info, and extracts JPG video frames using ffmpeg.
  2. preload Mode: All JPG frames are rendered in parallel into Chafa text frames before playback starts.
  3. stream Mode: Background parallel rendering of Chafa text frames occurs simultaneously with playback; the player waits if a required frame isn't ready.
  4. Cleanup: A trap mechanism ensures automatic deletion of temporary files and restoration of terminal settings upon script exit.

Notes and Troubleshooting

  • Performance: High-resolution or high-bitrate videos may be choppy, and terminal rendering capabilities can be a bottleneck.
  • Terminal Compatibility: Best results are seen with terminals that support ANSI escape sequences well (e.g., gnome-terminal, konsole, iTerm2).
  • Font: Monospaced fonts generally provide better character art display.
  • Temporary Files: Ensure sufficient space in your /tmp directory.
  • --threads Option: Setting this to your CPU core count is usually optimal.
  • Stuttering in Stream Mode: Try lowering FPS, reducing colors, increasing threads, or switching to preload mode.
  • Errors: Verify that all dependencies are installed and in your PATH, and check for corrupted video files.
Assets 2
Loading