Initial commitmain

1 files changed, 259 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..4701df8
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,259 @@
+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).