14 KiB
Of course! Based on a thorough analysis of your entire codebase, here is a new, updated README.md that reflects the current features, commands, and architecture of FastAnime. It maintains the style of your previous README while ensuring all information is accurate and relevant.
FastAnime
Your browser anime experience, from the terminal.
Screenshots
Media Results Menu:Riced Preview Examples
Anilist Results Menu (FZF):
Episodes Menu with Preview (FZF):
No Image Preview Mode:
Desktop Notifications + Episodes Menu:
Installation
The app runs wherever Python 3.10+ is available. On Android, you can use Termux. For installation help, join our Discord.
Installation on NixOS
nix profile install github:Benexl/fastanime
Installation on Arch Linux
Install from the AUR using an AUR helper like yay or paru.
# Stable version (recommended)
yay -S fastanime
# Git version (latest commit)
yay -S fastanime-git
Recommended Installation (uv)
The recommended installation method is with uv, a fast Python package manager.
# Install with all optional features (recommended for the full experience)
uv tool install "fastanime[standard]"
# Stripped-down installations
uv tool install fastanime # Core functionality only
uv tool install "fastanime[download]" # For advanced downloading
uv tool install "fastanime[discord]" # For Discord Rich Presence
uv tool install "fastanime[notifications]" # For desktop notifications
Other Installation Methods
pipx or pip
Using pipx (Recommended for isolated environments)
pipx install "fastanime[standard]"
Using pip
pip install "fastanime[standard]"
Bleeding Edge & Building from Source
Installing the Bleeding Edge Version
Download the latest fastanime_debug_build artifact from the GitHub Actions page, then:
unzip fastanime_debug_build.zip
uv tool install fastanime-*.whl
Building from Source
Requirements: Git, Python 3.10+, and uv.
git clone https://github.com/Benexl/FastAnime.git --depth 1
cd FastAnime
uv tool install .
fastanime --version
Tip
Enable shell completions for a much better experience by running
fastanime completionsand following the on-screen instructions for your shell.
External Dependencies
For the best experience, install these external tools:
- Required for Streaming:
- mpv - The primary media player.
- Recommended for UI & Previews:
- fzf - For a powerful fuzzy-finder interface.
- chafa or kitty's icat - For image previews in the terminal.
- Recommended for Downloads & Features:
- ffmpeg - Required for downloading HLS streams.
- webtorrent-cli - For streaming torrents.
- syncplay - To watch anime together with friends.
- feh or kitty's icat - For the experimental manga mode.
Usage
FastAnime offers a rich interactive TUI for browsing and a powerful CLI for scripting and automation.
Global Options
Most options can be passed directly to the fastanime command to override your config for that session.
--provider <allanime|animepahe>: Choose the streaming site to use.--selector <fzf|rofi|default>: Choose the UI backend.--preview,--no-preview: Enable/disable image and info previews (requiresfzf).--dub,--sub: Set preferred translation type.--icons,--no-icons: Toggle UI icons.--log,--log-file: Enable logging to stdout or a file for debugging.--rich-traceback: Show detailed, formatted tracebacks on error.
Main Commands
fastanime anilist: The main entry point for the interactive TUI. Browse, search, and manage your lists.fastanime registry: Manage your local database of anime. Sync, search, backup, and restore.fastanime download: Scriptable command to download specific episodes.fastanime search: Scriptable command to find and stream episodes directly.fastanime config: Manage your configuration file.fastanime update: Update FastAnime to the latest version.fastanime queue: Add episodes to the background download queue.fastanime worker: Run the background worker for downloads and notifications.
Deep Dive: fastanime anilist (Interactive TUI)
This is the primary way to use FastAnime. Simply run fastanime anilist to launch a rich, interactive terminal experience. From here you can:
- Browse trending, popular, and seasonal anime.
- Manage your personal lists (Watching, Completed, etc.) after logging in with
fastanime anilist auth. - Search for any anime in the AniList database.
- View detailed information, characters, recommendations, reviews, and airing schedules.
- Stream or download episodes.
anilist search Subcommand
A powerful command to filter the AniList database directly from your terminal.
# Search for anime from 2024, sorted by popularity, that is releasing and not on your list
fastanime anilist search -y 2024 -s POPULARITY_DESC --status RELEASING --not-on-list
# Find the most popular movies with the "Fantasy" genre
fastanime anilist search -g Fantasy -f MOVIE -s POPULARITY_DESC
# Dump search results as JSON instead of launching the TUI
fastanime anilist search -t "Demon Slayer" --dump-json
anilist download Subcommand
Combines the power of anilist search with the download command, allowing you to batch-download based on filters.
# Download episodes 1-12 of all fantasy anime that aired in Winter 2024
fastanime anilist download --season WINTER -y 2024 -g Fantasy -r "0:12"
Deep Dive: fastanime registry (Local Database)
FastAnime maintains a local registry of your anime for offline access, enhanced performance, and powerful data management.
registry sync: Synchronize your local data with your remote AniList account.registry stats: Show detailed statistics about your viewing habits.registry search: Search your locally stored anime data.registry backup: Create a compressed backup of your entire registry.registry restore: Restore your data from a backup file.registry export/import: Export your data to JSON/CSV for use in other applications.
Scriptable Commands: download & search
These commands are designed for automation and quick access.
download Examples
# Download the latest 5 episodes of One Piece
fastanime download -t "One Piece" -r "-5"
# Download episodes 1 to 24, merge subtitles, and clean up original files
fastanime download -t "Jujutsu Kaisen" -r "0:24" --merge --clean
search (Binging) Examples
# Start binging an anime from the first episode
fastanime search -t "Attack on Titan" -r ":"
# Watch the latest episode directly
fastanime search -t "My Hero Academia" -r "-1"
MPV IPC Integration
When use_ipc is enabled, FastAnime provides powerful in-player controls without closing 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 betweendubandsub.
Script Messages (MPV Console)
script-message select-episode <number>: Jump to a specific episode.script-message select-server <name>: Switch to a different streaming server.
Configuration
FastAnime is highly customizable via its configuration file, located at ~/.config/fastanime/config.ini (path may vary by OS).
Run fastanime config --path to find the exact location on your system.
A default configuration file with detailed comments is created on first run. You can edit it with fastanime config or use the interactive wizard with fastanime config --interactive.
Default Configuration (`config.ini`)
[general]
# The preferred watch history tracker (local,remote) in cases of conflicts
preferred_tracker = local
# The pygment style to use
pygment_style = github-dark
# The spinner to use
preferred_spinner = smiley
# The media database API to use (e.g., 'anilist', 'jikan').
media_api = anilist
# The default anime provider to use for scraping.
provider = allanime
# The interactive selector tool to use for menus.
selector = fzf
# Automatically select the best-matching search result from a provider.
auto_select_anime_result = True
# Display emoji icons in the user interface.
icons = True
# Type of preview to display in selectors.
preview = full
# The command-line tool to use for rendering images in the terminal.
image_renderer = icat
# The external application to use for viewing manga pages.
manga_viewer = feh
# Automatically check for new versions of FastAnime on startup.
check_for_updates = True
# Enable caching of network requests to speed up subsequent operations.
cache_requests = True
# Maximum lifetime for a cached request in DD:HH:MM format.
max_cache_lifetime = 03:00:00
# Attempt to normalize provider titles to match AniList titles.
normalize_titles = True
# Enable Discord Rich Presence to show your current activity.
discord = False
# Number of recently watched anime to keep in history.
recent = 50
[stream]
# The media player to use for streaming.
player = mpv
# Preferred stream quality.
quality = 1080
# Preferred audio/subtitle language type.
translation_type = sub
# The default server to use from a provider. 'top' uses the first available.
server = TOP
# Automatically play the next episode when the current one finishes.
auto_next = False
# Automatically resume playback from the last known episode and position.
continue_from_watch_history = True
# Which watch history to prioritize: local file or remote AniList progress.
preferred_watch_history = local
# Automatically skip openings/endings if skip data is available.
auto_skip = False
# Percentage of an episode to watch before it's marked as complete.
episode_complete_at = 80
# The format selection string for yt-dlp.
ytdlp_format = best[height<=1080]/bestvideo[height<=1080]+bestaudio/best
# Prevent updating AniList progress to a lower episode number.
force_forward_tracking = True
# Default behavior for tracking progress on AniList.
default_media_list_tracking = prompt
# Preferred language code for subtitles (e.g., 'en', 'es').
sub_lang = eng
# Use IPC communication with the player for advanced features like episode navigation.
use_ipc = True
Contributing
Pull requests are highly welcome! Please read our Contributing Guidelines to get started with setting up a development environment and understanding our coding standards.
Disclaimer
Important
This project scrapes public-facing websites (
allanime,animepahe). The developer(s) of this application have no affiliation with these content providers. This application hosts zero content. Use at your own risk.