ohm_streaming/app/downloaders/anime_sites/AGENTS.md

Anime Sites Downloaders

OVERVIEW

Handlers for French anime streaming catalogs that provide metadata and episode listings, delegating actual video extraction to video player handlers.

WHERE TO LOOK

File	Purpose
base.py	Abstract BaseAnimeSite class defining the interface all anime sites implement
animesama.py	Primary provider with dynamic domain switching, multiple video player extraction
nekosama.py	Neko-Sama / Gupy integration (metadata-only, no direct downloads)
animeultime.py	Anime-Ultime catalog handler
vostfree.py	Vostfree catalog handler
frenchmanga.py	French-Manga catalog handler

CONVENTIONS

Interface Contract

Each site must implement four async methods from BaseAnimeSite:

• can_handle(url: str) -> bool — URL pattern matching
• search_anime(query, lang) -> list[dict] — Returns {title, url, cover_image}
• get_episodes(anime_url, lang) -> list[dict] — Returns {episode_number, url, title, host}
• get_anime_metadata(anime_url) -> dict — Returns {synopsis, genres, rating, release_year, studio, poster_image, total_episodes, status}
• get_download_link(url) -> tuple[str, str] — Returns (video_player_url, filename)

Key Patterns

• Pipe-separated URLs: video_url|anime_page_url|episode_title — preserves context across extraction
• Language parameter: lang="vostfr" or "vf" — controls which episodes to return
• Video player delegation: Anime sites return player URLs (vidmoly, sendvid, sibnet, lpayer), not direct downloads
• Filename generation: {anime_name} - S{season} - {episode}.mp4 format
• HTTP headers: Browser UA and referer required to avoid blocking

Domain Detection

• AnimeSamaDownloader fetches current domain from anime-sama.pw dynamically
• Uses fallback chain for video extraction: detected player → cached player → priority list

Error Handling

• Raise Exception with descriptive message on failure
• Log at appropriate level (debug for expected failures, error for unexpected)
• Validate extracted URLs with _test_video_url() before returning