path: root/README.txt

VFETCH

neofetch but the ascii part is a video


DEPENDENCIES
============

Build Tools
-----------
* GNU Make
* C11-compliant compiler (a.k.a. ISO/IEC 9899:2011)
* pkg-config
* git

Libraries (Runtime & Development Headers)
-----------------------------------------
* chafa
* glib

Runtime Tools
-------------
* fastfetch or neofetch


COMPILE
=======

   git clone https://git.doan.luuduct.ai/vfetch
   cd vfetch
   make


SPECIFY A DIFFERENT COMPILER
----------------------------

By default, make attempts to find Clang or GCC. It fails otherwise.
If you want to use a different compiler (e.g., icc, tcc), specify
the CC variable and use fallback target:

   make fallback CC=<compiler>

where <compiler> is the C compiler of choice.

Note: Feel free to read and/or modify the Makefile for other useful targets.


USAGE
=====

After building, you can run the program:

   vfetch --file <video_path> <flags>


VIDEO FORMAT REQUIREMENTS
-------------------------

- Video Codec: MPEG-1
- Audio Codec: MPEG-1 Audio Layer II (MP2)
- Container:   MPEG-PS (.mpg, .mpeg)

Standard MP4, MKV, or MOV files will NOT work directly. You must convert them
accordingly (e.g. FFmpeg).


COMMAND REFERENCE
=================

--file <path>
    (Required) Specifies the path to the input video file to be animated.
    MUST be an MPEG-1 encoded file (see VIDEO FORMAT REQUIREMENTS section).

--help
    Provides help. All other commands will be ignored if --help is passed.

--size <W>x<H> or --size <W>
    Sets the dimensions of the animation output in character cells.
    Format:
      <W>: Automatically calculates the correct height to preserve the video's aspect ratio, based on the --cell-aspect.
      <W>x<H>: Forces the animation to specific dimensions, ignoring aspect ratio.
    Default: 80

--cell-aspect <value>
    Specifies the aspect ratio (Width / Height) of a single character cell in
    your terminal. This is used to calculate the correct image height when only
    the width is provided in --size.
    Most terminal fonts are twice as tall as they are wide. Therefore:
    Default: 0.50

--pad <X>:<Y> or --pad <int>
    Sets the positioning offset (padding) of the animation relative to the
    terminal's top-left corner.
    X (Horizontal): The number of spaces to indent from the left.
    Y (Vertical): The number of lines to push down from the top.
    Format:
      <X>:<Y>: Sets specific values (e.g., 10:5 shifts 10 spaces right and 5 lines down).
      <int>: Applies the same number to both X and Y (e.g., 5 becomes 5:5).
    Default: 4:2

--fps <value>
    Sets the target FPS for the animation.
    Accepts floating-point numbers with up to two decimal places (e.g., 23.97, 29.98).
    Cannot be higher than video's native FPS.
    Default: Source video's native FPS.

--refresh-rate <value>
    Sets the target refresh rate for the terminal animation in Hz.
    Default: 60
    Values: A positive integer from 1 to 65535
    NOTE: This controls the screen redraw rate, which is independent of the
    video's frame rate (--fps). A high refresh rate will not generate new video
    frames but can make the animation appear more fluid.

--audio
    Enables audio playback. The program extracts the audio track directly
    from the input video file.
    The audio codec MUST be MP2 (see VIDEO FORMAT REQUIREMENTS section).

--loop
    Enables infinite looping of the animation. If this flag is not provided,
    the program will play the video once and then exit automatically.

--fetch-tool <tool>
    Controls which system information utility is displayed on the side of the animation.
    Default Behavior: If not raised, the program will first try to use
    'fastfetch', falling back to 'neofetch' if it's not available.
    Values:
      fastfetch: Explicitly use fastfetch. The program will exit with an error
                 if it's not installed.
      neofetch:  Explicitly use neofetch. The program will exit with an error
                 if it's not installed.
      none:      Completely disables the system information display.

