Aniworld/docs/user_guide.md

# Aniworld User Guide

Complete user guide for the Aniworld Download Manager web application.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Installation](#installation)
3. [Initial Setup](#initial-setup)
4. [User Interface](#user-interface)
5. [Configuration](#configuration)
6. [Managing Anime](#managing-anime)
7. [Download Queue](#download-queue)
8. [Troubleshooting](#troubleshooting)
9. [Keyboard Shortcuts](#keyboard-shortcuts)
10. [FAQ](#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

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

#### 2. Create Python Environment

```bash
# 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

```bash
# Using pip
pip install -r requirements.txt

# Or using poetry
poetry install
```

#### 4. Start the Application

```bash
# 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](./api_reference.md)
-   Review [Deployment Guide](./deployment.md)
-   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](./api_reference.md) - For developers
-   [Deployment Guide](./deployment.md) - For system administrators
-   [GitHub Repository](https://github.com/your-repo/aniworld)
-   [Interactive API Documentation](http://localhost:8000/api/docs)

---

## Support

For additional help:

1. Check this user guide first
2. Review [Troubleshooting](#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