root
d4d8d8a3b6
- Migrated monolithic main.py to feature-scoped routers in app/routers/ - Added GEMINI.md for project context and AI instructional guidelines - Updated README.md with a comprehensive modernization plan (SQL migration, robust scraping DSL, frontend modernization) - Improved authentication with cookie support and modular JS - Updated test suite and documentation
42 lines
2.1 KiB
Markdown
42 lines
2.1 KiB
Markdown
# 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
|