Viu

^{Your browser anime experience, from the terminal.}

viu-showcase.webm

RICED

main menu

anime preview menu

episode menu

Core Features

• 📺 Interactive TUI: Browse, search, and manage your AniList library in a rich terminal interface powered by fzf, rofi, or a built-in selector.
• ⚡ Powerful Search: Filter the entire AniList database with over 20 different criteria, including genres, tags, year, status, and score.
• 💾 Local Registry: Maintain a fast, local database of your anime for offline access, detailed stats, and robust data management.
• ⚙️ Background Downloader: Queue episodes for download and let a persistent background worker handle the rest.
• 📜 Scriptable CLI: Automate streaming and downloading with powerful, non-interactive commands perfect for scripting.
• 🔧 Highly Customizable: Tailor every aspect—from UI colors and providers to playback behavior—via a simple, well-documented configuration file.
• 🔌 Extensible Architecture: Easily add new providers, media players, and UI selectors to fit your workflow.

Installation

Viu runs on Windows, macOS, Linux, and Android (via Termux). Pre-built binaries are available for quick installation without Python, or you can install via Python 3.10+ package managers.

Prerequisites

For the best experience, please install these external tools:

• Required for Streaming:
  • mpv - The primary and recommended media player.
• Recommended for UI & Previews:
  • fzf - For the best fuzzy-finder interface.
  • chafa or kitty's icat - For image previews in the terminal.
• Recommended for Downloads & Advanced Features:
  • ffmpeg - Required for downloading HLS streams and merging subtitles.
  • webtorrent-cli - For streaming torrents directly.

Pre-built Binaries (Recommended for Quick Start)

The easiest way to get started is to download a pre-built, self-contained binary from the releases page. These binaries include all dependencies and do not require Python to be installed.

Available for:

• Linux (x86_64): viu-linux-x86_64
• Windows (x86_64): viu-windows-x86_64.exe
• macOS (Intel x86_64): viu-macos-x86_64
• macOS (Apple Silicon ARM64): viu-macos-arm64

Installation Steps:

1. Download the appropriate binary for your platform from the releases page.

2. Linux/macOS: Make it executable:

   # Replace with the actual binary name you downloaded
   chmod +x viu-linux-x86_64
   

   Then move it to a directory in your PATH:

   # Option 1: System-wide installation (requires sudo)
   sudo mv viu-linux-x86_64 /usr/local/bin/viu
   
   # Option 2: User directory installation
   mkdir -p ~/.local/bin
   mv viu-linux-x86_64 ~/.local/bin/viu
   # Make sure ~/.local/bin is in your PATH
   

   Windows: Simply rename viu-windows-x86_64.exe to viu.exe and place it in a directory in your PATH, or run it directly.

3. Verify the installation:

   viu --version
   

Recommended Installation (uv)

The best way to install Viu is with uv, a lightning-fast Python package manager.

# Install with all optional features for the full experience
uv tool install "viu-media[standard]"

# Or, pick and choose the extras you need:
uv tool install viu-media  # Core functionality only
uv tool install "viu-media[download]"  # For advanced downloading with yt-dlp
uv tool install "viu-media[discord]"   # For Discord Rich Presence
uv tool install "viu-media[notifications]" # For desktop notifications

Other Installation Methods

nix run github:viu-media/viu

nix profile install github:viu-media/viu

viu.url = "github:viu-media/viu";

inputs.viu.packages.${pkgs.system}.default

# Stable version (recommended)
yay -S viu-media

# Git version (latest commit)
yay -S viu-media-git

# Recommended (with pip due to more control)
pkg install python
pkg install rust # required cause of pydantic

# NOTE: order matters

# get pydantic from the termux user repository
pip install pydantic --extra-index-url https://termux-user-repository.github.io/pypi/

# the above will take a while if you want to see more output and feel like sth is happening lol
pip install pydantic --extra-index-url https://termux-user-repository.github.io/pypi/ -v

