Metadata-Version: 2.4
Name: gingertea
Version: 0.2.0
Summary: Download and convert videos from YouTube and 1,300+ other sites in your terminal. Runs on yt-dlp.
Keywords: youtube,yt-dlp,downloader,tui,terminal,converter,mp3
Author: OrbitCord
Author-email: OrbitCord <orbitcord@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Dist: yt-dlp[default]>=2026.8.19
Requires-Dist: textual>=8.2
Requires-Dist: pillow>=10
Requires-Dist: platformdirs>=4
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
Requires-Dist: deno>=2.0
Requires-Dist: pillow-heif>=0.18
Requires-Dist: pillow-jxl-plugin>=1.3
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/orbitcord/gingertea
Project-URL: Issues, https://github.com/orbitcord/gingertea/issues
Description-Content-Type: text/markdown

<pre>
 ██████╗ ██╗███╗   ██╗ ██████╗ ███████╗██████╗ ████████╗███████╗ █████╗
██╔════╝ ██║████╗  ██║██╔════╝ ██╔════╝██╔══██╗╚══██╔══╝██╔════╝██╔══██╗
██║  ███╗██║██╔██╗ ██║██║  ███╗█████╗  ██████╔╝   ██║   █████╗  ███████║
██║   ██║██║██║╚██╗██║██║   ██║██╔══╝  ██╔══██╗   ██║   ██╔══╝  ██╔══██║
╚██████╔╝██║██║ ╚████║╚██████╔╝███████╗██║  ██║   ██║   ███████╗██║  ██║
 ╚═════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝
</pre>

