DOCSEARCHbyAlgolia
Submit Docs

AutoBangumi Documentation

repository·main·Indexed 27 days ago

https://github.com/estrellaxd/auto_bangumi

An automated anime download manager (version 3.3.5) that uses RSS feeds to trigger downloads and organizes files into media-server-ready directory structures. It features automated RSS parsing, TMDB integration, a setup wizard, and support for qBittorrent and aria2. The system includes a Vue3 and TypeScript-based WebUI and a FastAPI backend with an API for managing bangumi rules, torrent records, and episode offset detection.

Tokens
60K
Snippets
97
Records
395
Agent score
90%

What's inside AutoBangumi

  1. Overview of AutoBangumi features

    main

    AutoBangumi is an automated tool for anime subscription parsing, download management, and file organization. Key features include:

    • RSS Subscription Parsing: Automatically identifies and parses anime RSS feeds to handle parsing, downloading, and organizing without manual input.
    • Downloaders: Supports qBittorrent and aria2. Users can manage existing anime, download past episodes, and delete entries directly within AutoBangumi.
    • TMDB Metadata Matching: Uses TMDB to match anime information, ensuring accurate metadata even across different subtitle groups.
    • Media Library Integration: Automatically organizes filenames and directory structures to ensure high success rates for metadata scraping in media servers like Plex, Jellyfin, and Infuse.

  3. Overview of AutoBangumi

    main

    AutoBangumi is an automated anime downloading and organizing tool that operates based on RSS feeds. It tracks subscriptions from sites like [Mikan Project][mikan] and automatically downloads new episodes.

    Key capabilities include:

    • Automated Organization: Creates directory structures compatible with media servers like Plex and Jellyfin.
    • Automatic Renaming: Renames files to a standardized format (e.g., Series S01E01.mp4) to ensure high compatibility with media library metadata scrapers.
    • Mid-season Catch-up: Automatically identifies and downloads missed episodes from a current season.
    • Metadata Support: Includes a built-in TMDB parser to generate TMDB-formatted metadata files.
    • Customization: Highly fine-tunable settings for different media library requirements and reverse proxy support for Mikan RSS feeds.

  4. E2E Test Architecture and Design

    main

    The E2E testing environment uses a decoupled architecture to ensure isolation and bypass security restrictions during setup.

    Component Roles

    • pytest: The test runner driving HTTP requests to AutoBangumi at localhost:7892.
    • AutoBangumi Subprocess: Runs with isolated config/ and data/ directories in a temporary directory. It uses a downloader_type: "mock" during setup to bypass SSRF protections that block loopback IPs (like the qBittorrent container on localhost).
    • qBittorrent Container: Runs linuxserver/qbittorrent:latest at localhost:18080.
    • Mock RSS Server: Serves static XML fixtures from the fixtures/ directory at localhost:18888.

    Key Behaviors

    • DEV_VERSION Auth Bypass: When running from source (VERSION == "DEV_VERSION"), JWT validation is bypassed, and get_current_user returns "dev_user" unconditionally. This allows unauthenticated access during testing.
    • Path Isolation: AutoBangumi resolves config/ and data/ relative to the current working directory. The ab_process fixture ensures tests run in a clean, temporary directory.

  5. Understand the Backend Architecture Layers

    main

    The backend follows a layered architecture to decouple business logic from infrastructure. Developers should follow these dependency directions:

    1. domain: Contains domain values and rules. It must NOT import FastAPI, SQLModel sessions, or external clients.
    2. application: Contains use cases and typed application errors.
    3. ports: Defines protocols (interfaces) for repositories, unit-of-work, downloaders, HTTP, notifications, sessions, tokens, configuration, scheduler leases, and clocks.
    4. adapters: Contains concrete implementations (e.g., FastAPI, MCP, SQLite/SQLModel, HTTPX, notification providers, and file-backed configuration).

  6. Understand the Authentication and Session Model

    main

    Auto_Bangumi uses a database-backed session model for browser users and token-based authentication for APIs/MCP.

    Browser Sessions

    • Transport: Sessions are managed exclusively via an HttpOnly cookie named token.
    • Login/Refresh Response: Successful authentication endpoints return a non-secret DTO: { "authenticated": true }. They do not return an access_token field.
    • Logout: Revokes the cookie session and clears the cookie on the response. It is idempotent.

    API and MCP Authentication

    • Bearer Tokens: The Authorization: Bearer header accepts only database-backed tokens with scope="api". It cannot be used for browser-session tokens.
    • MCP: Requires a token with scope="mcp" or an allowed client IP.
    • Precedence: If a request contains both a Bearer API token and a session cookie, the Authorization header takes precedence. An API token will receive a 403 from session-only endpoints even if a valid cookie is present.

  7. Understand the Search Panel Redesign Plan

    main

    The Search Panel Redesign transitions the search experience from a simple dropdown list to a full modal-based interface. This redesign aims to prevent accidental dismissal of results, support large result sets via scrolling, and introduce advanced filtering capabilities based on metadata extracted from torrent titles.

    Key improvements include:

    • Modal-based UI: Uses a centered modal with a backdrop that does not close on click (to prevent accidental loss of results).
    • Advanced Filtering: Users can filter results by four dimensions: Subtitle Group, Resolution, Subtitle Type, and Season.
    • Confirmation Step: A nested modal allows users to review parsed metadata (RSS source, subtitle group, resolution, etc.) and configure advanced settings before subscribing.
    • Responsive Design: Adapts from a 3-column grid on desktop to a single-column bottom sheet on mobile devices.

  8. Core Features of AutoBangumi

    main

    AutoBangumi provides several key automation features:

    • Automated RSS Parsing: Parses bangumi information and automatically generates download rules.
    • Setup Wizard: A 7-step guided configuration for first-time users.
    • File Organization: Automatically organizes files into a hierarchical structure (e.g., Bangumi/Title/Season X/File.mp4).
    • Automatic Renaming: Renames files to a standard format (e.g., Kakkou no Iinazuke S01E07.mp4) that is highly compatible with media scrapers.
    • Missing Episode Recovery: Can complete missing episodes for a season currently in progress.
    • Customization: Highly configurable options for different media library requirements.
    • TMDB Integration: Built-in TMDB parser to generate complete TMDB-formatted files and metadata.
    • Supported Downloaders: Currently supports qBittorrent and aria2.

  9. Understand the Tokenizer Candidate/Resolver Architecture

    main

    The parsing architecture has migrated from a rule-based state modification model to a multi-stage pipeline that separates candidate generation from resolution. This ensures that rules are immutable and do not prematurely consume text, allowing for better conflict resolution.

    Parsing Pipeline Flow:

    1. Normalize: Normalize the input string and scan segments/spans.
    2. Rules: Collectors (group, structural, media, technical) emit Candidate[] objects.
    3. Resolver: Processes candidates to accept or reject them based on priority, specificity, and conflicts.
    4. Reconstruct: The title is rebuilt from the remaining unconsumed spans.
    5. Output: Produces a ParsedRelease object and an optional ParseTrace for diagnostics.

  10. Understand the AutoBangumi workflow pipeline

    main

    AutoBangumi (AB) operates as an RSS parser that automates the process from discovery to media library organization. The pipeline follows these six stages:

    1. RSS Parsing: Periodically fetches and parses subscribed RSS feeds from anime torrent sites.
    2. Title Analysis: Parses torrent titles to extract metadata including anime name, episode number, season, subtitle group, and resolution.
    3. Rule Generation: Creates specific download rules in qBittorrent based on the extracted metadata.
    4. Download Management: qBittorrent performs the actual downloading of the torrents.
    5. File Organization: Renames and moves downloaded files into a standardized directory structure.
    6. Media Library Ready: Produces organized files compatible with media servers like Plex and Jellyfin.

  11. Understand the AutoBangumi workflow

    main

    AutoBangumi (AB) functions as an RSS parser that automates the process of finding, downloading, and organizing anime content. The workflow follows these steps:

    1. RSS Parsing: AB periodically fetches and parses your subscribed RSS feeds.
    2. Title Analysis: It parses torrent titles to extract metadata such as anime name, episode number, season, subtitle group, and resolution.
    3. Rule Generation: Based on the extracted metadata, AB creates download rules within qBittorrent.
    4. Download Management: qBittorrent handles the actual downloading of the torrents.
    5. File Organization: Once downloaded, files are renamed and moved into a standardized directory structure.
    6. Media Library Readiness: The organized files are ready to be recognized by media servers like Plex or Jellyfin.

  12. New Features in Version 3.3

    main

    Version 3.3 introduced several advanced capabilities:

    • In-App Updates: Check, apply, and rollback updates via the log page with sha256 and ed25519 signature verification.
    • Multi-Provider LLM Parsers: Supports OpenAI-compatible interfaces, Anthropic Claude, and Google Gemini with primary/fallback modes.
    • Enhanced aria2 Support: Full management of aria2 including adding, querying, renaming, managing, and duplicate detection.
    • Special Content Support: Automatic identification and organization of Movies, OVA, OAD, and SP types.
    • Per-Bangumi Preferences: Set specific subtitle group or resolution preferences for individual series to avoid redundant downloads.
    • SSE-Driven WebUI: Uses Server-Sent Events (SSE) for real-time updates of status, downloader, and log pages.
    • Architectural Upgrades: Fully asynchronous backend, hardened authentication, health checks, and reliable database migrations.