Aniworld/docs/user_guide.md

Aniworld User Guide

Complete user guide for the Aniworld Download Manager web application.

Table of Contents

1. Getting Started
2. Installation
3. Initial Setup
4. User Interface
5. Configuration
6. Managing Anime
7. Download Queue
8. Troubleshooting
9. Keyboard Shortcuts
10. FAQ

Getting Started

Aniworld is a modern web application for managing and downloading anime series. It provides:

• Web-based Interface: Access via any modern web browser
• Real-time Updates: Live download progress tracking
• Queue Management: Organize and prioritize downloads
• Configuration Management: Easy setup and configuration
• Backup & Restore: Automatic configuration backups

System Requirements

• OS: Windows, macOS, or Linux
• Browser: Chrome, Firefox, Safari, or Edge (modern versions)
• Internet: Required for downloading anime
• Storage: Sufficient space for anime files (adjustable)
• RAM: Minimum 2GB recommended

Installation

Prerequisites

• Python 3.10 or higher
• Poetry (Python package manager)
• Git (for cloning the repository)

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/your-repo/aniworld.git
cd aniworld

2. Create Python Environment

# Using conda (recommended)
conda create -n AniWorld python=3.10
conda activate AniWorld

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

3. Install Dependencies

# Using pip
pip install -r requirements.txt

# Or using poetry
poetry install

4. Start the Application

# Using conda
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

# Or directly
python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000

5. Access the Application

Open your browser and navigate to:

http://localhost:8000

Initial Setup

Setting Master Password

On first launch, you'll be prompted to set a master password:

1. Navigate to Setup Page: http://localhost:8000/setup
2. Enter Password: Choose a strong password (minimum 8 characters recommended)
3. Confirm Password: Re-enter the password for confirmation
4. Save: Click "Set Master Password"

The master password protects access to your anime library and download settings.

Configuration

After setting the master password, configure the application:

1. Login: Use your master password to log in

2. Go to Settings: Click the settings icon in the navigation bar

3. Configure Directories:

   • Anime Directory: Where anime series are stored
   • Download Directory: Where downloads are saved
   • Cache Directory: Temporary file storage (optional)

4. Advanced Settings (optional):

   • Session Timeout: How long before auto-logout
   • Log Level: Application logging detail level
   • Theme: Light or dark mode preference

5. Save: Click "Save Configuration"

Automatic Backups

The application automatically creates backups when you update configuration. You can:

• View all backups in Settings → Backups
• Manually create a backup anytime
• Restore previous configuration versions
• Delete old backups to save space

User Interface

Dashboard

The main dashboard shows:

• Quick Stats: Total anime, episodes, storage used
• Recent Activity: Latest downloads and actions
• Quick Actions: Add anime, manage queue, view settings

Navigation

Top Navigation Bar:

• Logo: Return to dashboard
• Anime: Browse and manage anime library
• Downloads: View download queue and history
• Settings: Configure application
• Account: User menu (logout, profile)

Theme

Dark Mode / Light Mode:

• Toggle theme in Settings
• Theme preference is saved automatically
• Default theme can be set in configuration

Managing Anime

Browsing Anime Library

1. Click "Anime" in navigation
2. View Anime List: Shows all anime with missing episodes
3. Filter: Filter by series status or search by name

Adding New Anime

1. Click "Add Anime" button
2. Search: Enter anime title or key
3. Select: Choose anime from search results
4. Confirm: Click "Add to Library"

Viewing Anime Details

1. Click Anime Title in the list
2. View Information: Episodes, status, total count
3. Add Episodes: Select specific episodes to download

Managing Episodes

View Episodes:

• All seasons and episodes for the series
• Downloaded status indicators
• File size information

Download Episodes:

1. Select episodes to download
2. Click "Add to Queue"
3. Choose priority (Low, Normal, High)
4. Confirm

Delete Episodes:

1. Select downloaded episodes
2. Click "Delete"
3. Choose whether to keep or remove files
4. Confirm

Download Queue

Queue Status

The queue page shows:

