diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 259 |
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). |