gingertea downloads videos from YouTube and 1,300+ other sites in your terminal. Paste a
link and press `d` to save an MP4, or press `c` to choose a format and quality. You can
also convert videos, audio and images already on your computer. It runs on
[yt-dlp](https://github.com/yt-dlp/yt-dlp), [ffmpeg](https://ffmpeg.org) and
[Textual](https://textual.textualize.io/).

## Install

On macOS or Linux:

```sh
curl -LsSf https://raw.githubusercontent.com/orbitcord/gingertea/main/install.sh | sh
```

On Windows, run this in PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/orbitcord/gingertea/main/install.ps1 | iex"
```

The installer sets up [uv](https://docs.astral.sh/uv/), Python, gingertea, and ffmpeg.
Set `GINGERTEA_NO_FFMPEG=1` to skip the ffmpeg download; gingertea can get it the first
time you need it.

If you already use uv or pipx:

```sh
uv tool install gingertea
pipx install gingertea          # needs Python 3.10+
gingertea setup                 # optional: get ffmpeg now
```

To install the current GitHub version:

```sh
uv tool install git+https://github.com/orbitcord/gingertea
```

## Use

```sh
gingertea                  # open the app
gingertea <url>            # open with a video link loaded
gingertea <file>           # open Convert files with a file loaded
gingertea get <url>        # download without opening the app
gingertea convert <file> -f mp3
gingertea setup            # get ffmpeg and check available formats
gingertea update           # update yt-dlp
gingertea --version
```

Paste a link, or type a search and press Enter. gingertea shows the title, channel,
length, upload date and thumbnail. A playlist or channel shows how many videos it has.
The footer lists the keyboard shortcuts, and its shortcuts are clickable.

| Key | Action |
| --- | --- |
| `d` | Download the loaded video as MP4, or every video in a playlist |
| `e` | Tick videos in a playlist, or type a number to keep the first N |
| `a` | Download audio, using the last audio choice |
| `c` | Choose a format, quality, clip, subtitles and extras |
| `p` | Pause or resume the queue |
| `h` | History: open, show, copy, download again, or forget |
| `v` | Load a video link copied to the clipboard |
| `x` | Cancel the current job |
| `l` or `4` | Search supported sites |
| `s` or `3` | Open Settings |
| `t` | Choose a theme |
| `o` | Reveal the last saved file |
| `u` | Update yt-dlp |
| `ctrl+t` | Switch between Download and Convert files |
| `1` / `2` | Open Download / Convert files |
| `Tab` | Leave the URL field so letter shortcuts work |
| `esc` | Focus the current input field |
| `q` | Quit |

While the URL field has focus, letters go into the link. Press `Tab` first or click a
shortcut in the footer. You can add another link while a download runs. Settings chooses
how many run at once, from 1 to 4. `p` holds the ones still waiting. The tabs, wordmark,
thumbnail and shortcuts adapt to compact terminals so the input, actions and queue stay
visible.

`gingertea get` and `gingertea convert` print progress to stderr and each saved path to
stdout, so a script can use the file. `gingertea get` takes `--format`, `--quality`,
`--audio`, `--start`, `--end`, `--subs`, `--embed-subs`, `--srt`, `--sponsorblock`,
`--chapters` and `--loudnorm`. `gingertea convert` takes `-f`, plus `--start`, `--end`,
`--chapters`, `--loudnorm`, `--max-kb` and `--strip-exif`.

### Download formats

| Video | Audio |
| --- | --- |
| MP4, MKV, WebM, MOV, GIF | MP3, M4A, Opus, FLAC, WAV, OGG |
| best, 2160p … 360p | best, 320 / 192 / 128 kbps |

The quality list only shows options available for the video. The default MP4 choice
prefers H.264 for compatibility. YouTube usually limits H.264 to 1080p; higher MP4
resolutions may use VP9 or AV1, which some older players cannot play.

The same dialog has a clip, with a start and end such as `1:30`, `90` or `1m30s`. The
end has to come after the start. That works for a link and for a file on your computer.
Subtitles can go inside an MP4, MKV or WebM, or sit beside it as a `.srt`, in the
languages you list. On YouTube, SponsorBlock can cut sponsor segments or mark them as
chapters. Audio can be split into one file per chapter, and the volume can be evened
out. Images can be limited to a size in KB, and location data can be stripped.

A playlist is saved into a folder named after the playlist. A bare YouTube channel link
opens its Videos tab. Run the playlist again and videos already saved are skipped.
Press `h` for history: search it, open a file, show it in its folder, copy the link,
download it again, or forget the entry. When you come back to gingertea it offers a
link you copied; `v` loads it. If the queue finishes while the terminal is in the
background, gingertea posts a system notification.

Settings includes the filename. `{title}`, `{id}`, `{channel}`, `{date}`, `{index}` and
`{ext}` are filled in, and `/` makes a folder. An example name is shown as you type.

### Convert files on your computer

Open Convert files with `ctrl+t` or click the tab. Drop files into the terminal, paste
their paths, or press `f` to browse. You can add several files at once and mix videos,
audio and images. Dropping a file on the Download tab switches to Convert files.

Press `c` to choose a format. The dialog shows which files the selection applies to.
Use `r` to remove the selected file and `x` to cancel a conversion. The Frames tab
exports video frames to a folder of images.

| Video | Audio | Image |
| --- | --- | --- |
| MP4, MKV, WebM, MOV, M4V, AVI, TS, FLV, WMV, MPG, 3GP, OGV, GIF, animated PNG, animated WebP | MP3, M4A, AAC, Opus, OGG, FLAC, ALAC, WAV, AIFF, WMA, AC3, E-AC3, MP2, WavPack, TTA, CAF, AU, MKA | JPG, PNG, WebP, AVIF, JPEG XL, HEIC, JPEG 2000, TIFF, BMP, GIF, TGA, QOI, EXR, HDR, PPM, PCX, SGI, DPX |

Converted files go next to their originals. gingertea leaves each original unchanged.
When the streams already fit the selected format, it copies them without re-encoding.
The dialog says whether the conversion will copy or re-encode. Some formats need codecs
that an ffmpeg build may lack; unavailable options stay visible with a note about what's
missing. Pillow plugins provide support for HEIC and JPEG XL.

### Where files go

Downloads go to your Downloads folder. Names use the video title and ID, such as
`Title [video-id].mp4`. If a file with that name already exists, gingertea adds a
number, for example `Title [video-id] (2).mp4`. Press `s` to choose another folder.

Settings, including your theme and download folder, live in:

| Platform | File |
| --- | --- |
| macOS | `~/Library/Application Support/gingertea/config.toml` |
| Linux | `~/.config/gingertea/config.toml` |
| Windows | `%LOCALAPPDATA%\gingertea\config.toml` |

### Themes

Masala Chai is the default dark theme. Press `t` or click Themes
to choose Tea House, Matcha, Earl Grey, Masala Chai, Hibiscus, gingertea light, or a
built-in Textual theme. gingertea remembers your choice.

### Videos that need you signed in

For age-restricted or members-only videos, choose a browser in Settings where you are
signed in. gingertea can read cookies from Chrome, Firefox, Safari, Edge, Brave, Opera,
Vivaldi or Chromium through yt-dlp. Cookies stay off until you choose a browser. On
macOS, expect a Keychain prompt the first time.

### When downloads break

Sites change how they serve video, and yt-dlp ships updates to keep up. gingertea checks
for a newer yt-dlp at startup. Press `u` or run `gingertea update` to install it, then
try the link again. The Sites screen can check whether yt-dlp has a dedicated extractor
for a link. Browser cookies may help with login errors.

### Updates

With a uv tool or pipx install, gingertea checks PyPI for a newer release while it is
open. If one is available, the update runs in the background after you quit, and the
next launch uses the new version. Set `GINGERTEA_NO_AUTO_UPDATE=1` to turn this off.

### ffmpeg, Deno and image formats

Converting needs ffmpeg, and some YouTube downloads need Deno to run JavaScript. The
installer downloads gingertea's own ffmpeg build; `gingertea setup` installs it now, or
the app can get it the first time it is needed. If ffmpeg is already on your `PATH`,
gingertea uses it too. Deno and the Pillow plugins for HEIC and JPEG XL install with the
Python package. If a format still needs a codec your machine doesn't have, the Convert
dialog shows it as unavailable and names the missing codec.

## Uninstall

```sh
uv tool uninstall gingertea       # or: pipx uninstall gingertea
```

The cached ffmpeg binary stays outside the Python environment so updates don't download
it again. To remove it too, delete the `ffmpeg` folder next to the settings file:
`~/Library/Application Support/gingertea/ffmpeg` on macOS,
`~/.local/share/gingertea/ffmpeg` on Linux, or
`%LOCALAPPDATA%\gingertea\ffmpeg` on Windows.

## Development

```sh
git clone https://github.com/orbitcord/gingertea && cd gingertea
uv sync --locked
uv run gingertea
uv run pytest -q                   # offline tests
GINGERTEA_LIVE=1 uv run pytest -q   # also download real videos
uv run ruff check src tests
uv run ruff format --check src tests
uv build --no-sources
```

To release, update the version in `pyproject.toml`, run `uv lock`, then push the matching
`vX.Y.Z` tag. GitHub Actions runs the checks, builds the package, publishes to PyPI, and
creates a GitHub release. PyPI Trusted Publishing must be configured for owner
`orbitcord`, repository `gingertea`, workflow `release.yml`, and environment `pypi`.

## Please be considerate

Only download videos you have the right to download, and follow each site's terms.

## License

MIT. Source copyright notices remain in [LICENSE](LICENSE).
