AniWorld Downloader

AniWorld Downloader is a command-line tool built to download and stream anime content from aniworld.to. With it, you can grab single episodes, download entire seasons, and organize files into neatly structured folders. It’s cross-platform, so it works on Windows, macOS, and Linux for a smooth experience across all major OSes.

Table of Contents

Overview

• Features
• TODO

Getting Started

• Installation
  • Latest Release
  • Dev Version (Unstable)
• Uninstallation

Usage Guide

• Usage Basics
  • Running with Menu
  • Command-Line Arguments

Examples

• Command-Line Examples
  • Download a Single Episode
  • Download Multiple Episodes
  • Watch Episodes with Aniskip
  • Syncplay with Friends
  • Download with Specific Provider and Language
  • Use Episode File

Advanced Setup

• Anime4K Setup

FAQs and Support

• FAQ
  • Providers
  • s.to & bs.to Support
• Support

Contribution and Licensing

• Contributing
• Credits
• License

Project Insights

• Star History

Features

• Episode Downloads: Easily download single episodes or entire seasons in one go.
• Instant Streaming: Stream episodes directly via the mpv player.
• Auto Play Next: Automatically transition to the next episode for uninterrupted viewing.
• Flexible Providers: Choose from Vidoza, VOE, and Streamtape, with Doodstream support coming soon.
• Language Options: Switch between German Dub, English Sub, or German Sub based on your preference.
• Aniskip Integration: Automatically skip intros and outros (currently available for Season 1; expanding soon).
• Syncplay for Group Watching: Enjoy synchronized anime watching sessions with friends.
• Proxy Compatibility: Set up an HTTP proxy for restricted network environments.

(back to top)

Installation

Prerequisites

1. Python Version: Ensure you have Python 3.9 or higher installed.
   • Note: Although Python 3.13 is available, it does not include windows-curses, which is needed for the menu to work on Windows. To avoid issues, please use Python 3.12 until windows-curses is updated. Check for updates here.

Python Installation Tutorial (Windows only)

Installing AniWorld Downloader

• To install the latest release of AniWorld Downloader, run:

  pip install aniworld

• To update to the latest version, use:

  pip install -U aniworld

Development Version (Unstable & Requires Git)

• To install the latest development changes directly from GitHub, use:

  pip install --upgrade git+https://github.com/phoenixthrush/AniWorld-Downloader.git#egg=aniworld

• To update, simply rerun the command above. These builds may be unstable, so it’s good to check regularly.

Local Installation

If you prefer to have the files locally:

1. Clone the repository:

   git clone https://github.com/phoenixthrush/AniWorld-Downloader aniworld

2. Install it in editable mode:

   pip install -U -e ./aniworld

3. To keep your local version up to date, run:

   git -C aniworld pull

(back to top)

Uninstallation

To uninstall AniWorld Downloader, run the following command:

aniworld --uninstall

(back to top)

Usage

Running with Menu

To launch AniWorld Downloader with an interactive menu, use:

aniworld

(back to top)

Command-Line Examples

AniWorld Downloader supports various command-line options for downloading and streaming anime without using the interactive menu. This allows access to advanced features not available in the menu (e.g., --aniskip, --keep-watching, --syncplay-password).

Example 1: Download a Single Episode

To download episode 1 of "Demon Slayer: Kimetsu no Yaiba":

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1

Example 2: Download Multiple Episodes

To download multiple episodes of "Demon Slayer":

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-2

Example 3: Watch Episodes with Aniskip

To watch an episode while skipping intros and outros:

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --action Watch --aniskip

Example 4: Syncplay with Friends

To syncplay a specific episode with friends:

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --action Syncplay --keep-watching

Language Options for Syncplay

You can choose different languages for yourself and your friends:

• For German Dub:

  aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --action Syncplay --keep-watching --language "German Dub" --aniskip

• For English Sub:

  aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --action Syncplay --keep-watching --language "English Sub" --aniskip

Note: Anyone watching the same anime (regardless of episode) will automatically join the room if Syncplay is enabled. To restrict access to strangers, set a password for the room:

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --action Syncplay --keep-watching --language "English Sub" --aniskip --syncplay-password beans

