gingertea 0.1.0__tar.gz

gingertea-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Yore Des
+Copyright (c) 2026 OrbitCord
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gingertea-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: gingertea
+Version: 0.1.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
+
+# gingertea
+
+Download videos and audio in your terminal. Convert local media files in batches.
+
+Paste a link, press `d` to save an MP4, or press `c` to choose a format and quality.
+gingertea uses [yt-dlp](https://github.com/yt-dlp/yt-dlp),
+[ffmpeg](https://ffmpeg.org), and [Textual](https://textual.textualize.io/).
+
+![gingertea in the Tea House theme](https://raw.githubusercontent.com/orbitcord/gingertea/main/docs/gingertea.png)
+
+## 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, Python, gingertea, and ffmpeg. Set
+`GINGERTEA_NO_FFMPEG=1` to skip the ffmpeg download. The app can fetch it later.
+
+If you already use uv or pipx:
+
+```sh
+uv tool install gingertea
+# Or, with Python 3.10 or newer:
+pipx install gingertea
+```
+
+To install the current GitHub version:
+
+```sh
+uv tool install git+https://github.com/orbitcord/gingertea
+```
+
+## Use
+
+```sh
+gingertea                  # Open the app
+gingertea <url>            # Load a video link
+gingertea <file>           # Add a local file to Convert files
+gingertea setup            # Download ffmpeg and check available formats
+gingertea update           # Update yt-dlp
+gingertea --version
+```
+
+Download and Convert files have separate queues. Each queue runs one job at a time.
+You can add another link while a download runs.
+
+### Keyboard controls
+
+Press `Tab` to leave the input field before using letter or number shortcuts.
+The footer also has clickable shortcuts.
+
+| Key | Action |
+| --- | --- |
+| `1` | Open Download |
+| `2` | Open Convert files |
+| `3` or `s` | Open Settings |
+| `4` or `l` | Search supported sites |
+| `ctrl+t` | Switch between Download and Convert files |
+| `d` | Download the loaded video as MP4 |
+| `c` | Choose a format and quality |
+| `f` | Browse local files |
+| `r` | Remove the selected local file |
+| `x` | Cancel the current job |
+| `o` | Reveal the last saved file |
+| `u` | Update yt-dlp |
+| `t` | Choose a theme |
+| `esc` | Focus the current input field |
+| `q` | Quit |
+
+The sidebar collapses in narrow terminals. The input, media actions, queue, and
+keyboard controls remain available.
+
+### Download formats
+
+| Media | Formats |
+| --- | --- |
+| Video | MP4, MKV, WebM, MOV, GIF |
+| Audio | MP3, M4A, Opus, FLAC, WAV, OGG |
+
+The quality picker lists the resolutions available for the loaded video.
+The default MP4 choice selects H.264 for compatibility. YouTube usually limits H.264
+to 1080p. Higher MP4 resolutions may contain VP9 or AV1 and need a compatible player.
+
+Downloads go to your Downloads folder. Change the folder in Settings.
+Existing files keep their names. A new download gets a numbered suffix if needed.
+
+### Convert local files
+
+Open Convert files. Drop files into the terminal, paste their paths, or press `f`
+to browse. Press `c` to select an output format. You can mix video, audio, and images
+in one batch. The dialog shows which files the selection applies to.
+
+| Media | Formats |
+| --- | --- |
+| Video | MP4, MKV, WebM, MOV, M4V, AVI, TS, FLV, WMV, MPG, 3GP, OGV, GIF, animated PNG, animated WebP |
+| Audio | MP3, M4A, AAC, Opus, OGG, FLAC, ALAC, WAV, AIFF, WMA, AC3, E-AC3, MP2, WavPack, TTA, CAF, AU, MKA |
+| Image | JPG, PNG, WebP, AVIF, JPEG XL, HEIC, JPEG 2000, TIFF, BMP, GIF, TGA, QOI, EXR, HDR, PPM, PCX, SGI, DPX |
+
+The Frames tab exports video frames to a folder of images. Converted files go next
+to each original. gingertea leaves the original file unchanged. When the streams
+fit the output format, it copies them without re-encoding. The dialog explains
+whether the selected conversion will copy or re-encode.
+
+Some formats need codecs that your ffmpeg build may lack. Unavailable formats stay
+visible with a note about the missing codec. Pillow plugins handle HEIC and JPEG XL.
+
+### Themes
+
+Tea House is the default light theme. Press `t` or click Change theme to choose
+Matcha, Earl Grey, Masala Chai, Hibiscus, the original gingertea dark and light
+palettes, or a built-in Textual theme. gingertea saves your choice.
+
+The cup uses the selected icon asset, rendered with Unicode quadrant cells. It does
+not need Sixel or Kitty graphics support. Its colors follow the theme.
+
+### Videos that require a login
+
+For age-restricted or members-only videos, choose a browser in Settings where
+you are signed in to the site. gingertea reads its cookies through yt-dlp.
+Cookies remain off until you choose a browser. macOS may show a Keychain prompt.
+
+If a site blocks a download, update yt-dlp with `u` and try again. Browser cookies
+may help with authentication errors. The Sites screen can check whether yt-dlp
+has a dedicated extractor for a link.
+
+### Settings and updates
+
+Settings live in these locations:
+
+| Platform | File |
+| --- | --- |
+| macOS | `~/Library/Application Support/gingertea/config.toml` |
+| Linux | `~/.config/gingertea/config.toml` |
+| Windows | `%LOCALAPPDATA%\gingertea\config.toml` |
+
+gingertea checks for newer yt-dlp and gingertea releases at startup. With a uv tool
+or pipx install, it can update itself after you quit. Set
+`GINGERTEA_NO_AUTO_UPDATE=1` to disable that behavior.
+
+## Development
+
+```sh
+git clone https://github.com/orbitcord/gingertea
+cd gingertea
+uv sync --locked
+uv run gingertea
+uv run pytest -q
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv build --no-sources
+```
+
+The default tests replace network downloads with fakes. Set `GINGERTEA_LIVE=1` to
+include tests that download real videos.
+
+For a release, update the version in `pyproject.toml`, run `uv lock`, and push a
+matching `vX.Y.Z` tag. Configure PyPI Trusted Publishing for owner `orbitcord`,
+repository `gingertea`, workflow `release.yml`, and environment `pypi` first.
+The release workflow runs checks, builds the package, publishes it, and creates a
+GitHub release.
+
+## Uninstall
+
+```sh
+uv tool uninstall gingertea
+# Or:
+pipx uninstall gingertea
+```
+
+The cached ffmpeg binary stays outside the Python environment. To remove it,
+delete the gingertea data directory. On macOS it is
+`~/Library/Application Support/gingertea/ffmpeg`. On Linux it is
+`~/.local/share/gingertea/ffmpeg`. On Windows it is
+`%LOCALAPPDATA%\gingertea\ffmpeg`.
+
+## License
+
+MIT. The source copyright notices remain in [LICENSE](LICENSE).

gingertea-0.1.0/README.md

@@ -0,0 +1,187 @@
+# gingertea
+
+Download videos and audio in your terminal. Convert local media files in batches.
+
+Paste a link, press `d` to save an MP4, or press `c` to choose a format and quality.
+gingertea uses [yt-dlp](https://github.com/yt-dlp/yt-dlp),
+[ffmpeg](https://ffmpeg.org), and [Textual](https://textual.textualize.io/).
+
+![gingertea in the Tea House theme](https://raw.githubusercontent.com/orbitcord/gingertea/main/docs/gingertea.png)
+
+## 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, Python, gingertea, and ffmpeg. Set
+`GINGERTEA_NO_FFMPEG=1` to skip the ffmpeg download. The app can fetch it later.
+
+If you already use uv or pipx:
+
+```sh
+uv tool install gingertea
+# Or, with Python 3.10 or newer:
+pipx install gingertea
+```
+
+To install the current GitHub version:
+
+```sh
+uv tool install git+https://github.com/orbitcord/gingertea
+```
+
+## Use
+
+```sh
+gingertea                  # Open the app
+gingertea <url>            # Load a video link
+gingertea <file>           # Add a local file to Convert files
+gingertea setup            # Download ffmpeg and check available formats
+gingertea update           # Update yt-dlp
+gingertea --version
+```
+
+Download and Convert files have separate queues. Each queue runs one job at a time.
+You can add another link while a download runs.
+
+### Keyboard controls
+
+Press `Tab` to leave the input field before using letter or number shortcuts.
+The footer also has clickable shortcuts.
+
+| Key | Action |
+| --- | --- |
+| `1` | Open Download |
+| `2` | Open Convert files |
+| `3` or `s` | Open Settings |
+| `4` or `l` | Search supported sites |
+| `ctrl+t` | Switch between Download and Convert files |
+| `d` | Download the loaded video as MP4 |
+| `c` | Choose a format and quality |
+| `f` | Browse local files |
+| `r` | Remove the selected local file |
+| `x` | Cancel the current job |
+| `o` | Reveal the last saved file |
+| `u` | Update yt-dlp |
+| `t` | Choose a theme |
+| `esc` | Focus the current input field |
+| `q` | Quit |
+
+The sidebar collapses in narrow terminals. The input, media actions, queue, and
+keyboard controls remain available.
+
+### Download formats
+
+| Media | Formats |
+| --- | --- |
+| Video | MP4, MKV, WebM, MOV, GIF |
+| Audio | MP3, M4A, Opus, FLAC, WAV, OGG |
+
+The quality picker lists the resolutions available for the loaded video.
+The default MP4 choice selects H.264 for compatibility. YouTube usually limits H.264
+to 1080p. Higher MP4 resolutions may contain VP9 or AV1 and need a compatible player.
+
+Downloads go to your Downloads folder. Change the folder in Settings.
+Existing files keep their names. A new download gets a numbered suffix if needed.
+
+### Convert local files
+
+Open Convert files. Drop files into the terminal, paste their paths, or press `f`
+to browse. Press `c` to select an output format. You can mix video, audio, and images
+in one batch. The dialog shows which files the selection applies to.
+
+| Media | Formats |
+| --- | --- |
+| Video | MP4, MKV, WebM, MOV, M4V, AVI, TS, FLV, WMV, MPG, 3GP, OGV, GIF, animated PNG, animated WebP |
+| Audio | MP3, M4A, AAC, Opus, OGG, FLAC, ALAC, WAV, AIFF, WMA, AC3, E-AC3, MP2, WavPack, TTA, CAF, AU, MKA |
+| Image | JPG, PNG, WebP, AVIF, JPEG XL, HEIC, JPEG 2000, TIFF, BMP, GIF, TGA, QOI, EXR, HDR, PPM, PCX, SGI, DPX |
+
+The Frames tab exports video frames to a folder of images. Converted files go next
+to each original. gingertea leaves the original file unchanged. When the streams
+fit the output format, it copies them without re-encoding. The dialog explains
+whether the selected conversion will copy or re-encode.
+
+Some formats need codecs that your ffmpeg build may lack. Unavailable formats stay
+visible with a note about the missing codec. Pillow plugins handle HEIC and JPEG XL.
+
+### Themes
+
+Tea House is the default light theme. Press `t` or click Change theme to choose
+Matcha, Earl Grey, Masala Chai, Hibiscus, the original gingertea dark and light
+palettes, or a built-in Textual theme. gingertea saves your choice.
+
+The cup uses the selected icon asset, rendered with Unicode quadrant cells. It does
+not need Sixel or Kitty graphics support. Its colors follow the theme.
+
+### Videos that require a login
+
+For age-restricted or members-only videos, choose a browser in Settings where
+you are signed in to the site. gingertea reads its cookies through yt-dlp.
+Cookies remain off until you choose a browser. macOS may show a Keychain prompt.
+
+If a site blocks a download, update yt-dlp with `u` and try again. Browser cookies
+may help with authentication errors. The Sites screen can check whether yt-dlp
+has a dedicated extractor for a link.
+
+### Settings and updates
+
+Settings live in these locations:
+
+| Platform | File |
+| --- | --- |
+| macOS | `~/Library/Application Support/gingertea/config.toml` |
+| Linux | `~/.config/gingertea/config.toml` |
+| Windows | `%LOCALAPPDATA%\gingertea\config.toml` |
+
+gingertea checks for newer yt-dlp and gingertea releases at startup. With a uv tool
+or pipx install, it can update itself after you quit. Set
+`GINGERTEA_NO_AUTO_UPDATE=1` to disable that behavior.
+
+## Development
+
+```sh
+git clone https://github.com/orbitcord/gingertea
+cd gingertea
+uv sync --locked
+uv run gingertea
+uv run pytest -q
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv build --no-sources
+```
+
+The default tests replace network downloads with fakes. Set `GINGERTEA_LIVE=1` to
+include tests that download real videos.
+
+For a release, update the version in `pyproject.toml`, run `uv lock`, and push a
+matching `vX.Y.Z` tag. Configure PyPI Trusted Publishing for owner `orbitcord`,
+repository `gingertea`, workflow `release.yml`, and environment `pypi` first.
+The release workflow runs checks, builds the package, publishes it, and creates a
+GitHub release.
+
+## Uninstall
+
+```sh
+uv tool uninstall gingertea
+# Or:
+pipx uninstall gingertea
+```
+
+The cached ffmpeg binary stays outside the Python environment. To remove it,
+delete the gingertea data directory. On macOS it is
+`~/Library/Application Support/gingertea/ffmpeg`. On Linux it is
+`~/.local/share/gingertea/ffmpeg`. On Windows it is
+`%LOCALAPPDATA%\gingertea\ffmpeg`.
+
+## License
+
+MIT. The source copyright notices remain in [LICENSE](LICENSE).

gingertea-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "gingertea"
+version = "0.1.0"
+description = "Download and convert videos from YouTube and 1,300+ other sites in your terminal. Runs on yt-dlp."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = [
+    "youtube",
+    "yt-dlp",
+    "downloader",
+    "tui",
+    "terminal",
+    "converter",
+    "mp3",
+]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "yt-dlp[default]>=2026.8.19",
+    "textual>=8.2",
+    "pillow>=10",
+    "platformdirs>=4",
+    "tomli-w>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+    "deno>=2.0",
+    "pillow-heif>=0.18",
+    "pillow-jxl-plugin>=1.3",
+]
+
+[[project.authors]]
+name = "OrbitCord"
+email = "orbitcord@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/orbitcord/gingertea"
+Issues = "https://github.com/orbitcord/gingertea/issues"
+
+[project.scripts]
+gingertea = "gingertea.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "UP",
+]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

gingertea-0.1.0/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "gingertea"
+version = "0.1.0"
+description = "Download and convert videos from YouTube and 1,300+ other sites in your terminal. Runs on yt-dlp."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "OrbitCord", email = "orbitcord@gmail.com" }
+]
+requires-python = ">=3.10"
+keywords = ["youtube", "yt-dlp", "downloader", "tui", "terminal", "converter", "mp3"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "yt-dlp[default]>=2026.8.19",
+    "textual>=8.2",
+    "pillow>=10",
+    "platformdirs>=4",
+    "tomli-w>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+    "deno>=2.0",
+    "pillow-heif>=0.18",
+    "pillow-jxl-plugin>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/orbitcord/gingertea"
+Issues = "https://github.com/orbitcord/gingertea/issues"
+
+[project.scripts]
+gingertea = "gingertea.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.23,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

gingertea-0.1.0/src/gingertea/__init__.py

@@ -0,0 +1,15 @@
+"""gingertea: a terminal video downloader and converter built on yt-dlp."""
+
+
+def __getattr__(name: str):
+    # Looked up on first use: importlib.metadata adds ~15 ms to every launch otherwise.
+    if name == "__version__":
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            value = version("gingertea")
+        except PackageNotFoundError:  # pragma: no cover - running from a source tree
+            value = "0.0.0"
+        globals()["__version__"] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

gingertea-0.1.0/src/gingertea/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gingertea-0.1.0/src/gingertea/app.py

@@ -0,0 +1,45 @@
+"""The Textual application."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from textual.app import App
+
+from . import config
+from .screens.main import MainScreen
+from .theme import THEMES
+
+
+class GingerTeaApp(App):
+    CSS_PATH = "styles.tcss"
+    TITLE = "gingertea"
+    ENABLE_COMMAND_PALETTE = True
+
+    def __init__(self, initial_url: str = "") -> None:
+        super().__init__()
+        self.initial_url = initial_url
+        # Set when PyPI has a newer gingertea; the CLI starts the upgrade after the app exits.
+        self.pending_app_update: str | None = None
+        self.settings = config.load()
+
+    def on_mount(self) -> None:
+        for theme in THEMES:
+            self.register_theme(theme)
+        saved = self.settings.theme
+        self.theme = saved if saved in self.available_themes else "tea-house"
+        self.theme_changed_signal.subscribe(self, self._remember_theme)
+
+    def _remember_theme(self, theme) -> None:
+        if theme.name != self.settings.theme:
+            self.save_settings(replace(self.settings, theme=theme.name))
+
+    def get_default_screen(self) -> MainScreen:
+        return MainScreen(self.initial_url)
+
+    def save_settings(self, settings: config.Settings) -> None:
+        self.settings = settings
+        try:
+            config.save(settings)
+        except OSError as exc:
+            self.notify(f"Couldn't save settings: {exc}", severity="error")