anifetch-cli 1.0.1
Animated terminal fetch with video and audio support.
License: MIT
Requires Python: >=3.11
Keywords: fetch, terminal, cli, animated, neofetch, fastfetch, anifetch

![anifetch](https://github.com/Notenlish/anifetch/blob/main/docs/anifetch.webp?raw=true)

# Anifetch - Neofetch but animated.

This is a small tool built with fastfetch/neofetch, ffmpeg and chafa. It allows you to use fastfetch or neofetch while having animations.

## Installation

### Installation for Linux

Recommended Python version: 3.11 and later. If you use NixOS refer to [Installation for NixOS](#installation-for-nixos).

Run this in the terminal.

```bash
curl https://raw.githubusercontent.com/Notenlish/anifetch/refs/heads/main/install.sh | bash
```

After installation, run this to test if anifetch was installed correctly:

```bash
anifetch example.mp4
```

Please read our [User guide](#user-guide) for more info on how to use anifetch.

---

### Installation for Windows (Winget or Scoop)

Check whether you have winget installed by running `winget` in the windows terminal. If you dont have it, install it [here](https://github.com/microsoft/winget-cli/?tab=readme-ov-file#installing-the-client). If you want, you can use [Scoop](https://scoop.sh/) instead. Just replace the `winget` part with `scoop`.

Run this in the terminal after verifying winget works:

```
winget install chafa ffmpeg fastfetch
```

You can install neofetch too but it is deprecated and not recommended. Run this to install: `winget install neofetch`

After installing the necessary dependencies using winget/scoop, install anifetch via pip. You can install it via pipx too.

```pip install anifetch-cli```

> [!WARNING]
> **Do not** install `anifetch` on pypi, it is not related with this project. Install `anifetch-cli`.

### Installation for MacOS with Homebrew

Install homebrew if you haven't installed it already by following the guide [here](https://brew.sh/).

Run this in the terminal after verifying homebrew is installed:

```
brew install chafa ffmpeg fastfetch
```

After installing the necessary dependencies, install anifetch via pip . You can install it via pipx too.

```pip install anifetch-cli```

> [!WARNING]
> **Do not** install `anifetch` on pypi, it is not related with this project. Install `anifetch-cli`.

### Manual Installation

You need the following tools installed on your system:

- `chafa`

  - Debian/Ubuntu: `sudo apt install chafa`
  - [Other distros – Download Instructions](https://hpjansson.org/chafa/download/)

- `ffmpeg` (for video/audio playback)

  - Debian/Ubuntu: `sudo apt install ffmpeg`
  - [Other systems – Download](https://www.ffmpeg.org/download.html)

- `fastfetch / neofetch` (Fastfetch is recommended)

  - Debian/Ubuntu: `sudo apt install fastfetch`
  - [Other systems - Instructions for Fastfetch](https://github.com/fastfetch-cli/fastfetch?tab=readme-ov-file#installation)
  - Neofetch installation _(Not recommended)_ can be found [here](https://github.com/dylanaraps/neofetch/wiki/Installation)

🔧 Make sure `pipx` is installed:

```bash
sudo apt install pipx
pipx ensurepath
```

and then:

```bash
pipx install git+https://github.com/Notenlish/anifetch.git
```

This installs `anifetch` in an isolated environment, keeping your system Python clean.
You can then run the `anifetch` command directly in your terminal.

Since pipx installs packages in an isolated environment, you won't have to worry about dependency conflicts or polluting your global python environment. `anifetch` will behave just like a native cli tool. You can upgrade your installation with `pipx upgrade anifetch`


---

### Installation for NixOS
#### ❄️ As a flake:
Add the anifetch repo as a flake input:

```nix
{
    inputs = {
        anifetch = {
            url = "github:Notenlish/anifetch";
            inputs.nixpkgs.follows = "nixpkgs";
        };
    };
}
```

Remember to add:

```nix
    specialArgs = {inherit inputs;};
```

to your nixos configuration, like I've done here on my system:

```nix
    nixosConfigurations = {
      Enlil = nixpkgs.lib.nixosSystem {
        specialArgs = {inherit inputs outputs;};
```

#### ❄️ As a package:

Add anifetch to your packages list like so:

```nix
{inputs, pkgs, ...}: {
    environment.systemPackages = with pkgs; [
        inputs.anifetch.packages.${pkgs.system}.default
        fastfetch # Choose either fastfetch or neofetch to run anifetch with
        neofetch
    ];
}
```

#### ❄️ As an overlay:

Add the overlay to nixpkgs overlays, then add the package to your package list as you would a package from the normal nixpkgs repo.

```nix
{inputs, pkgs, ...}: {
    nixpkgs = {
        overlays = [
            inputs.anifetch.overlays.anifetch
        ];
    };

    environment.systemPackages = with pkgs; [
        anifetch
        fastfetch # Choose either fastfetch or neofetch to run anifetch with
        neofetch
    ];
}
```

The Nix package contains all the dependencies in a wrapper script for the application aside from fastfetch or neofetch, so you should only need to add one of those to your package list as well.

After you've done these steps, rebuild your system.

---

### Developer Installation (for contributors):

```bash
git clone https://github.com/Notenlish/anifetch.git
cd anifetch
python3 -m venv venv
source venv/bin/activate
pip install -e .
```
> on windows do this to activate the venv instead: `venv\Scripts\activate`. Also on windows you should use `py` instead of `python3`.


This installs `anifetch` in editable mode within a local virtual environment for development.

You can then run the program in two ways:

- As a CLI: `anifetch`
- Or as a module: `python3 -m anifetch` (useful for debugging or internal testing)

> Please avoid using `pip install` outside a virtual environment on Linux. This is restricted by [PEP 668](https://peps.python.org/pep-0668/) to protect the system Python.

On Nix you can run:

```bash
nix develop
pip install -e .
```

inside the anifetch dir after cloning the repo. This creates a python venv you can re-enter by running `nix develop` inside the project dir.

## User Guide

You don't need to configure anything for `fastfetch` or `neofetch`. If they already work on your machine, `anifetch` will detect and use them automatically. Please note that at least one of these must be installed, otherwise anifetch won't work. **By default, `anifetch` will use fastfetch**. 

> We dont recommend using neofetch as it is archived. **To use neofetch**, you must append `-nf` to the anifetch command. For some distros you may need to append `--force` to the command too since neofetch is deprecated.

Simply `cd` to the directory your video file is located in and do `anifetch [path_to_video_file]`. Both relative and absolute paths are supported. Anifetch is packaged with an `example.mp4` video by default. You can use that to test anifetch.

Any video file you give to anifetch will be stored in `~/.local/share/anifetch/assets` folder for linux and `C:\\Users\\[Username]\\AppData\\Local\\anifetch\\anifetch\\assets` folder for windows. After running `anifetch` with this video file once, next time you use anifetch, you will be able to use that same video file in any location by just using its filename, since the video file has been saved in `assets`.

### Example usage:

```bash
anifetch video.mp4 -W 40 -H 20 -ca "--symbols wide --fg-only"
```

_Note : by default, the video `example.mp4` can directly be used as an example._

### Optional arguments:

- `-s` / `--sound`: Plays sound along with the video. If you provide a sound file, it will use it, otherwise will use ffmpg to extract audio from the video.
- `-r` / `--framerate`: Framerate to use when extracting frames from ffmpeg.
- `-W` / `--width`: video width
- `-H` / `--height`: video height (may be automatically fixed with the width)
- `-ca` / `--chafa-arguments`: extra arguments to pass to `chafa`. For an example, try adding this: `-ca "--symbols wide --fg-only"` this makes the output use Japanese characters.
- `-C` / `--center`: centers the terminal animation vertically
- `--cleanup`: Clears the screen on program exit.
- `-nf` / `--neofetch`: uses `neofetch` instead of `fastfetch`
- `-fr` / `--force-render`: Forcefully re-renders the animation while not caring about the cache. Useful if the cache is broken or the contents of the video file has changed.
- `-i` / `--interval`: Use this to make anifetch update the fetch information over time, sets fetch refresh interval in seconds. Default is -1(never). 
- `-b` / `--benchmark`: For testing, prints how long it took to process in seconds.
- `--force`: Add this argument if you want to use neofetch even if it is deprecated on your system.
- `--chroma`: Add this argument to chromakey a hexadecimal color from the video using ffmpeg. Syntax: '--chroma \<hex-color>:\<similiarity>:\<blend>'
- `--quality`: Changes the output quality of ffmpeg when extracting frames. This doesn't have much effect on the quality or speed from my testing, so you shouldn't need to change this. 2 highest quality, 10 lowest quality.
- `--loop`: Determines how many times the animation should loop. Default is -1(always loop).
- `--no-key-exit`: Don't exit anifetch when user presses a key.

### Cached files:

Anifetch automatically caches rendered animations to speed up future runs. Each unique combination of video and render options generates a cache stored in `~/.local/share/anifetch/`, organized by hash. This includes frames, output, and audio.

Cache-related commands:

`anifetch --cache-list` — View all cached configurations and orders them.

`anifetch --cache-delete <number>` — Delete a specific cache.

`anifetch --clear` — Delete all cached files.

Note that modifying the content of a video file but keeping the same name makes Anifetch still use the old cache. In that case, use `--force-render` or `-fr` to bypass the cache and generate a new version.

For full help:

```bash
anifetch --help
```

### Auto start on terminal start.

Add this to the end of `.bashrc`:

```bash
anifetch [video_file] [other_args_if_needed]
```


## Customizing Fastfetch/Neofetch output

For customizing fastfetch/neofetch output, you can check out these pages:
- [Fastfetch Customization](https://github.com/fastfetch-cli/fastfetch/wiki/Configuration)
- [Neofetch Customization](https://github.com/dylanaraps/neofetch/wiki/Customizing-Info)


## 📊 Benchmarks

Here's the benchmark from running each cli 10 times. Tested on Windows 11 with Intel I5-12500H processor.

| CLI                            | Time Taken(total) | Time Taken (avg) |
| ------------------------------ | ----------------- | ---------------- |
| fastfetch                      | 0.27 seconds      | 0.03 seconds     |
| anifetch (nocache) (fastfetch) | 20.18 seconds     | 2.02 seconds     |
| anifetch (cached) (fastfetch)  | 0.78 seconds      | 0.08 seconds     |

As it can be seen, Anifetch is quite fast if you cache the animations.

## Troubleshooting

Make sure to install the dependencies listed on [Prerequisites](#Prerequisites). If ffmpeg throws an error saying `libxm12.so.16: cannot open shared object file: No such file or directory exists` then you must install `libxm12`. Here's an comment showing how to install it for arch: [https://github.com/Notenlish/anifetch/issues/24#issuecomment-2920189918](solution)

If weird characters are appearing in your terminal then your terminals font probably can't render some characters. Consider installling [nerdfonts](https://www.nerdfonts.com/).

## Notes

Anifetch attempts to cache the animation so that it doesn't need to render them again when you run it with the same file. However, if the name of the file is the same, but it's contents has changed, it won't re-render it. In that case, you will need to add `--force-render` as an argument to `anifetch.py` so that it re-renders it. You only have to do this only once when you change the file contents.

Also, ffmpeg can generate the the same image for 2 consecutive frames, which may make it appear like it's stuttering. Try changing the framerate if that happens. Or just increase the playback rate.

Currently only the `symbols` format of chafa is supported, formats like kitty, iterm etc. are not supported. If you try to tell chafa to use iterm, kitty etc. it will just override your format with `symbols` mode.

## What's Next

- [ ] Support different formats like iterm, kitty, sixel etc.

- [ ] Allow the user to provide their own premade frames in a folder instead of an video.

- [ ] Update the animated logo on the readme so that its resolution is smaller + each individual symbol is bigger.

## Dev commands

Devs can use additional tools in the `tools` folder in order to test new features from Anifetch.

## Credits

Neofetch: [Neofetch](https://github.com/dylanaraps/neofetch)

Fastfetch: [Fastfetch](https://github.com/fastfetch-cli/fastfetch)

I got the inspiration for Anifetch from Pewdiepie's Linux video. [Video](https://youtu.be/pVI_smLgTY0?t=879)

I dont remember where I got the example.mp4 video from, if you know the source or license please open an issue. If you are the license owner and want this video removed please open an issue and I will remove it.

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=Notenlish/anifetch&type=Date)](https://www.star-history.com/#Notenlish/anifetch&Date)