Seraph-Novel-DL

Novel downloader with Cloudflare bypass using undetected-chromedriver.

Features

Core Features

• ✅ Cloudflare Bypass - Automatically bypasses Cloudflare protection
• ✅ Modern GUI - Beautiful PyQt5 dark-themed interface
• ✅ Plugin Architecture - Easy to add support for new novel sites
• ✅ Session Management - Saves login sessions for reuse

GUI Features

• 🎨 Modern Dark Theme - Sleek Catppuccin Mocha color scheme
• 🔍 Novel Search - Search and browse novels with detailed results
• 📖 Novel Details - View cover, description, rating, genres, and chapter list
• 📥 Smart Downloads - Download with progress tracking, pause/resume, and retry logic
• 📁 Custom Output - Choose where to save your downloaded novels
• 🔐 Optional Login - Auto-hides login for sites that don't require it

EPUB Features

• 📚 Rich Metadata - Includes title, author, description, and genres
• 🖼️ Cover Images - Automatically downloads and embeds cover art
• 📑 Table of Contents - Proper chapter navigation
• 🎯 Clean Content - Removes ads and unwanted text

Installation

pip install -r requirements.txt

How It Works

The script uses undetected-chromedriver which makes Chrome undetectable to anti-bot systems like Cloudflare. It will:

1. Launch Chrome with anti-detection
2. Navigate to the login page
3. Auto-solve any Cloudflare challenges
4. Log you in
5. Save your session to selenium_session.pkl

Session Reuse

After the first successful login, your session is saved to selenium_session.pkl. You can load these cookies in future sessions to skip the login process.

Troubleshooting

Chrome version mismatch

If you get a Chrome version error, the driver will auto-download the correct version.

Cloudflare still blocking

Make sure you're not using a VPN or proxy that's flagged by Cloudflare.

Login fails

Check your credentials in the .env file.

Plugin Architecture

Seraph-Novel-DL uses a simple plugin system to support multiple novel websites. Each plugin implements a standard interface defined by BasePlugin.

Adding a New Site

1. Create plugin file: plugins/yoursite_com.py
2. Inherit from BasePlugin:

from plugins.base_plugin import BasePlugin

class YourSitePlugin(BasePlugin):
    @property
    def name(self) -> str:
        return "YourSite"

    @property
    def requires_login(self) -> bool:
        return True  # or False if login is optional

    # Implement required methods:
    # - initialize(driver)
    # - login(driver, email, password)
    # - search_novel(driver, query)
    # - get_novel_details(driver)
    # - load_chapters(driver)
    # - download_chapter(driver, url, title)

3. Create locators: locators/yoursite_com/ folder with CSS selectors
4. Register plugin: Add to PLUGINS dict in main.py

PLUGINS = {
    "novelbin": NovelBinPlugin,
    "yoursite": YourSitePlugin,  # Add here
}

Project Structure

Seraph-Novel-DL/
├── gui.py                  # PyQt5 GUI application
├── main.py                 # Core functions and plugin registry
├── requirements.txt        # Python dependencies
├── .env                    # Your credentials (optional)
├── plugins/               # Website plugins
│   ├── base_plugin.py     # Plugin interface
│   └── novelbin_com.py    # NovelBin implementation
├── locators/              # CSS selectors for each site
│   └── novelbin_com/
│       ├── login.py
│       ├── main_page.py
│       ├── novel_page.py
│       └── chapter_page.py
└── output/                # Downloaded EPUB files

Dependencies

• undetected-chromedriver - Bypasses bot detection
• selenium - Browser automation
• PyQt5 - Modern GUI framework
• ebooklib - EPUB file generation
• python-dotenv - Environment variable management

Credits

Inspired by Novel-Grabber by Flameish.