Example 5: Download with Specific Provider and Language

To download an episode using the VOE provider with English subtitles:

aniworld --episode https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-1/episode-1 --provider VOE --language "English Sub"

Example 6: Use an Episode File

You can download episodes listed in a text file. Here’s an example of what the text file (test.txt) should look like:

# The whole anime
https://aniworld.to/anime/stream/alya-sometimes-hides-her-feelings-in-russian

# The whole Season 2
https://aniworld.to/anime/stream/demon-slayer-kimetsu-no-yaiba/staffel-2

# Only Season 3 Episode 13
https://aniworld.to/anime/stream/kaguya-sama-love-is-war/staffel-3/episode-13

To download the episodes specified in the file, use:

aniworld --episode-file /Users/goofball/Downloads/test.txt --language "German Dub"

You can also combine this with Watch and Syncplay actions, along with other arguments as needed.

(back to top)

Anime4K Setup

To set up Anime4K, run the following commands based on your GPU type. This setup will install everything needed to use Anime4K in the mpv player, even outside of AniWorld.

For Higher-End GPUs

(e.g., GTX 1080, RTX 2070, RTX 3060, RX 590, Vega 56, 5700XT, 6600XT, M1 Pro, M1 Max, M1 Ultra, M2 Pro, M2 Max)

aniworld --anime4k High

For Lower-End GPUs

(e.g., GTX 980, GTX 1060, RX 570, M1, M2, Intel chips)

aniworld --anime4k Low

To Remove Anime4K

If you want to uninstall Anime4K, use the following command:

aniworld --anime4k Remove

Notes

• This installation saves all necessary files into the mpv directory.
• You can switch between settings by specifying the optimized modes (High or Low).
• Use the Remove option to uninstall Anime4K easily.

(back to top)

AniWorld Command Options

aniworld --help

usage: aniworld [-h] [-v] [-d] [-u] [-U {mpv,yt-dlp,syncplay,all}] [-s SLUG] [-l LINK]
                [-q QUERY] [-e EPISODE [EPISODE ...]] [-f EPISODE_FILE] [-lf]
                [-a {Watch,Download,Syncplay}] [-o OUTPUT] [-O OUTPUT_DIRECTORY]
                [-L {German Dub,English Sub,German Sub}]
                [-p {Vidoza,Streamtape,VOE,Doodstream}] [-A {High,Low,Remove}]
                [-sH SYNCPLAY_HOSTNAME] [-sU SYNCPLAY_USERNAME] [-sR SYNCPLAY_ROOM]
                [-sP SYNCPLAY_PASSWORD [SYNCPLAY_PASSWORD ...]] [-k] [-K]
                [-r [RANDOM_ANIME]] [-D] [-C] [-x PROXY] [-w]

Parse optional command line arguments.

options:
  -h, --help            show this help message and exit

General Options:
  -v, --version         Print version info
  -d, --debug           Enable debug mode
  -u, --uninstall       Self uninstall
  -U {mpv,yt-dlp,syncplay,all}, --update {mpv,yt-dlp,syncplay,all}
                        Update mpv, yt-dlp, syncplay, or all.

Search Options:
  -s SLUG, --slug SLUG  Search query - E.g. demon-slayer-kimetsu-no-yaiba
  -l LINK, --link LINK  Search query - E.g. https://aniworld.to/anime/stream/demon-
                        slayer-kimetsu-no-yaiba
  -q QUERY, --query QUERY
                        Search query input - E.g. demon

Episode Options:
  -e EPISODE [EPISODE ...], --episode EPISODE [EPISODE ...]
                        List of episode URLs
  -f EPISODE_FILE, --episode-file EPISODE_FILE
                        File path containing a list of episode URLs
  -lf, --episode-local  NOT IMPLEMENTED YET - Use local episode files instead of URLs