• Queue Stats: Total items, status breakdown
• Current Download: What's downloading now
• Progress: Download speed and time remaining
• Queue List: All pending downloads

Queue Management

Add Episodes to Queue

1. Go to "Anime" or "Downloads"
2. Select anime and episodes
3. Click "Add to Queue"
4. Set priority and confirm

Manage Queue Items

Pause/Resume:

• Click pause icon to pause individual download
• Resume when ready

Prioritize:

1. Click item in queue
2. Select "Increase Priority" or "Decrease Priority"
3. Items with higher priority download first

Remove:

1. Select item
2. Click "Remove" button
3. Confirm deletion

Control Queue Processing

Start Queue: Begin downloading queued items

• Click "Start" button
• Downloads begin in priority order

Pause Queue: Pause all downloads temporarily

• Click "Pause" button
• Current download pauses
• Click "Resume" to continue

Stop Queue: Stop all downloads

• Click "Stop" button
• Current download stops
• Queue items remain

Clear Completed: Remove completed items from queue

• Click "Clear Completed"
• Frees up queue space

Monitor Progress

Real-time Updates:

• Download speed (MB/s)
• Progress percentage
• Time remaining
• Current file size

Status Indicators:

• 🔵 Pending: Waiting to download
• 🟡 Downloading: Currently downloading
• 🟢 Completed: Successfully downloaded
• 🔴 Failed: Download failed

Retry Failed Downloads

1. Find failed item in queue
2. Click "Retry" button
3. Item moves back to pending
4. Download restarts when queue processes

Configuration

Basic Settings

Anime Directory:

• Path where anime series are stored
• Must be readable and writable
• Can contain nested folders

Download Directory:

• Where new downloads are saved
• Should have sufficient free space
• Temporary files stored during download

Session Timeout:

• Minutes before automatic logout
• Default: 1440 (24 hours)
• Minimum: 15 minutes

Advanced Settings

Log Level:

• DEBUG: Verbose logging (development)
• INFO: Standard information
• WARNING: Warnings and errors
• ERROR: Only errors

Update Frequency:

• How often to check for new episodes
• Default: Daily
• Options: Hourly, Daily, Weekly, Manual

Provider Settings:

• Anime provider configuration
• Streaming server preferences
• Retry attempts and timeouts

Storage Management

View Storage Statistics:

• Total anime library size
• Available disk space
• Downloaded vs. pending size

Manage Storage:

1. Go to Settings → Storage
2. View breakdown by series
3. Delete old anime to free space

Backup Management

Create Backup:

1. Go to Settings → Backups
2. Click "Create Backup"
3. Backup created with timestamp

View Backups:

• List of all configuration backups
• Creation date and time
• Size of each backup

Restore from Backup:

1. Click backup name
2. Review changes
3. Click "Restore"
4. Application reloads with restored config

Delete Backup:

1. Select backup
2. Click "Delete"
3. Confirm deletion

Troubleshooting

Common Issues

Can't Access Application

Problem: Browser shows "Connection Refused"

Solutions:

• Verify application is running: Check terminal for startup messages
• Check port: Application uses port 8000 by default
• Try different port: Modify configuration if 8000 is in use
• Firewall: Check if firewall is blocking port 8000

Login Issues

Problem: Can't log in or session expires

Solutions:

• Clear browser cookies: Settings → Clear browsing data
• Try incognito mode: May help with cache issues
• Reset master password: Delete data/config.json and restart
• Check session timeout: Verify in settings

Download Failures

Problem: Downloads keep failing

Solutions:

• Check internet connection: Ensure stable connection
• Verify provider: Check if anime provider is accessible
• View error logs: Go to Settings → Logs for details
• Retry download: Use "Retry" button on failed items
• Contact provider: Provider might be down or blocking access

Slow Downloads

Problem: Downloads are very slow

Solutions:

• Check bandwidth: Other applications might be using internet
• Provider issue: Provider might be throttling
• Try different quality: Lower quality might download faster
• Queue priority: Reduce queue size for faster downloads
• Hardware: Ensure sufficient CPU and disk performance

