crunchy-cli/README.md

# crunchy-cli

A pure [Rust](https://www.rust-lang.org/) CLI for [Crunchyroll](https://www.crunchyroll.com).

<p align="center">
  <a href="https://github.com/crunchy-labs/crunchy-cli">
    <img src="https://img.shields.io/github/languages/code-size/crunchy-labs/crunchy-cli?style=flat-square" alt="Code size">
  </a>
  <a href="https://github.com/crunchy-labs/crunchy-cli/releases/latest">
    <img src="https://img.shields.io/github/downloads/crunchy-labs/crunchy-cli/total?style=flat-square" alt="Download Badge">
  </a>
  <a href="https://github.com/crunchy-labs/crunchy-cli/blob/master/LICENSE">
    <img src="https://img.shields.io/github/license/crunchy-labs/crunchy-cli?style=flat-square" alt="License">
  </a>
  <a href="https://github.com/crunchy-labs/crunchy-cli/releases">
    <img src="https://img.shields.io/github/v/release/crunchy-labs/crunchy-cli?include_prereleases&style=flat-square" alt="Release">
  </a>
  <a href="https://discord.gg/PXGPGpQxgk">
    <img src="https://img.shields.io/discord/994882878125121596?label=discord&style=flat-square" alt="Discord">
  </a>
  <a href="https://github.com/crunchy-labs/crunchy-cli/actions/workflows/ci.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/crunchy-labs/crunchy-cli/ci.yml?branch=master&style=flat-square" alt="CI">
  </a>
</p>

<p align="center">
  <a href="#%EF%B8%8F-usage">Usage 🖥️</a>
  •
  <a href="#%EF%B8%8F-disclaimer">Disclaimer 📜</a>
  •
  <a href="#-license">License ⚖</a>
</p>

> 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).

## ✨ 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.

## 💾 Get the executable

### 📥 Download the latest binaries

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

This requires [nix](https://nixos.org) and you'll probably need `--extra-experimental-features "nix-command flakes"` depending on your configurations.
```shell
$ nix <run|shell|develop> github:crunchy-labs/crunchy-cli
```

### 🛠 Build it yourself

Since we do not support every platform and architecture you may have to build the project yourself.
This requires [git](https://git-scm.com/) and [Cargo](https://doc.rust-lang.org/cargo).
```shell
$ git clone https://github.com/crunchy-labs/crunchy-cli
$ cd crunchy-cli
$ cargo build --release
$ cargo install --force --path .
```

## 🖥️ Usage

> All shown commands are examples 🧑🏼‍🍳

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.

- Credentials
  - ```shell
    $ crunchy --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"
    ```
- Stay Anonymous
  - Skip the login check:
  - ```shell 
    $ crunchy --anonymous
    ```

### 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*.

```shell
$ crunchy --etp-rt "4ebf1690-53a4-491a-a2ac-488309120f5d" login
```

With the session stored, you do not need to use `--credentials` / `--etp-rt` anymore. This does not work with `--anonymous`.

### Download

**Supported urls**
- Single episode (with [episode filtering](#episode-filtering))
  ```shell
  $ crunchy 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
  ```

**Options**
- Audio language

  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
  ```
  Default is your system locale. If not supported by Crunchyroll, `en-US` (American English) is the default.

- Subtitle language

  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
  ```
  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
  ```
  Default is `{title}.mp4`. See the [Template Options section](#output-template-options) below for more options.

- Resolution

  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
  ```
  Default is `best`.

### Archive

**Supported urls**
- Single episode (with [episode filtering](#episode-filtering))
  ```shell
  $ crunchy 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
  ```

**Options**
- Audio languages

  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
  ```
  Default is your system locale (if not supported by Crunchyroll, `en-US` (American English) and `ja-JP` (Japanese) are used).

- Subtitle languages

  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
  ```
  Default is `all` subtitles.

- Output template

  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
  ```
  Default is `{title}.mkv`. See the [Template Options section](#output-template-options) below for more options.

- Resolution

  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
  ```
  Default is `best`.

- Merge behavior

  Due to censorship, some episodes have multiple lengths for different languages.
  In the best case, when multiple audio & subtitle tracks are used, there is only one *video* track and all other languages can be stored as audio-only.
  But, as said, this is not always the case.
  With the `-m` / `--merge` flag you can define the behaviour when an episodes' video tracks differ in length.
  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
  ```
  Default is `auto`.

- 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
  ```
  Default is none.
  
### Output Template Options

You can use various template options to change how the filename is processed. The following tags are available:

- `{title}`                   → Title of the video
- `{series_name}`             → Name of the series
- `{season_name}`             → Name of the season
- `{audio}`                   → Audio language of the video
- `{resolution}`              → Resolution of the video
- `{season_number}`           → Number of the season
- `{episode_number}`          → Number of the episode
- `{relative_episode_number}` → Number of the episode relative to its season
- `{series_id}`               → ID of the series
- `{season_id}`               → ID of the season
- `{episode_id}`              → ID of the episode

Example:
```shell
$ crunchy 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'
```

### Search

**Supported urls/input**
- Single episode (with [episode filtering](#episode-filtering))
  ```shell
  $ crunchy 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
  ```
- Search input
  ```shell
  $ crunchy search "darling in the franxx"
  ```

**Options**
- Audio

  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
  ```
  Default is your system locale.

### Episode filtering

Filters patterns can be used to download a specific range of episodes from a single series.

A filter pattern may consist of either a season, an episode, or a combination of the two.
When used in combination, seasons `S` must be defined before episodes `E`.

There are many possible patterns, for example:
- `...[E5]` - Download the fifth episode.
- `...[S1]` - Download the whole first season.
- `...[-S2]` - Download the first two seasons.
- `...[S3E4-]` - Download everything from season three, episode four, onwards.
- `...[S1E4-S3]` - Download season one, starting at episode four, then download season two and three.
- `...[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]`

# 📜 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.

**You are entirely responsible for what happens to files you downloaded through crunchy-cli.**

# ⚖ License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the [LICENSE](LICENSE) file for more details.