Action Options:
  -a {Watch,Download,Syncplay}, --action {Watch,Download,Syncplay}
                        Action to perform
  -o OUTPUT, --output OUTPUT
                        Download directory E.g. /Users/phoenixthrush/Downloads
  -O OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        Final download directory E.g ExampleDirectory, defaults to anime
                        name if not specified
  -L {German Dub,English Sub,German Sub}, --language {German Dub,English Sub,German Sub}
                        Language choice
  -p {Vidoza,Streamtape,VOE,Doodstream}, --provider {Vidoza,Streamtape,VOE,Doodstream}
                        Provider choice

Anime4K Options:
  -A {High,Low,Remove}, --anime4k {High,Low,Remove}
                        Set Anime4K optimised mode (High Eg.: GTX 1080, RTX 2070, RTX
                        3060, RX 590, Vega 56, 5700XT, 6600XT; Low Eg.: GTX 980, GTX
                        1060, RX 570, or Remove).

Syncplay Options:
  -sH SYNCPLAY_HOSTNAME, --syncplay-hostname SYNCPLAY_HOSTNAME
                        NOT IMPLEMENTED YET - Set syncplay hostname
  -sU SYNCPLAY_USERNAME, --syncplay-username SYNCPLAY_USERNAME
                        NOT IMPLEMENTED YET - Set syncplay username
  -sR SYNCPLAY_ROOM, --syncplay-room SYNCPLAY_ROOM
                        NOT IMPLEMENTED YET - Set syncplay room
  -sP SYNCPLAY_PASSWORD [SYNCPLAY_PASSWORD ...], --syncplay-password SYNCPLAY_PASSWORD [SYNCPLAY_PASSWORD ...]
                        Set a syncplay room password

Miscellaneous Options:
  -k, --aniskip         Skip intro and outro
  -K, --keep-watching   Continue watching
  -r [RANDOM_ANIME], --random-anime [RANDOM_ANIME]
                        Select random anime (default genre is "all", Eg.: Drama)
  -D, --only-direct-link
                        Output direct link
  -C, --only-command    Output command
  -x PROXY, --proxy PROXY
                        Set HTTP Proxy - E.g. http://0.0.0.0:8080
  -w, --use-playwright  Bypass fetching with a headless browser using Playwright instead
                        (EXPERIMENTAL!!!)

(back to top)

Dependencies

AniWorld Downloader requires the following Python packages:

• requests
• beautifulsoup4
• npyscreen
• colorlog
• py7zr
• packaging
• yt-dlp
• windows-curses (only for Windows users)

These packages are automatically installed when you set up AniWorld Downloader using pip.

(back to top)

TODO List

Completed Tasks

• Command-Line Improvements

  • Implement argparse for command-line argument parsing.
  • Refactor the code into modular Python files.
  • Display season and episode names instead of full links in selections.

• Logging and Proxy Support

  • Integrate the Python logging module.
  • Add support for proxy configurations.

• Automatic Installations

  • Automatically download and install the following on Windows & Linux:
    • mpv
    • yt-dlp
    • Syncplay

• Feature Enhancements

  • Implement movie support.
  • Configure Anime4K installation for:
    • Windows
    • MacOS
    • Linux
  • Add options for Syncplay room passwords.
  • Add mass file support.
  • Add Captcha bypass for headless browser fetches.
  • Allow changing final output folder
  • Add option to select a random anime optionally via genre
  • Add additional installation variants.

• Bug Fixes

  • Fix season episode count.
  • Fix yt-dlp progress bar on Windows.
  • Fix empty output for unavailable selected languages.
  • Use anime title instead of slug on the episode list.
  • Add time to cancel.
  • Fix output folder for mass processed files.
  • Fix Syncplay and mpv video desync issue (use Vidoza for Watch & Syncplay).
  • Automatically clean up old logs.
  • Separate the functionalities of aniskip and auto start & exit.
  • Sanitise echo strings on Windows
  • Add ascii art fallback on Windows 10
  • Fix mpv auto download on Windows 10

Upcoming Tasks

• New Stable Release
  • Full Testing
  • Bug fixing
