anime_manager/README.md

Anime Manager

A Python-based application for managing anime with automated monitoring, notifications, and a web dashboard.

Table of Contents

• Anime Manager
  • Table of Contents
  • Quick Start
    • Prerequisites
    • Installation
  • Features
  • Technology Stack
  • Architecture
  • Project Structure
  • Installation
    • Docker Setup
    • Local Setup
  • Configuration
    • General
    • Renamer
    • Telegram Notifications
    • Database
    • Logging
    • Environment Variables
  • Usage
    • Dashboard Features:
    • Key Capabilities:
  • Screenshots
    • Dashboard Overview
    • Rule Management Interface
    • Progress Tracking Page
    • Configuration Settings
    • Drop Folder Screen
  • Development
    • Running Tests
    • Code Style
  • Contributing
  • Future Improvements
    • Critical Issues
    • Security Enhancements
    • Code Quality
    • Feature Enhancements
    • Infrastructure
    • Priority Guide
  • License
  • Support

Quick Start

Prerequisites

• Docker & Docker Compose

Installation

wget https://gitea.kareemhorstink.me/Imrayya/anime_manager/src/branch/main/docker-compose.yml 
# Edit the docker-compose.yml file to customize settings as needed
docker compose up -d

Access the web dashboard at: http://localhost:5000

Features

• File Monitoring: Automatically watches directories for new anime files
• Database Management: Stores and manages anime information
• Notifications: Sends alerts for new episodes and updates
• Web Dashboard: User-friendly interface to manage anime, rules, and processing
• Rule Management: Create, edit, and delete regex-based rules for episode extraction and renaming
• Progress Tracking: Real-time view of in-progress file processing with detailed status
• File Processing: Advanced processing logic with duplicate episode handling and override title capabilities
• Flush & Reprocess: Manually trigger reprocessing of files for rule updates
• Processed Files Count: Dashboard displays counts of processed, pending, and total files
• Episode Extraction: Robust regex-based episode extraction with group index validation
• Docker Support: Easy deployment with Docker and Docker Compose

Technology Stack

Component	Technology
Backend	Python 3.8+, Flask
Database	SQLite
File Monitoring	Watchdog
Configuration	TOML
Notifications	Telegram Bot API
Deployment	Docker, Docker Compose

Architecture

graph TD
    A[Drop Folder] --> B[File Watcher]
    B --> C[Processor]
    C --> D[Database]
    C --> E[Notifications]
    C --> F[Renamer Script]
    C --> G[Media Folder]
    H[Web Dashboard] --> C
    H --> D

Architecture Flow:

1. Files are dropped into the monitored folder
2. File watcher detects new files
3. Processor handles extraction, renaming, and organization
4. Results stored in database and notifications sent
5. Web dashboard provides real-time monitoring and management

Project Structure

.
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── docker-compose.yml      # Docker Compose configuration
├── Dockerfile             # Docker image definition
├── core/                  # Core application modules
│   ├── config.py         # Configuration settings
│   ├── database.py       # Database management
│   ├── notifier.py       # Notification system
│   ├── processor.py      # File processing logic
│   ├── watcher.py        # Directory watching
│   └── __init__.py
└── web/                   # Web interface
    ├── app.py            # Flask application
    └── templates/        # HTML templates
        ├── base.html
        ├── dashboard.html
        ├── logs.html
        ├── progress.html
        ├── rules.html
        └── config.html

Installation

Docker Setup

docker compose up -d

For custom configuration, create a docker-compose.override.yml or modify the environment variables.

Local Setup

1. Clone the repository

git clone <repository-url>
cd "Anime Manager"

2. Create a virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure the application

   • Edit the configuration file config.toml (create one in the project root). See the Configuration section for details.

5. Run the application

python main.py

Configuration

Configuration is managed through core/config.py and uses a TOML file (config.toml). Key settings include:

General