Application Crashes

Problem: Application stops working

Solutions:

• Check logs: View logs in Settings → Logs
• Restart application: Stop and restart the process
• Clear cache: Delete temporary files in Settings
• Reinstall: As last resort, reinstall application

Error Messages

"Authentication Failed"

• Incorrect master password
• Session expired (need to log in again)
• Browser cookies cleared

"Configuration Error"

• Invalid directory path
• Insufficient permissions
• Disk space issues

"Download Error: Provider Error"

• Anime provider is down
• Content no longer available
• Streaming server error

"Database Error"

• Database file corrupted
• Disk write permission denied
• Low disk space

Getting Help

Check Application Logs:

1. Go to Settings → Logs
2. Search for error messages
3. Check timestamp and context

Review Documentation:

• Check API Reference
• Review Deployment Guide
• Consult inline code comments

Community Support:

• Check GitHub issues
• Ask on forums or Discord
• File bug report with logs

Keyboard Shortcuts

General

Shortcut	Action
Ctrl+S / Cmd+S	Save settings
Ctrl+L / Cmd+L	Focus search
Escape	Close dialogs
?	Show shortcuts help

Anime Management

Shortcut	Action
Ctrl+A	Add new anime
Ctrl+F	Search anime
Delete	Remove anime
Enter	View details

Download Queue

Shortcut	Action
Ctrl+D	Add to queue
Space	Play/Pause queue
Ctrl+Shift+P	Pause all downloads
Ctrl+Shift+S	Stop all downloads

Navigation

Shortcut	Action
Ctrl+1	Go to Dashboard
Ctrl+2	Go to Anime
Ctrl+3	Go to Downloads
Ctrl+4	Go to Settings

Accessibility

Shortcut	Action
Tab	Navigate between elements
Shift+Tab	Navigate backwards
Alt+M	Skip to main content
Alt+H	Show help

FAQ

General Questions

Q: Is Aniworld free? A: Yes, Aniworld is open-source and completely free to use.

Q: Do I need internet connection? A: Yes, to download anime. Once downloaded, you can watch offline.

Q: What formats are supported? A: Supports most video formats (MP4, MKV, AVI, etc.) depending on provider.

Q: Can I use it on mobile? A: The web interface works on mobile browsers, but is optimized for desktop.

Installation & Setup

Q: Can I run multiple instances? A: Not recommended. Use single instance with same database.

Q: Can I change installation directory? A: Yes, reconfigure paths in Settings → Directories.

Q: What if I forget my master password? A: Delete data/config.json and restart (loses all settings).

Downloads

Q: How long do downloads take? A: Depends on file size and internet speed. Typically 5-30 minutes per episode.

Q: Can I pause/resume downloads? A: Yes, pause individual items or entire queue.

Q: What happens if download fails? A: Item remains in queue. Use "Retry" to attempt again.

Q: Can I download multiple episodes simultaneously? A: Yes, configure concurrent downloads in settings.

Storage

Q: How much space do I need? A: Depends on anime count. Plan for 500MB-2GB per episode.

Q: Where are files stored? A: In the configured "Anime Directory" in settings.

Q: Can I move downloaded files? A: Yes, but update the path in configuration afterwards.

Performance

Q: Application is slow, what can I do? A: Reduce queue size, check disk space, restart application.

Q: How do I free up storage? A: Go to Settings → Storage and delete anime you no longer need.

Q: Is there a way to optimize database? A: Go to Settings → Maintenance and run database optimization.

Support

Q: Where can I report bugs? A: File issues on GitHub repository.

Q: How do I contribute? A: See CONTRIBUTING.md for guidelines.

Q: Where's the source code? A: Available on GitHub (link in application footer).

---

Additional Resources

• API Reference - For developers
• Deployment Guide - For system administrators
• GitHub Repository
• Interactive API Documentation

---

Support

For additional help:

1. Check this user guide first
2. Review Troubleshooting section
3. Check application logs in Settings
4. File issue on GitHub
5. Contact community forums

---

Last Updated: October 22, 2025 Version: 1.0.0