• Complete codebase rewrite in new v.3 branch
  • Restructure argument handling by using globally accessible objects
  • Fix --only-direct-link language bug
  • Sort argument help section
  • Implement missing argument options
  • Syncplay support for other sites and local playback
  • Implement an ordered list for provider fallback in globals.py
  • Remove unnecessary dependencies
  • Fix Aniskip for seasons beyond the first
  • Optimize performance to reduce requests and eliminate duplicate function calls
  • Add generic fallback extractor
  • Anonymize logs by removing usernames
  • Add support for Doodstream
  • Add support for other sites

(back to top)

FAQ

Providers

Aniworld-Downloader currently supports three providers:

• VOE
• Vidoza
• Streamtape

Doodstream is not supported due to constant backend updates that block download attempts. While I initially had support for it, Doodstream's backend changes rendered my previous method obsolete.

Download and Viewing Recommendations

In older versions, the default provider for both downloading and watching with syncplay and mpv was Vidoza. However, since Vidoza and Streamtape throttle download speeds, I recommend using VOE for downloads, as it can fully utilize your bandwidth.

Drawback of VOE:

• Many fragments can be invalid, affecting playback with mpv. While downloads using yt-dlp work fine, invalid fragments may cause scenes to skip or glitch, leading to noticeable disruptions, especially during syncplay, where different fragment issues among viewers can result in annoying jumps.

Current Recommendations:

• Download in this order:
  VOE > Vidoza > Streamtape

• For viewing in mpv or syncplay:
  Vidoza > Streamtape > VOE

s.to & bs.to Support

I previously had support for s.to in a separate branch, but it is now unmaintained and untested. Currently, I do not plan to re-implement support for s.to, as I've focused on stabilizing the existing code. Before adding new providers, I need to streamline the backend, which is somewhat messy due to redundant functions and fetches from recent feature additions.

Note on Adding s.to Support:

• Adding s.to support would not be difficult—it only requires one fewer fetch than Aniworld's current method to access streaming providers. If anyone is interested in contributing to this effort, I would be happy to merge the addition.

There are already other tools that support s.to. For terminal-based viewing of s.to, check out my friend's project called gucken—he’s doing great work there.

Regarding Aniworld’s claim of hosting 1,000+ license-free anime, it’s worth noting that they also stream new shows that may require subscriptions elsewhere. Supporting s.to could mean indirectly accessing copyrighted content, such as Netflix originals. As I do not host any content but fetch it directly from streaming providers, I am not liable for any issues arising from downloading anime.

Feel free to contribute! Any help is appreciated, and I’d be happy to merge in support for s.to or bs.to if it gets added.

(back to top)

Credits

• mpv: Media player used for streaming.
• yt-dlp: Tool for downloading videos.
• Syncplay: Service for synchronized playback with friends.
• Anime4K: A high-quality real-time upscaler for anime video.

(back to top)

Contributing

Contributions to AniWorld Downloader are welcome! Your input helps improve the project, whether it’s through:

• Reporting bugs
• Suggesting features
• Submitting pull requests

Contributors

• Lulu (since Sep 14, 2024)
  

• Tmaster055 (since Oct 21, 2024)
  

(back to top)

License

This project is licensed under the MIT License.
For more details, see the LICENSE file.

(back to top)

Support

I’ve received several reports from users experiencing unexpected menu quits. Recently, streaming providers have started blocking IP addresses from downloading. You can bypass this by using a VPN. You might try using the --use-playwright option instead, though it's still experimental and may not be very effective. Additionally, run aniworld with the --debug flag.

This will typically reveal a timeout error, indicating the domain couldn’t be reached or another issue.

How to Get Help

If you still need assistance with AniWorld Downloader, you can:

• File a report via the GitHub Issues page.
• Contact me directly via email at [email protected], on Matrix @phoenixthrush:matrix.org, or on Discord phoenixthrush.

While I do respond to emails, opening a GitHub issue is preferable, even for installation questions, so others can find solutions too. However, I’m still happy to help via email if you prefer.

If you enjoy AniWorld Downloader and want to support the project, please consider starring the repository on GitHub. It’s a small gesture that means a lot and motivates me to keep improving the project.

Thank you for your support and feedback!

(back to top)

Star History

(back to top)