Setting	Description	Default
drop_folder	Directory to watch for new files	/watch
media_folder	Destination directory for processed files	/anime
scan_interval	How often to scan for new files (seconds)	60
video_extensions	List of video file extensions to process	[".mp4", ".mkv", ".avi"]
check_stable_seconds	Wait time to ensure file is stable before processing	10

Renamer

Setting	Description	Default
script_path	Path to rename script	./rename.sh
python_executable	Python executable to use	python
default_flags	Default flags for the rename script	""

Telegram Notifications

Setting	Description	Default
enabled	Enable/disable Telegram notifications	false
bot_token	Telegram bot token	""
chat_id	Telegram chat ID	""
notify_on	List of events to notify about	["no_match", "copy_error", "rename_error"]

Database

Setting	Description	Default
path	Path to SQLite database file	anime_manager.db

Logging

Setting	Description	Default
level	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
max_log_entries	Maximum number of log entries to keep in the database	1000

Environment Variables

Variable	Description
ANIME_MANAGER_CONFIG_PATH	Path to custom config.toml file
ANIME_MANAGER_LOG_LEVEL	Override logging level
ANIME_MANAGER_PORT	Web dashboard port (default: 5000)

Usage

Once running, access the web dashboard at http://localhost:5000 (or configured port).

Dashboard Features:

• Anime Management: View all managed anime, add new series to track, manage watched/unwatched status
• Rule Management: Create, edit, and delete regex-based rules for episode extraction and file renaming
• Progress Tracking: Monitor in-progress file processing with real-time updates
• File Processing: View processed files count, trigger flush and reprocess operations
• Logs: Review system logs for debugging and monitoring
• Notifications: Receive alerts for new episodes and processing updates

Key Capabilities:

• Episode Extraction: Advanced regex matching with configurable group indexes
• Duplicate Handling: Automatic detection and handling of duplicate episodes
• Title Override: Custom title overrides for specific rules
• Batch Reprocessing: Manually reprocess files after rule changes
• Real-time Monitoring: Watch directory changes and process files automatically

Screenshots

Dashboard Overview

Rule Management Interface

Progress Tracking Page

Configuration Settings

Drop Folder Screen

Development

Running Tests

pytest

Code Style

Ensure code follows PEP 8 standards. Use black for formatting:

black .

Contributing

1. Create a feature branch
2. Make your changes
3. Submit a pull request

Future Improvements

Critical Issues

• Remove .roo/memory.txt reading from production code (security concern)
• Add CSRF protection to all web forms
• Add API authentication for /api/* endpoints

Security Enhancements

• Add rate limiting to API endpoints
• Add environment variable validation at startup
• Implement secure file handling with path traversal checks

Code Quality

• Add comprehensive unit tests
• Replace raw SQL with SQLAlchemy ORM
• Implement config hot-reload support
• Add consistent type hints across all modules

Feature Enhancements

• Add WebSocket support for real-time updates
• Implement multi-user support with role-based access
• Add additional notification channels (Discord, Email, webhooks)
• Add rule import/export functionality (JSON/YAML)
• Add file thumbnails/previews in dashboard
• Add statistics/analytics dashboard with charts
• Implement scheduled processing (cron-like functionality)
• Add backup/restore for database and config

Infrastructure

• Add health check endpoint (/api/health)
• Add Prometheus metrics endpoint
• Add Docker healthcheck to Dockerfile

Priority Guide

Priority	Items
High	CSRF protection, API authentication, .roo/memory.txt removal
Medium	Rate limiting, config validation, unit tests
Lower	Feature additions (WebSocket, multi-user, etc.)

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

You are free to:

• Use this software for any purpose
• Modify and distribute it
• Use it commercially

Under the condition that:

• You use the same GPL v3 license for derivative works
• You include a copy of the license
• You provide a link to the original project
• You disclose modifications made to the code

Support

For issues and questions, please create an issue in the repository.