# now you can install viu
pip install viu-media

# === optional deps ===
# if you have reach here awesome lol :)

# yt-dlp for downloading m3u8 and hls streams
pip install yt-dlp[default,curl-cffi]

# you may also need ffmpeg for processing the videos
pkg install ffmpeg

# tip if you also want yt functionality
pip install yt-dlp-ejs

# you require js runtime
# eg the recommended one
pkg install deno

# for faster fuzzy search
pip install thefuzz

# if you want faster scraping, though barely noticeable lol
pip install lxml --extra-index-url https://termux-user-repository.github.io/pypi/

# if compilation fails you need to have
pkg install libxml2 libxslt

# == ui setup ==
pkg install fzf

# then enable fzf in the config
viu --selector fzf config --update

# if you want previews as well specify preview option
# though images arent that pretty lol, so you can stick to text over full
viu --preview text config --update

# if you set preview to full you need a terminal image renderer
pkg install chafa

# == player setup ==
# for this you need to strictly install from playstore
# search for mpv or vlc (recommended, since has nicer ui)
# the only limitation is currently its not possible to pass headers to the android players
# through android intents
# so use servers like sharepoint and wixmp
# though this is not an issue when it comes to downloading ;)
# if you have installed using 'pkg' uninstall it

# okey now you are all set, i promise the hussle is worth it lol :)
# posted a video of it working to motivate you
# note i recorded it from waydroid which is android for linux sought of like an emulator(bluestacks for example)

pipx install "viu-media[standard]"

pip install "viu-media[standard]"

git clone https://github.com/viu-media/Viu.git --depth 1
cd Viu
uv tool install .
viu --version

Getting Started: Quick Start

Get up and running in three simple steps:

1. Authenticate with AniList:

   viu anilist auth
   

   This will open your browser. Authorize the app and paste the obtained token back into the terminal. Alternatively, you can pass the token directly as an argument, or provide a path to a text file containing the token.

2. Launch the Interactive TUI:

   viu anilist
   

3. Browse & Play: Use your arrow keys to navigate the menus, select an anime, and choose an episode to stream instantly.

Usage Guide

The Interactive TUI (viu anilist)

This is the main, user-friendly way to use Viu. It provides a rich terminal experience where you can:

• Browse trending, popular, and seasonal anime.
• Manage your personal lists (Watching, Completed, Paused, etc.).
• Search for any anime in the AniList database.
• View detailed information, characters, recommendations, reviews, and airing schedules.
• Stream or download episodes directly from the menus.

Powerful Searching (viu anilist search)

Filter the entire AniList database with powerful command-line flags.

# Search for anime from 2024, sorted by popularity, that is releasing and not on your list
viu anilist search -y 2024 -s POPULARITY_DESC --status RELEASING --not-on-list

# Find the most popular movies with the "Fantasy" genre
viu anilist search -g Fantasy -f MOVIE -s POPULARITY_DESC

# Dump search results as JSON instead of launching the TUI
viu anilist search -t "Demon Slayer" --dump-json

Background Downloads (viu queue & worker)

Viu includes a robust background downloading system.

1. Add episodes to the queue:

   # Add episodes 1-12 of Jujutsu Kaisen to the download queue
   viu queue add -t "Jujutsu Kaisen" -r "0:12"
   

