Miirakuru 「ミイラクル」

Easily sync your Anime and Manga to several supported sites via Discord, only for self-host!

About

Miirakuru (Japanese: ミイラクル [mʲiːꜜɾakɯɾɯ̥], wordplay of Miracle「ミラクル」 and Mummy 「ミイラ」) is a Discord bot that assist you in tracking your currently watching anime to MyAnimeList directly from Discord. It also able to sync to multiple platforms thanks to AnimeAPI.

Build with interactions.py, this bot uses slash command (/) as main interface to the software instead of prefixed/text command.

Miirakuru does not have invitable link, and anyone who interested using it must self-host this bot instead.

Planned Features

General

• MyAnimeList OAuth2 Authentication
• Auto Backup data
• Show anime information
• Update tracking data
• Logs activity
• Broadcast user activity to a channel from RSS/Atom
• Use TOML for configuration
• Save secret data to keyring available on the system

Anime Sync Databases

• Main

  • MyAnimeList
  • AniList
  • Kitsu
  • SIMKL

• One-Way Sync

  • Annict
  • Bangumi
  • Shikimori
  • Trakt — Unless BetterAnimeTraktMapper finished, Trakt will be one-way sync.

• Experimental

  • Kaize — Trying to mock browser API Request
  • Notify.moe — User may require to provide their own Cookie value.
  • Otak Otaku — Trying to mock browser API Request

• Won't Supported

  [!NOTE]

  All of the sites below does not have API, and using mock environment will required CAPTCHA.

  Using cloudscraper could solve this, but it can block async request for the bot to run.

  • Anime-Planet — No API, using mock environment required CAPTCHA.
  • AniDB — API uses UDP as main interface rather HTTPS, which could cause unexpected issues raised from unexperienced developer (@nattadasu).
  • aniSearch — No API, using mock environment required CAPTCHA.
  • LiveChart — Can't fool User-Agent; it would ask CAPTCHA.
  • Nautiljon — No API, using mock environment required CAPTCHA.

Manga Sync Databases

• Main
  • MyAnimeList
  • AniList
  • Kitsu
  • MangaUpdates
• One-Way Sync
  • Bangumi
• Experimental
  • Kaize — Trying to mock browser API Request
  • Mangadex — Until MD team allows OAuth with Client Session with their new API and Authorization method, it might be impossible for now.
• Won't t Supported
  • Anime-Planet — No API, using mock environment required CAPTCHA.
  • aniSearch — No API, using mock environment required CAPTCHA.
  • Nautiljon — No API, using mock environment required CAPTCHA.

Methodology

As each platform has different way to store their data and the assigned ID, this becomes a challenge to sync the data between platforms. To solve this, Miirakuru uses a method called ID Mapping.

In some situation, the ID from one platform can be used to get the ID from another platform interchangeably. For example, the ID from MyAnimeList can be used to get the ID from Shikimori, and vice versa. This is because Shikimori retrieves their data from MyAnimeList.

However, this is not always the case. For example, the ID from MyAnimeList cannot be used to get the ID from AniList, and vice versa. To solve this, we need to use a third-party API to get the ID from another platform. If the API does not support the platform, then we need to ask the user to provide the ID from the platform by searching from the platform itself or provide the ID from the platform.

sequenceDiagram
  actor user as User on Discord
  participant root as Miirakuru
  participant ani as AnimeAPI
  participant site as Site

  alt Adding Anime to Database
    user->>root: Add anime
    activate user
    par Getting ID
      root->>+ani: Get anime ID
      activate ani
      ani-->>root: Post anime ID
    and if ID is not found
      root->>+site: Get anime ID
      site-->>-root: Post anime ID
    and If site does not support API
      site-->>user: Ask user to provide anime ID
      user->>root: Provide anime ID
    end
    deactivate ani
    root->>root: Add anime to database with UUID
    alt If user activates MyAniLi sync
      root->>+site: Save encrypted JSON to title's comment/note
      site-->>-root: Confirms if anime is added
    end
    root-->>user: Confirms if anime is added
    deactivate user
  end

  alt Update Anime in Database
    user->>root: Update anime
    activate user
    par Update data
      root->>site: Post updated data
      activate site
      site-->>root: Confirms if anime is updated
    and If user activates MyAniLi sync
      root->>+site: Save encrypted JSON to title's comment/note, if modified
      site-->>-root: Confirms if anime is updated
    end
    deactivate site
    root-->>user: Confirms if anime is updated
    deactivate user
  end

  alt Showing Anime Information
    user->>root: Show anime
    activate user
    Note over root: Priority: AniList, MyAnimeList, MangaUpdates, Kitsu, SIMKL, [...]
    root->>root: Pick platform with highest priority
    root->>site: Get anime information
    activate site
      site-->>root: Post anime information
    deactivate site
    root-->>user: Post anime information
    deactivate user
  end

Third-Party Compatibility

Miirakuru allows third-party to access the API to manage user's library via HTTP REST request. The API is available on /api/v1/ endpoint.

Additionally, Miirakuru also has webhook support to Taiga and similar application to update user's library without using Discord bot. Miirakuru will aim to support Jellyfin and Kodi in the future.

Then, if user opted in MyAniLi sync, Miirakuru will save the required data by MyAniLi to the title's comment/note for each platform signed in.

Set-Up

Prerequisites

Before installing and running the software, you must have those required packages/apps to be installed first:

1. Git
2. Python 3.10 or greater

And your system must fulfill these requirements:

• Windows:
  • Windows 10 or greater
• Linux:
  • systemd as init system
  • FreeDesktop.org-compliant Secret Service implementation.
• macOS:
  • macOS 11 (Big Sur) or greater

Additionally, you can install pipenv as dependency manager instead of using virtualenv and pip.

Cloning and Installing Required Packages

1. To make the software available on your machine, open Terminal and write as following:

   git clone https://github.com/nattadasu/miirakuru.git
   cd miirakuru

   Or, using GitHub CLI:

   gh repo clone nattadasu/miirakuru
   cd miirakuru

2. Depending which dependency manager you use, install required packages

   • Using pipenv:

     pipenv install

   • Using virtualenv and pip:

     python -m venv venv
     # depending on what OS and shell:
     # bash:
     source ./venv/bin/activate
     # PowerShell, Windows:
     #   & ./venv/Scripts/activate.ps1
     # PowerShell, *nix:
     #   & ./venv/bin/activate.ps1
     pip install -U -r requirements.txt

3. Copy .env.example as .env, and fill all fields

4. Run the software

   • Using pipenv:

     pipenv run main.py

   • Using virtualenv:

     python main.py

License

This software is licensed under GNU Affero General Public License v3.0.

You can modify and redistribute this software as long as you follow the license terms, and any modified version of this software must be released under the same license.

Acknowledgements

This software was inspired or made possible by the following:

• infanf/myanili — inspiration for this software to allows user to sync their main MyAnimeList list to other platforms
• interactions.py — the library used to build this bot
• nattadasu/animeApi — the API used to get ID from other
• nattadasu/ryuuRyuusei (especially rewrite version) — nattadasu's first bot, basically
• YuuCorp/Yuuko and White Cat — Bots that allow user to update their list (from AniList and MyAnimeList respectively) via Discord platforms