{"id":13624048,"url":"https://github.com/justfoolingaround/animdl","last_synced_at":"2025-05-15T09:04:29.846Z","repository":{"id":37575859,"uuid":"358163720","full_name":"justfoolingaround/animdl","owner":"justfoolingaround","description":"A highly efficient, fast, powerful and light-weight anime downloader and streamer for your favorite anime.","archived":false,"fork":false,"pushed_at":"2024-06-13T19:16:54.000Z","size":2555,"stargazers_count":1356,"open_issues_count":58,"forks_count":111,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-03T20:08:54.726Z","etag":null,"topics":["anime","download","python","scraper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justfoolingaround.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"justfoolingaroundkr"}},"created_at":"2021-04-15T07:15:23.000Z","updated_at":"2025-04-02T15:29:47.000Z","dependencies_parsed_at":"2023-02-15T16:45:24.109Z","dependency_job_id":"ca5b986e-7bee-485f-9581-5dc9cc5d3cb2","html_url":"https://github.com/justfoolingaround/animdl","commit_stats":{"total_commits":316,"total_committers":15,"mean_commits":"21.066666666666666","dds":"0.10126582278481011","last_synced_commit":"2a0d6ae86eb0b63dcb340f5cddbe5214f47b85e9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justfoolingaround%2Fanimdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justfoolingaround%2Fanimdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justfoolingaround%2Fanimdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justfoolingaround%2Fanimdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justfoolingaround","download_url":"https://codeload.github.com/justfoolingaround/animdl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248441905,"owners_count":21104100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anime","download","python","scraper"],"created_at":"2024-08-01T21:01:38.199Z","updated_at":"2025-04-11T16:39:35.858Z","avatar_url":"https://github.com/justfoolingaround.png","language":"Python","readme":"\u003ch1 align=\"center\"\u003e\u003cimg src=\"https://capsule-render.vercel.app/api?type=soft\u0026fontColor=703ee5\u0026text=justfoolingaround/animdl\u0026height=150\u0026fontSize=60\u0026desc=Ridiculously%20efficient,%20fast%20and%20light-weight.\u0026descAlignY=75\u0026descAlign=60\u0026color=00000000\u0026animation=twinkling\"\u003e\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003csup\u003eA highly efficient, powerful and fast anime scraper.\u003c/sup\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./animdl_demo.gif\"\u003e\u003c/p\u003e\n\n***\n\n## Overview\n\n*   [Installation](#installation)\n    1.  [PIP Installation](#installation)\n    2.  [Source Code Download](#installation)\n*   [Support](#support)\n*   [Usage](#usage)\n    *   [`stream` / `download` / `grab`](#stream--download--grab)\n    *   [`-r` / `--range`](#-r----range-argument)\n    *   [`--index`](#--index-argument)\n    *   [`-s` / `--special`](#-s----special-argument)\n    *   [`-q` / `--quality`](#-q----quality-argument)\n    *   [**More** usage](#conclusion)\n*   [Providers](#providers)\n*   [Configurations](#configurations)\n    *   [Setting up providers](#setting-up-providers)\n    *   [Quality selection](#quality-selection)\n    *   [Player selection](#player-selection)\n    *   [`ffmpeg` set-up](#ffmpeg-set-up)\n    *   [Discord Rich Presence set-up](#discord-rich-presence-set-up)\n    *   [`fzf` set-up](#fzf-set-up)\n    *   [Schedule set-up](#schedule-set-up)\n*   [Contributing to the project](#contributing-to-the-project)\n*   [Project Disclaimer](#project-disclaimer)\n*   [In a nutshell](#in-a-nutshell)\n*   [Code redistribution](#code-redistribution)\n*   [From the author](#from-the-author)\n*   [Honourable mentions](#honourable-mentions)\n    *   [Similar Projects](#similar-projects)\n    *   [Internal Dependencies](#internal-dependencies)\n*   [Sponsoring the project](#sponsoring-the-project)\n\n## Installation\n\nThis project can be installed on to your device via different mechanisms, these mechanisms are listed below in the order of ease.\n\n1.  PIP Installs Packages **aka** PIP Installation\n\n    ```sh\n    pip install animdl\n    ```\n\n2.  Installation from source\n\n    First ensure [Poetry is installed](https://python-poetry.org/docs/#installation).\n\n    Then run the following command:\n\n    ```sh\n    git clone https://www.github.com/justfoolingaround/animdl.git \\\n    \u0026\u0026 cd animdl \\\n    \u0026\u0026 poetry build \\\n    \u0026\u0026 pip install animdl \\\n    \u0026\u0026 cd ..\n    ```\n\n## Support\n\nYou can contact the developer directly via this [email](mailto:kr.justfoolingaround@gmail.com). However, the most recommended way is to head to the discord server.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://discord.gg/gaX2Snst2j\"\u003e\n\u003cimg src=\"https://invidget.switchblade.xyz/gaX2Snst2j\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\nIf you run into issues or want to request a new feature, you are encouraged to make a GitHub issue, won't bite you, trust me.\n\n## Usage\n\n```txt\nUsage: animdl [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  download  Download your favorite anime by query.\n  grab      Stream the stream links to the stdout stream for external usage.\n  schedule  Know which animes are going over the air when.\n  search    Search for an anime in the provider.\n  stream    Stream your favorite anime by query.\n```\n\nThe `stream` option is disabled automatically if the project cannot find any of the supported streamers.\n\n### `stream` / `download` / `grab`\n\nThese commands are the main set of command in the project. All of them scrape the target site, the only difference is how it is used.\n\n*   The `stream` option tosses the stream url to a player so that you can seamlessly binge your anime.\n    *   Streaming supports Discord Rich Presence with `pypresence`.\n\n*   The `download` option downloads the anime to your local machine.\n    *   Downloading is done in the directory where you run the project.\n    *   `-d` flag can be used to specify a download folder as well.\n    *   [Internet Download Manager](https://internetdownloadmanager.com/) is supported and can be used via `--idm` flag. This downloader cannot download HLS streams.\n    *   The project cannot modify the content type. That means, videos in the `ts` format need to be converted to other formats externally post download.\n    *   The downloading process cannot be controlled.\n        *   If download speed fluctuates, it is a server-side problem. The project cannot \"fix\" it.\n        *   If the download is slow, it is based on the server's upload speed. The project cannot \"fix\" it. **Speedtests are not reliable and their results will not correspond to the download speeds obtained through the project.**\n    *   The project utilises the fastest and the most straight-forward way to download, there is no further optimisation, period.\n\n*   The `grab` option simply streams the stream url to the stdout stream.\n    *   This is useful for external usage and testing.\n\n```sh\nanimdl stream \"One Piece\" \n```\n\n\u003cp align=\"center\"\u003e\n\u003csub\u003e\nProviders can be specified by using provider prefix, \u003ccode\u003e9anime:One Piece\u003c/code\u003e, will use the 9Anime provider.\n\u003c/sub\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003csub\u003e\nYou can specify direct urls to the provider; the project will automatically detect the provider and continue scraping. This method ignores searching.\u003csub\u003e\u003c/p\u003e\n\n### `-r` / `--range` argument\n\nThis argument is shared by **stream**, **download** and **grab**, it can be used to hand over custom ranges for selecting episodes.\n\n*   This argument constructs a check for the episodes, hence, will not throw error if the episode count does not meet the scraping count.\n*   This argument can be used in **reverse** order, the constructer will automatically fix the order.\n*   Range intersections will not cause issues.\n*   `1` will be treated as a singular range from 1 to 1.\n*   `1-2` will be treated as a range from 1 to 2.\n*   `1-2,230-340` will be treated as two different checks. The first check will be from `1` to `2`, the second from `230` to `340`.\n*   You can use any separators, the project will automatically parse your range string.\n\n### `--index` argument\n\nThis argument is shared by **stream**, **download** and **grab**, it can be used to automatically select the search result. The default argument for index is `1`, that is, the first stream.\n\n`--index 2` will automatically select the second search result without prompt.\n\n### `-s` / `--special` argument\n\nThis argument is shared by **stream** and **download**, it can be used to hand over the latest episode of the anime by using `-s latest`. Similarly, the latest 2 episodes can be selected via `latest-2`.\n\n*   This argument is compatible with `-r`, you will get the last episode of the range.\n\n### `-q` / `--quality` argument\n\nThis argument is incredibly powerful and can be used to select streams from their **attributes**.\n\n*   `1080` will select the stream with the resolution of 1080.\n*   `1080/worst` will do the above but will also select the worst quality stream if that stream is not available.\n*   `best[title]` will select the best stream that has the `title` attribute.\n*   `best[title=r'^DUB']` will select the stream with the `title` attribute that matches the regular expression. If `r` is not used, the expression will be treated as a literal string.\n*   The normal integers can be substituted with `best` and `worst` for special parsing.\n*   You need not mention the quality in the argument if you just want an attribute.\n\nYou can find out what attributes are available for each stream by using the `grab` command.\n\n```json\n[\n  {\n    \"stream_url\": \"https://yqwym.vizcloud.digital/simple/EqPFI_kQBAro1HhYl67rC8UuoVwHubb7CkJ7rqk+wYMnU94US2El/br/list.m3u8#.mp4\",\n    \"headers\": {\n      \"referer\": \"https://vizcloud.digital/embed/83P7OX0N8PLE\"\n    }\n  },\n  {\n    \"stream_url\": \"https://yqwym.vidstream.pro/EqPVIPsMWl322yVezviuGdNz9wsVp_2ySFow5Od52MBlQ9QQG34s9aQ0yhbkTfyI+tzdG4991O3X4fVqACOikmeZRvMNGrBeQ5aivXxFIkYzNJElHAM1icyfowvCviiceQevRCxV9F7i7CIYt0hIz61716gsQxXskJ6eV4Gg4_OC/br/list.m3u8\",\n    \"headers\": {\n      \"referer\": \"https://vizcloud.digital/embed/83P7OX0N8PLE\"\n    }\n  },\n  {\n    \"stream_url\": \"https://yzqq.mcloud.to/12a3c523f910040ae8d4785897aeeb0bc52ea15c07b9b6fb0a427baea96ed0842f54d0184c6820e9f935c248a146eb8df28cc21a817ad2e8c0eefd680420a692659945f21618bd454698bcbf6e42394f3d4ee734180c3281ce9bb00fcaa2298e7913aa40036bbb0abaf07046a14442c2f32c9df66b1a/r/list.m3u8\",\n    \"headers\": {\n      \"referer\": \"https://mcloud.to/embed/k18xp6\"\n    }\n  }\n]\n```\n\nThis is the prettified output of `animdl grab \"9anime:one piece\"`, and the stream has `headers` and `stream_url` attributes.\n\nIf you feel that a particular stream is fast enough for you, `-q [stream_url=r'.+mcloud\\.to.+']`\u003csub\u003e(or equivalent, this is just for testing)\u003c/sub\u003e will select that stream.\n\n### Conclusion\n\nThis project posses powerful commands and arguments to aid them, there are **many** arguments that aren't specified here but are available in the project. This is done because these commands are advanced usage commands which may just cause confusion. Feel free to ask about them.\n\n## Providers\n\nPlease head to [animdl's official provider benchmarks](https://github.com/justfoolingaround/animdl-provider-benchmarks).\n\nThe images in that repository are automatically updated every few hours, hence, please be aware that the developers already know what's broken.\n\nSome providers may not work due to DDoS protection services. We try our best to fix what's fixable. There are plenty of alternatives even if one goes down in the project.\n\n\u003cp align=\"center\"\u003e\u003cb\u003eThe project contains providers that aren't mentioned here. This is intentional.\u003c/b\u003e\u003c/p\u003e\n\n## Configurations\n\nConfiguration files can be globally or locally be specified.\n\nYou can use the `ANIMDL_CONFIG` environment variable to specify a configuration file on a global level.\n\nElse, a file with the name `animdl_config.yml` in the working directory will be used if available.\n\nFuthermore, the configuration files can be globally placed at:\n\n*   Windows:\n    *   `%USERPROFILE%/.animdl/config.yml`\n*   Anything else:\n    *   `$HOME/.config/animdl/config.yml`\n\nOnly a singular configuration file in the above priority order is used, configurations aren't merged.\n\n### Setting up providers\n\nYou can specify a default provider using the `default_provider` configuration option.\n\n```yml\ndefault_provider: animixplay\n```\n\nThis project uses a standardised url **per** provider. This makes the project capable of using different **official** proxies of the same provider.\n\nThis can be specified via `site_urls` by using the following configuration.\n\n```yml\nsite_urls:\n    animixplay: https://www.animixplay.to/\n```\n\n### Quality selection\n\nYou can specify a default quality using the `quality_string` configuration option.\n\n```yml\nquality_string: best[subtitle]/best\n```\n\n### Player selection\n\nYou can specify a default player using the `default_player` configuration option.\n\n```yml\ndefault_player: mpv\n```\n\nYou can change player attributes, such as, what the `executable` is and what `opts` are to be passed during the player call.\n\n```yml\nplayers:\n    mpv:\n        executable: mpv\n        opts: []\n```\n\nIf the executable is found, the player will be eligible for use.\n\nCurrently supported players are:\n\n*   [`mpv`](https://mpv.io/)\n*   [`vlc`](https://www.videolan.org/vlc/)\n*   [`iina`](https://iina.io/)\n*   [`celluloid`](https://celluloid-player.github.io)\n*   [`ffplay`](https://www.ffmpeg.org/ffplay.html)\n*   `android` (Android Player, only available **when** there aren't any headers for the stream)\n\n### ffmpeg set-up\n\nYou can make the project force `ffmpeg` for HLS downloading (awfully slow) and merging subtitles for downloads when external subtitles are available.\n\n```yml\nffmpeg:\n    executable: ffmpeg\n    hls_download: false\n    submerge: true\n```\n\n### Discord Rich Presence set-up\n\nThis project supports RPC clients, this can be enabled **only** from the configuration. To use this, you must have `pypresence` installed via:\n\n```sh\npip install pypresence\n```\n\n```yml\ndiscord_presence: true\n```\n\n### fzf set-up\n\nYou can force the project search prompts to use [`fzf`](https://github.com/junegunn/fzf).\n\nThis is an incredibly powerful tool and can enchance the user experience by a lot. For obvious reasons, you need to have it installed and on PATH (can be configured to use an executable path as well).\n\n```yml\nfzf:\n    executable: fzf\n    opts: []\n    state: true\n```\n\nUsers can benefit by using `fzf` and `animdl stream twist:` as this allows them to browse the **entire** Twist library with a heavenly interface.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://media.discordapp.net/attachments/856404208445292545/972471580640804894/unknown.png\"\u003e\u003c/p\u003e\n\nThe above screenshot has `fzf`'s user theme configured.\n\n### Schedule set-up\n\nThe project can be used to view the schedule of the upcoming anime for the week with the user cherished time and date formats.\n\n```yml\nschedule:\n    site_url: https://graphql.anilist.co/ # DO NOT CHANGE UNLESS YOU KNOW WHAT YOU'RE DOING\n    date_format: \"%b. %d, %A\"\n    time_format: \"%X\"\n```\n\nPlease refer to [Python `datetime.strftime` documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior) for the available formats.\n\n## Contributing to the project\n\nIt is **not** recommended for any average Python developers to engage with the project codebase as the mechanisms used are extremely high level and requires greater understanding of the codebase and Python in general.\n\nIf you wish to, you can contribute to the project by submitting a pull request.\n\nThe best way to contribute would be to suggest the developer a provider or a feature, more better if you can show a logic of how that can be done, you'll be mentioned and thanked!\n\n## Project disclaimer\n\nThe disclaimer of the project can be found [here](./disclaimer.md).\n\n## In a nutshell\n\n*   Abuses the developer's braincells in scraping to give about the fastest and most efficient toolset.\n*   Brings about a highly powerful codebase which is just about appropriate for scraping.\n*   Does not use any heavy dependencies by default.\n*   Does not use `selenium` **or** JavaScript evaluators for scraping.\n*   Integrates powerful internal tools such as a HLS downloader.\n*   Is maintained, **heavily** as far as possible.\n\n## Code redistribution\n\nFeel free to do so and take references from the codebase. You need not give credit to the project or [justfoolingaround](https://github.com/justfoolingaround), however, please do a `blame` check and see if the contributor wants to be credited.\n\n## From the author\n\nI just maintain this project for my gratification. I'd love to hear from you about your projects and problems (even unrelated to the project), so feel free to contact [me](https://github.com/justfoolingaround).\n\nI'm glad you're here!\n\n## Honourable mentions\n\n### Similar Projects\n\n*   Shell\n    *   [ani-cli](https://github.com/pystardust/ani-cli)\n*   Kotlin\n    *   [Cloudstream-3](https://github.com/Lagradost/cloudstream-3)\n    *   [Saikou](https://github.com/saikou-app/saikou)\n\nThese are actively maintained projects, each of which has its own unique features and functionality.\n\n### Internal Dependencies\n\n*   Core\n    *   [encode/httpx](https://github.com/encode/httpx)\n    *   [Legrandin/pycryptodome](https://github.com/Legrandin/pycryptodome)\n    *   [pallets/click](https://github.com/pallets/click)\n    *   [tqdm/tqdm](https://github.com/tqdm/tqdm)\n    *   [lxml/lxml](https://github.com/lxml/lxml)\n*   Optional\n    *   [junegunn/fzf](https://github.com/junegunn/fzf)\n    *   [qwertyquerty/pypresence](https://github.com/qwertyquerty/pypresence)\n\nThe project would definitely not be complete or even in a working state if it weren't for these dependencies.\n\n## Sponsoring the project\n\nUsually sponsors means funding which consequently means money but for the project, it means stars. Feel free to star the project if you think it is worthy of one. Moreover, you can just talk, banter and argue with the developer as that way you'll be paying with your time.\n\n\u003cp align=\"center\"\u003e\n\u003ccode\u003e\n\u003ca href=\"https://www.codacy.com/gh/justfoolingaround/animdl/dashboard\"\u003e\n\u003cimg src=\"https://app.codacy.com/project/badge/Grade/a3a66c513f6949fb9f4aeb5fd26db937\"\u003e\n\u003c/a\u003e\n\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003csup\u003eYou are an absolute legend, keep being awesome!\u003c/sup\u003e\n\u003c/p\u003e\n","funding_links":["https://ko-fi.com/justfoolingaroundkr"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustfoolingaround%2Fanimdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustfoolingaround%2Fanimdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustfoolingaround%2Fanimdl/lists"}