2. Start the worker process:

   # Run the worker in the foreground (press Ctrl+C to stop)
   viu worker
   
   # Or run it as a background process
   viu worker &
   ```The worker will now process the queue, download your episodes, and check for notifications.
   

Scriptable Commands (download & search)

These commands are designed for automation and quick, non-interactive tasks.

download Examples

# Download the latest 5 episodes of One Piece
viu download -t "One Piece" -r "-5"

# Download episodes 1 to 24, merge subtitles, and clean up original files
viu download -t "Jujutsu Kaisen" -r "0:24" --merge --clean

search (Binging) Examples

# Start binging an anime from the first episode
viu search -t "Attack on Titan" -r ":"

# Watch the latest episode directly
viu search -t "My Hero Academia" -r "-1"

Local Data Management (viu registry)

Viu maintains a local database of your anime for offline access and enhanced performance.

• registry sync: Synchronize your local data with your remote AniList account.
• registry stats: Show detailed statistics about your viewing habits.
• registry backup: Create a compressed backup of your entire registry.
• registry restore: Restore your data from a backup file.
• registry export/import: Export/import your data to JSON/CSV for use in other applications.
• registry clean: Clean up orphaned or invalid entries from your local database.

Configuration

Viu is highly customizable. A default configuration file with detailed comments is created on the first run.

• Find your config file: viu config --path
• Edit in your default editor: viu config
• Use the interactive wizard: viu config --interactive

Most settings in the config file can be temporarily overridden with command-line flags (e.g., viu --provider animepahe anilist).

# [general] Section: Controls overall application behavior.
[general]
provider = allanime          ; The default anime provider (allanime, animepahe).
selector = fzf               ; The interactive UI tool (fzf, rofi, default).
preview = full               ; Preview type in selectors (full, text, image, none).
image_renderer = icat        ; Tool for terminal image previews (icat, chafa).
icons = True                 ; Display emoji icons in the UI.
auto_select_anime_result = True ; Automatically select the best search match.
...

# [stream] Section: Controls playback and streaming.
[stream]
player = mpv                 ; The media player to use (mpv, vlc).
quality = 1080               ; Preferred stream quality (1080, 720, 480, 360).
translation_type = sub       ; Preferred audio/subtitle type (sub, dub).
auto_next = False            ; Automatically play the next episode.
continue_from_watch_history = True ; Resume playback from where you left off.
use_ipc = True               ; Enable in-player controls via MPV's IPC.
...

# [downloads] Section: Controls the downloader.
[downloads]
downloader = auto            ; Downloader to use (auto, default, yt-dlp).
downloads_dir = ...          ; Directory to save downloaded anime.
max_concurrent_downloads = 3 ; Number of parallel downloads in the worker.
merge_subtitles = True       ; Automatically merge subtitles into the video file.
cleanup_after_merge = True   ; Delete original files after merging.
...

# [worker] Section: Controls the background worker process.
[worker]
enabled = True
notification_check_interval = 15 ; How often to check for new episodes (minutes).
download_check_interval = 5      ; How often to process the download queue (minutes).
...

Advanced Features

MPV IPC Integration

When use_ipc = True is set in your config, Viu provides powerful in-player controls without needing to close MPV.

Key Bindings:

• Shift+N: Play the next episode.
• Shift+P: Play the previous episode.
• Shift+R: Reload the current episode.
• Shift+A: Toggle auto-play for the next episode.
• Shift+T: Toggle between dub and sub.

Script Messages (For MPV Console):

• script-message select-episode <number>: Jump to a specific episode.
• script-message select-server <name>: Switch to a different streaming server.

Running as a Service (Linux/systemd)

You can run the background worker as a systemd service for persistence.

1. Create a service file at ~/.config/systemd/user/viu-worker.service:

   [Unit]
   Description=Viu Background Worker
   After=network-online.target
   
   [Service]
   Type=simple
   ExecStart=/path/to/your/viu worker --log
   Restart=always
   RestartSec=30
   
   [Install]
   WantedBy=default.target
   

   Replace /path/to/your/viu with the output of which viu.

2. Enable and start the service:

   systemctl --user daemon-reload
   systemctl --user enable --now viu-worker.service
   

Project using it

Inazuma - official gui wrapper over viu built in kivymd

Contributing

Contributions are welcome! Whether it's reporting a bug, proposing a feature, or writing code, your help is appreciated. Please read our Contributing Guidelines to get started.