Skip to main content

About

Welcome to anisama, a Python CLI to browse, watch, and download anime from multiple sources (VOSTFR/VF).

  • Inspired by ani-cli, the original shell-based anime streaming tool.
  • Scrapes 7 sources: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime.
  • Interactive TUI built with Rich and Questionary.
  • Connects to the anisama API for fast search and video resolution.

PyPI version PyPI downloads Tests status Python version

Project Structure

anisama/
├── src/                       # Library package (installed as `anisama`)
│   ├── __init__.py            # Version and top-level exports
│   ├── config.py              # Constants, headers, domains, paths
│   ├── cache.py               # Catalog CRUD, multi-source merge
│   ├── search.py              # Fuzzy search (rapidfuzz)
│   ├── http_client.py         # Shared httpx.Client singleton (HTTP/2)
│   ├── resolver.py            # Video URL resolution per host
│   ├── sources.py             # Source registry + unified API
│   ├── exceptions.py          # Custom exceptions
│   ├── scraper/               # Per-source scrapers
│   │   ├── base.py            # Shared helpers, domain discovery
│   │   ├── anime_sama.py      # Anime-Sama scraper
│   │   ├── voiranime.py       # Voiranime scraper
│   │   ├── myfluneo.py        # MyFluneo scraper (Playwright)
│   │   ├── animesultra.py     # AnimesUltra scraper
│   │   ├── frenchanime.py     # FrenchAnime scraper
│   │   ├── animoflix.py       # AnimoFlix scraper (Playwright)
│   │   └── franime.py         # Franime scraper (API-based)
│   └── cli/                   # CLI-specific code
│       ├── app.py             # Entry point, click command
│       ├── display.py         # Banner, colors, info panels
│       ├── workflow.py        # Main workflow (search, play, download)
│       ├── picker.py          # Selection menus
│       ├── player.py          # Player detection, play/download
│       ├── mirror.py          # Speed tests, mirror resolution
│       ├── install.py         # yt-dlp/ffmpeg install guides
│       ├── settings.py        # Settings menu
│       └── api_client.py      # Remote anisama API client
├── data/                      # Local catalog/settings storage
├── tests/                     # Pytest suite
└── pyproject.toml

Features

  • Search anime by title with fuzzy matching (rapidfuzz) across 7 sources
  • Multi-source merge: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime
  • Intelligent dedup: season/lang variants grouped under one result
  • Smart search: exact match shows only relevant results, broad queries show variants
  • Browse seasons (VOSTFR / VF)
  • Stream episodes in your preferred video player
  • Download episodes directly
  • Episode range support (1-5 or 1,3,5)
  • Multiple video mirrors with automatic speed-tested fallback
  • Player support: mpv, VLC, IINA, MoonPlayer, ImPlay
  • API-first resolve with local fallback
  • "Continue watching" history menu
  • AniList-powered info panel (score, status, episodes, studios, tags, synopsis)
  • Prefer MP4 sources over HLS/m3u8 for faster playback
  • Automatic m3u8 → mp4 conversion for downloads

Installation

pip install anisama

With Playwright support

pip install anisama[playwright]
playwright install chromium

From source

git clone https://github.com/6sfy/anisama.git
cd anisama
pip install -e .

Usage

Interactive mode

anisama

CLI mode

anisama "demon slayer"
anisama "one piece" -e 1-5
anisama "attack on titan" -e 1,3,5 --lang vf
anisama "jujutsu kaisen" -d -e 1
anisama -p vlc "berserk"

Options

Flag Description
--lang vostfr/vf Language filter
--dub Shorthand for VF
-d, --download Download instead of streaming
-e, --episodes Episode range: 5, 1-5, or 1,3,5
-p, --player Player: mpv, vlc, iina, moonplayer, implay
-U, --update Force refresh the anime catalog
-s, --settings Open settings menu
-q, --quiet Reduce output verbosity
--version Show version
-h, --help Show help

API

anisama uses a centralized API for fast search and video resolution. The API server source is available at github.com/6sfy/anisama-api.

The API base URL defaults to https://anisama.sexcaller.lol and can be overridden with the ANISAMA_API environment variable.

As a library

from anisama import cache, search, resolver
from anisama.scraper import anime_sama, voiranime
from anisama.scraper.base import find_active_domain
from anisama.sources import SOURCES
from anisama.config import KNOWN_DOMAINS, DEFAULT_HEADERS

# Find active domain
domain = find_active_domain()

# Download catalog
catalog = cache.download_combined_catalog(domain)

# Search
results = search.search_combined("demon slayer", catalog, domain)

# Get episodes
seasons = anime_sama.get_anime_seasons(results[0]["link"])
episodes = anime_sama.get_episodes(seasons[0]["url"])

# Resolve video URL
video = resolver.resolve_url(episodes[0]["mirrors"]["eps1"])

# Use the unified source registry
for name, source in SOURCES.items():
    print(f"{name}: {source.description}")

Configuration

  • ANISAMA_API — Override the API base URL (default: https://anisama.sexcaller.lol)
  • ANISAMA_DATA_DIR — Override the data directory (default: <project_root>/data)
  • ANISAMA_PLAYWRIGHT_EXECUTABLE_PATH — Path to Playwright Chromium executable

Sources

Source Language Method
Anime-Sama VOSTFR/VF HTML scraping
Voiranime VOSTFR/VF HTML scraping
MyFluneo VOSTFR Playwright
AnimesUltra VOSTFR/VF Sitemap/HTML
French-Anime VOSTFR/VF HTML scraping
AnimoFlix VOSTFR HTML + Playwright
Franime VOSTFR/VF API

Contributing

  • Before creating an issue, please ensure that it hasn't already been reported/suggested.
  • See the contribution guide if you'd like to submit a PR.

Credits

  • pystardust/ani-cli for the original idea and workflow
  • Content sources: Anime-Sama, Voiranime, MyFluneo, AnimesUltra, French-Anime, AnimoFlix, Franime

Metadata

Release files for anisama 2.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anisama 2.1.1
File Size Uploaded Provenance Actions
anisama-2.1.1.tar.gz 63.1 kB With provenance Details for anisama-2.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anisama 2.1.1
File Interpreter ABI Platform Actions
anisama-2.1.1-py3-none-any.whl Python 3 none any Details for anisama-2.1.1-py3-none-any.whl

Total release size: 133.6 kB

Release files / anisama-2.1.1.tar.gz

Download URL anisama-2.1.1.tar.gz
Size 63.1 kB
Tags Source
SHA-256 checksum
How to use checksums
45ed206b2c5f063e3c6192e92cfb429bd9f773c34db0e828e5e05bb6ff29cd42
BLAKE2b-256 checksum
How to use checksums
ce05e18f9df6b15fbb8896c1064007f54ccd3efdc222ed827a7175d9abc0266b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.

Transparency log

Release files / anisama-2.1.1-py3-none-any.whl

Download URL anisama-2.1.1-py3-none-any.whl
Size 70.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
93029f747937b6aa8af2f1facec2bf18e6cf875a1cf03f6b7717e885e31decbc
BLAKE2b-256 checksum
How to use checksums
ef03f36ffb18e7bd2c50f8769735112a564d3ff2de39f68e5ee2e26020bc4ad9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.

Transparency log

Security for anisama 2.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anisama-2.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page