diff --git a/README.md b/README.md index 1b2a37b..a8ec76e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # crunchy-cli -A pure [Rust](https://www.rust-lang.org/) CLI for [Crunchyroll](https://www.crunchyroll.com). +👇 A Command-line downloader for Crunchyroll [Crunchyroll](https://www.crunchyroll.com).

@@ -26,23 +26,20 @@ A pure [Rust](https://www.rust-lang.org/) CLI for [Crunchyroll](https://www.crun

Usage 🖥️ • - Disclaimer 📜 + Disclaimer 📜 • License ⚖

> We are in no way affiliated with, maintained, authorized, sponsored, or officially associated with Crunchyroll LLC or any of its subsidiaries or affiliates. -> The official Crunchyroll website can be found at [crunchyroll.com](https://crunchyroll.com/). - -> This README belongs to the _master_ branch which is currently under heavy development towards the next major version (3.0). -> It is mostly stable but some issues may still occur. -> If you do not want to use an under-development / pre-release version, head over to the _[golang](https://github.com/crunchy-labs/crunchy-cli/tree/golang)_ branch which contains the EOL but last stable version (and documentation for it). +> The official Crunchyroll website can be found at [www.crunchyroll.com](https://www.crunchyroll.com/). ## ✨ Features - Download single videos and entire series from [Crunchyroll](https://www.crunchyroll.com). - Archive episodes or seasons in an `.mkv` file with multiple subtitles and audios. - Specify a range of episodes to download from an anime. +- Search through the Crunchyroll collection and return metadata (title, duration, direct stream link, ...) of all media types. ## 💾 Get the executable @@ -50,12 +47,25 @@ A pure [Rust](https://www.rust-lang.org/) CLI for [Crunchyroll](https://www.crun Check out the [releases](https://github.com/crunchy-labs/crunchy-cli/releases) tab and get the binary from the latest (pre-)release. -### ❄️ The nix way +### 📦 Get it via a package manager -This requires [nix](https://nixos.org) and you'll probably need `--extra-experimental-features "nix-command flakes"` depending on your configurations. -```shell -$ nix github:crunchy-labs/crunchy-cli -``` +- [AUR](https://aur.archlinux.org/) + + If you're using Arch or an Arch based Linux distribution you are able to install our [AUR](https://aur.archlinux.org/) package. + You need an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers) like [yay](https://github.com/Jguer/yay) to install it. + ```shell + # this package builds crunchy-cli manually (recommended) + $ yay -S crunchy-cli + # this package installs the latest pre-compiled release binary + $ yay -S crunchy-cli-bin + ``` + +- [Nix](https://nixos.org/) + + This requires [nix](https://nixos.org) and you'll probably need `--extra-experimental-features "nix-command flakes"`, depending on your configurations. + ```shell + $ nix github:crunchy-labs/crunchy-cli + ``` ### 🛠 Build it yourself @@ -64,7 +74,9 @@ This requires [git](https://git-scm.com/) and [Cargo](https://doc.rust-lang.org/ ```shell $ git clone https://github.com/crunchy-labs/crunchy-cli $ cd crunchy-cli +# either just build it (will be available in ./target/release/crunchy-cli)... $ cargo build --release +# ... or install it globally $ cargo install --force --path . ``` @@ -74,47 +86,101 @@ $ cargo install --force --path . crunchy-cli requires you to log in. Though you can use a non-premium account, you will not have access to premium content without a subscription. -You can authenticate with your credentials (username:password) or by using a refresh token. +You can authenticate with your credentials (user:password) or by using a refresh token. - Credentials - - ```shell - $ crunchy --credentials "user:password" - ``` + + ```shell + $ crunchy-cli --credentials "user:password" + ``` - Refresh Token - - To obtain a refresh token, you have to log in at [crunchyroll.com](https://www.crunchyroll.com/) and extract the `etp_rt` cookie. - The easiest way to get it is via a browser extension which lets you export your cookies, like [Cookie-Editor](https://cookie-editor.cgagnier.ca/) ([Firefox](https://addons.mozilla.org/en-US/firefox/addon/cookie-editor/) / [Chrome](https://chrome.google.com/webstore/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)). - When installed, look for the `etp_rt` entry and extract its value. - - ```shell - $ crunchy --etp-rt "4ebf1690-53a4-491a-a2ac-488309120f5d" - ``` + + To obtain a refresh token, you have to log in at [crunchyroll.com](https://www.crunchyroll.com/) and extract the `etp_rt` cookie. + The easiest way to get it is via a browser extension which lets you export your cookies, like [Cookie-Editor](https://cookie-editor.cgagnier.ca/) ([Firefox](https://addons.mozilla.org/en-US/firefox/addon/cookie-editor/) / [Chrome](https://chrome.google.com/webstore/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)). + When installed, look for the `etp_rt` entry and extract its value. + ```shell + $ crunchy-cli --etp-rt "4ebf1690-53a4-491a-a2ac-488309120f5d" + ``` - Stay Anonymous - - Skip the login check: - - ```shell - $ crunchy --anonymous - ``` + + Login without an account (you won't be able to access premium content): + ```shell + $ crunchy-cli --anonymous + ``` + +### Global settings + +You can set specific settings which will be + +- Verbose output + + If you want to include debug information in the output, use the `-v` / `--verbose` flag to show it. + ```shell + $ crunchy-cli -v + ``` + This flag can't be used with `-q` / `--quiet`. + +- Quiet output + + If you want to hide all output, use the `-q` / `--quiet` flag to do so. + This is especially useful if you want to pipe the output video to an external program (like a video player). + ```shell + $ crunchy-cli -q + ``` + +- Language + + By default, the resulting metadata like title or description are shown in your system language (if Crunchyroll supports it, else in English). + If you want to show the results in another language, use the `--lang` flag to set it. + ```shell + $ crunchy-cli --lang de-DE + ``` + +- Experimental fixes + + Crunchyroll constantly changes and breaks its services or just delivers incorrect answers. + The `--experimental-fixes` flag tries to fix some of those issues. + As the *experimental* in `--experimental-fixes` states, these fixes may or may not break other functionality. + ```shell + $ crunchy-cli --experimental-fixes + ``` + For an overview which parts this flag affects, see the [documentation](https://docs.rs/crunchyroll-rs/latest/crunchyroll_rs/crunchyroll/struct.CrunchyrollBuilder.html) of the underlying Crunchyroll library, all functions beginning with `stabilization_` are applied. + +- Proxy + + The `--proxy` flag supports https and socks5 proxies to route all your traffic through. + This may be helpful to bypass the geo-restrictions Crunchyroll has on certain series. + ```shell + $ crunchy-cli --proxy socks5://127.0.0.1:8080 + ``` + Make sure that proxy can either forward TLS requests, which is needed to bypass the (cloudflare) bot protection, or that it is configured so that the proxy can bypass the protection itself. ### Login -crunchy-cli can store your session, so you don't have to authenticate every time you execute a command. - -Note that the `login` keyword has to be used *last*. +The `login` command can store your session, so you don't have to authenticate every time you execute a command. ```shell -$ crunchy --etp-rt "4ebf1690-53a4-491a-a2ac-488309120f5d" login +# save the refresh token which gets generated when login with credentials. +# your username/email and password won't be stored at any time on disk +$ crunchy-cli login --credentials "user:password" +# save etp-rt cookie +$ crunchy-cli login --etp-rt "4ebf1690-53a4-491a-a2ac-488309120f5d" ``` -With the session stored, you do not need to use `--credentials` / `--etp-rt` anymore. This does not work with `--anonymous`. +With the session stored, you do not need to pass `--credentials` / `--etp-rt` / `--anonymous` anymore when you want to execute a command. ### Download +The `download` command lets you download episodes with a specific audio language and optional subtitles. + **Supported urls** - Single episode (with [episode filtering](#episode-filtering)) ```shell - $ crunchy download https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + $ crunchy-cli download https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome ``` - Series (with [episode filtering](#episode-filtering)) ```shell - $ crunchy download https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli download https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` **Options** @@ -123,7 +189,7 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Set the audio language with the `-a` / `--audio` flag. This only works if the url points to a series since episode urls are language specific. ```shell - $ crunchy download -a de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli download -a de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is your system locale. If not supported by Crunchyroll, `en-US` (American English) is the default. @@ -132,16 +198,15 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Besides the audio, you can specify the subtitle language by using the `-s` / `--subtitle` flag. The subtitles will be burned into the video track (cf. [hardsub](https://www.urbandictionary.com/define.php?term=hardsub)) and thus can not be turned off. ```shell - $ crunchy download -s de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli download -s de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is none. - Output template Define an output template by using the `-o` / `--output` flag. - If you want to use any other file format than [`.ts`](https://en.wikipedia.org/wiki/MPEG_transport_stream) you need [ffmpeg](https://ffmpeg.org/). ```shell - $ crunchy download -o "ditf.mp4" https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + $ crunchy-cli download -o "ditf.mp4" https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome ``` Default is `{title}.mp4`. See the [Template Options section](#output-template-options) below for more options. @@ -149,20 +214,54 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any The resolution for videos can be set via the `-r` / `--resolution` flag. ```shell - $ crunchy download -r worst https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + $ crunchy-cli download -r worst https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome ``` Default is `best`. +- FFmpeg Preset + + You can specify specific built-in presets with the `--ffmpeg-preset` flag to convert videos to a specific coding while downloading. + Multiple predefined presets how videos should be encoded (h264, h265, av1, ...) are available, you can see them with `crunchy-cli download --help`. + If you need more specific ffmpeg customizations you could either convert the output file manually or use ffmpeg output arguments as value for this flag. + ```shell + $ crunchy-cli downlaod --ffmpeg-preset av1-lossless https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + ``` + +- Skip existing + + If you re-download a series but want to skip episodes you've already downloaded, the `--skip-existing` flag skips the already existing/downloaded files. + ```shell + $ crunchy-cli download --skip-existing https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + ``` + +- Yes + + Sometimes different seasons have the same season number (e.g. Sword Art Online Alicization and Alicization War of Underworld are both marked as season 3), in such cases an interactive prompt is shown which needs user further user input to decide which season to download. + The `--yes` flag suppresses this interactive prompt and just downloads all seasons. + ```shell + $ crunchy-cli download --yes https://www.crunchyroll.com/series/GR49G9VP6/sword-art-online + ``` + If you've passed the `-q` / `--quiet` [global flag](#global-settings), this flag is automatically set. + +- Force hardsub + + If you want to burn-in the subtitles, even if the output format/container supports soft-subs (e.g. `.mp4`), use the `--force-hardsub` flag to do so. + ```shell + $ crunchy-cli download --force-hardsub -s en-US https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + ``` + ### Archive +The `archive` command lets you download episodes with multiple audios and subtitles and merges it into a `.mkv` file. + **Supported urls** - Single episode (with [episode filtering](#episode-filtering)) ```shell - $ crunchy archive https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + $ crunchy-cli archive https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome ``` - Series (with [episode filtering](#episode-filtering)) ```shell - $ crunchy archive https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` **Options** @@ -170,7 +269,7 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Set the audio language with the `-a` / `--audio` flag. Can be used multiple times. ```shell - $ crunchy archive -a ja-JP -a de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive -a ja-JP -a de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is your system locale (if not supported by Crunchyroll, `en-US` (American English) and `ja-JP` (Japanese) are used). @@ -178,7 +277,7 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Besides the audio, you can specify the subtitle language by using the `-s` / `--subtitle` flag. ```shell - $ crunchy archive -s de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive -s de-DE https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is `all` subtitles. @@ -187,7 +286,7 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Define an output template by using the `-o` / `--output` flag. crunchy-cli uses the [`.mkv`](https://en.wikipedia.org/wiki/Matroska) container format, because of it's ability to store multiple audio, video and subtitle tracks at once. ```shell - $ crunchy archive -o "{title}.mkv" https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive -o "{title}.mkv" https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is `{title}.mkv`. See the [Template Options section](#output-template-options) below for more options. @@ -195,7 +294,7 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any The resolution for videos can be set via the `-r` / `--resolution` flag. ```shell - $ crunchy archive -r worst https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive -r worst https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is `best`. @@ -208,32 +307,57 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Valid options are `audio` - store one video and all other languages as audio only; `video` - store the video + audio for every language; `auto` - detect if videos differ in length: if so, behave like `video` - otherwise like `audio`. Subtitles will always match the primary audio and video. ```shell - $ crunchy archive -m audio https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive -m audio https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is `auto`. +- FFmpeg Preset + + You can specify specific built-in presets with the `--ffmpeg-preset` flag to convert videos to a specific coding while downloading. + Multiple predefined presets how videos should be encoded (h264, h265, av1, ...) are available, you can see them with `crunchy-cli archive --help`. + If you need more specific ffmpeg customizations you could either convert the output file manually or use ffmpeg output arguments as value for this flag. + ```shell + $ crunchy-cli archive --ffmpeg-preset av1-lossless https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + ``` + - Default subtitle `--default-subtitle` Set which subtitle language is to be flagged as **default** and **forced**. ```shell - $ crunchy archive --default-subtitle en-US https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli archive --default-subtitle en-US https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is none. +- Skip existing + + If you re-download a series but want to skip episodes you've already downloaded, the `--skip-existing` flag skips the already existing/downloaded files. + ```shell + $ crunchy-cli archive --skip-existing https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + ``` + +- Yes + + Sometimes different seasons have the same season number (e.g. Sword Art Online Alicization and Alicization War of Underworld are both marked as season 3), in such cases an interactive prompt is shown which needs user further user input to decide which season to download. + The `--yes` flag suppresses this interactive prompt and just downloads all seasons. + ```shell + $ crunchy-cli archive --yes https://www.crunchyroll.com/series/GR49G9VP6/sword-art-online + ``` + If you've passed the `-q` / `--quiet` [global flag](#global-settings), this flag is automatically set. + ### Search **Supported urls/input** - Single episode (with [episode filtering](#episode-filtering)) ```shell - $ crunchy search https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome + $ crunchy-cli search https://www.crunchyroll.com/watch/GRDQPM1ZY/alone-and-lonesome ``` - Series (with [episode filtering](#episode-filtering)) ```shell - $ crunchy search https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli search https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` - Search input ```shell - $ crunchy search "darling in the franxx" + $ crunchy-cli search "darling in the franxx" ``` **Options** @@ -241,11 +365,40 @@ With the session stored, you do not need to use `--credentials` / `--etp-rt` any Set the audio language to search via the `--audio` flag. Can be used multiple times. ```shell - $ crunchy search --audio en-US https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + $ crunchy-cli search --audio en-US https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx ``` Default is your system locale. -### Output Template Options +- Result limit + + If your input is a search term instead of an url, you have multiple options to control which results to process. + The `--search-top-results-limit` flag sets the limit of top search results to process. + `--search-series-limit` sets the limit of only series, `--search-movie-listing-limit` of only movie listings, `--search-episode-limit` of only episodes and `--search-music-limit` of only concerts and music videos. + ```shell + $ crunchy-cli search --search-top-results-limit 10 "darling in the franxx" + # only return series which have 'darling' in it. do not return top results which might also be non-series items + $ crunchy-cli search --search-top-results-limit 0 --search-series-limit 10 "darling" + # this returns 2 top results, 3 movie listings, 5 episodes and 1 music item as result + $ crunchy-cli search --search-top-results-limit 2 --search-movie-listing-limit 3 --search-episode-limit 5 --search-music-limit 1 "test" + ``` + Default is `5` for `--search-top-results-limit`, `0` for all others. + +- Output template + + The search command is designed to show only the specific information you want. + This is done with the `-o`/`--output` flag. + You can specify keywords in a specific pattern, and they will get replaced in the output text. + The required pattern for this begins with `{{`, then the keyword, and closes with `}}` (e.g. `{{episode.title}}`). + For example, if you want to get the title of an episode, you can use `Title: {{episode.title}}` and `{{episode.title}}` will be replaced with the episode title. + You can see all supported keywords with `crunchy-cli search --help`. + ```shell + $ crunchy-cli search -o "{{series.title}}" https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx + ``` + Default is `S{{season.number}}E{{episode.number}} - {{episode.title}}`. + +--- + +#### Output Template Options You can use various template options to change how the filename is processed. The following tags are available: @@ -263,11 +416,11 @@ You can use various template options to change how the filename is processed. Th Example: ```shell -$ crunchy archive -o "[S{season_number}E{episode_number}] {title}.mkv" https://www.crunchyroll.com/series/G8DHV7W21/dragon-ball +$ crunchy-cli archive -o "[S{season_number}E{episode_number}] {title}.mkv" https://www.crunchyroll.com/series/G8DHV7W21/dragon-ball # Output file: '[S01E01] Secret of the Dragon Ball.mkv' ``` -### Episode filtering +#### Episode filtering Filters patterns can be used to download a specific range of episodes from a single series. @@ -283,13 +436,17 @@ There are many possible patterns, for example: - `...[S3,S5]` - Download season three and five. - `...[S1-S3,S4E2-S4E6]` - Download season one to three, then episodes two to six from season four. -In practice, it would look like this: `https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx[E1-E5]` +In practice, it would look like this: +``` +https://www.crunchyroll.com/series/GY8VEQ95Y/darling-in-the-franxx[E1-E5] +``` # 📜 Disclaimer -This tool is **ONLY** meant for private use. You need a subscription to [`💳 Crunchyroll Premium 💳`](https://www.crunchyroll.com/welcome#plans) to download premium content. +This tool is meant for private use only. +You need a [Crunchyroll Premium](https://www.crunchyroll.com/welcome#plans) subscription to access premium content. -**You are entirely responsible for what happens to files you downloaded through crunchy-cli.** +**You are entirely responsible for what happens when you use crunchy-cli.** # ⚖ License