--verbose
    Enables verbose console output, showing high-level information about
    caching, command execution, and pipeline steps.
    By default, this output goes to stdout. If used with --debug, all verbose
    output is redirected to stderr.

--debug
    Enables highly detailed developer output to stderr for troubleshooting.
    This includes low-level details like worker thread activity and raw command
    outputs on failure.
    This flag also enables --verbose and forces all diagnostic output to stderr.

--format <mode>
    Sets the output format for rendering in the terminal. The fidelity and
    compatibility vary significantly.
    Default: symbols.
    Values:
      symbols: (Default) Renders using Unicode characters.
      sixels:  Renders a high-quality bitmap image.
               Requires a Sixel-compatible terminal (e.g., Xterm, WezTerm).
      kitty:   Renders a pixel-perfect image.
               Requires a Kitty-compatible terminal.
               Requires Chafa 1.8.0+
      iterm2:  Renders a pixel-perfect image.
               Requires an iTerm2-compatible terminal.
               Requires Chafa 1.8.0+

--colors <mode>
    Sets the color mode for the terminal output.
    Values:
      8:     Use the 8 standard ANSI colors.
             Requires Chafa 1.8.0+
      16/8:  A 16-color compatibility mode that maps to the 8 base colors.
             Requires Chafa 1.12.0+
      16:    Use the 16 standard ANSI colors.
      240:   Use a 240-color palette.
      256:   Use the full 256-color xterm palette.
      full:  Use 24-bit truecolor for the highest color fidelity.

--fg <RRGGBB>
    Sets a specific foreground color to be used for all characters. This is
    most effective in 2-color modes but can influence other modes. Color is
    specified as a 6-digit hex string.

--bg <RRGGBB>
    Sets a specific background color. This color will be blended with the
    video's background. Color is specified as a 6-digit hex string.

--fg-only
    Renders only the foreground characters, leaving the background of each
    character cell transparent. This allows the terminal's background color to
    show through.
    Requires Chafa 1.8.0+

--color-space <space>
    Specifies the color space to use for calculating color similarity, which
    affects color quantization.
    Values:
      rgb:    RGB color space.
      din99d: A perceptually uniform color space for better visual results.

--symbols <list>
    Controls the set of characters used to render the image.
    You can specify a preset or combine multiple classes with commas
    (e.g., --symbols "block,braille,stipple").

    Common Values:
      all:     Use all available symbols.
      ascii:   Restrict output to only the 7-bit ASCII character set.
      block:   Use all block-drawing characters (half, quad, sextant, etc.).
      braille: Use all 256 braille patterns.
      solid:   Use only solid block characters.
      stipple: Use stippled (shaded/dotted) characters.
      none:    Use no symbols.

    List of supported values:
      all, none, ascii, braille, space, solid, stipple, inverted,
      block, border, diagonal, dot, half, hhalf, vhalf, quad, sextant, wedge,
      alnum, alpha, digit, latin, wide,
      geometric, technical,
      ambiguous, bad, extra, imported, legacy, narrow, ugly

--fill <symbol-string>
    Fills transparent background areas with repeating characters from the
    provided string. This is not a class selector like --symbols.
    Any valid UTF-8 characters can be used.
    Example: --fill "·." will fill transparent areas with an alternating pattern
    of dots.


INTERACTIVE CONTROLS
====================

During video playback, these keybindings are available:

* 'q' or 'Q': Quit the program immediately.
* 'p' or 'P': Toggle Pause/Resume.


LICENSE
=======

SOURCE CODE
-----------

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

DEPENDENCIES
------------

* miniaudio - Licensed under the MIT No Attribution (SPDX: MIT-0).
* pl_mpeg - Licensed under the MIT License, also known as the Expat License (SPDX: MIT).
* chafa - Licensed under the GNU Lesser General Public License v3.0 or later (SPDX: LGPL-3.0-or-later).
* glib - Licensed under the GNU Lesser General Public License v2.1 or later (SPDX: LGPL-2.1-or-later).