carrot-leaf 0.1.0__tar.gz

carrot_leaf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yore Des
+
+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.

carrot_leaf-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: carrot-leaf
+Version: 0.1.0
+Summary: A good-looking terminal app for downloading and converting YouTube (and 1000+ other sites) videos, powered by yt-dlp.
+Keywords: youtube,yt-dlp,downloader,tui,terminal,converter,mp3
+Author: Yore Des
+Author-email: Yore Des <designsbyyore@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: static-ffmpeg>=3.0
+Requires-Dist: deno>=2.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Yore-Des/carrot-leaf
+Project-URL: Issues, https://github.com/Yore-Des/carrot-leaf/issues
+Description-Content-Type: text/markdown
+
+<pre>
+  \ | /    ██████╗ █████╗ ██████╗ ██████╗  ██████╗ ████████╗ ██╗     ███████╗ █████╗ ███████╗
+   \|/    ██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗╚══██╔══╝ ██║     ██╔════╝██╔══██╗██╔════╝
+ ▐█████▌  ██║     ███████║██████╔╝██████╔╝██║   ██║   ██║    ██║     █████╗  ███████║█████╗
+  ▐███▌   ██║     ██╔══██║██╔══██╗██╔══██╗██║   ██║   ██║    ██║     ██╔══╝  ██╔══██║██╔══╝
+   ▐█▌    ╚██████╗██║  ██║██║  ██║██║  ██║╚██████╔╝   ██║    ███████╗███████╗██║  ██║██║
+    ▀      ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝    ╚═╝    ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝
+</pre>
+
+A good-looking terminal app for downloading and converting videos from YouTube and
+1,000+ other sites. Paste a link, then **Download** or **Convert**. Built on
+[yt-dlp](https://github.com/yt-dlp/yt-dlp) and [Textual](https://textual.textualize.io/).
+
+## Install
+
+**macOS / Linux**
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/Yore-Des/carrot-leaf/main/install.sh | sh
+```
+
+**Windows** (PowerShell)
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Yore-Des/carrot-leaf/main/install.ps1 | iex"
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if you don't have it, then installs
+Carrot Leaf with its own Python. Your system Python doesn't matter, and you don't need to
+install ffmpeg or anything else.
+
+Already use uv or pipx?
+
+```sh
+uv tool install carrot-leaf
+pipx install carrot-leaf      # needs Python 3.10+
+```
+
+## Use it
+
+```sh
+carrot                 # open the app
+carrot <url>           # open with a link already loaded
+carrot update          # update yt-dlp
+carrot --version
+```
+
+Paste a link anywhere in the app. The video's details and thumbnail show up, then:
+
+| Key   | Does                                                    |
+| ----- | ------------------------------------------------------- |
+| `d`   | **Download**: best quality, saved as MP4                |
+| `c`   | **Convert**: pick a video or audio format and a quality |
+| `s`   | Settings: download folder, browser cookies              |
+| `o`   | Show the last downloaded file in Finder / Explorer      |
+| `u`   | Update yt-dlp                                           |
+| `esc` | Back to the URL bar                                     |
+| `q`   | Quit                                                    |
+
+You can paste another link while a download is running. Jobs wait in line and run one
+at a time.
+
+### Formats
+
+| Video                     | Audio                              |
+| ------------------------- | ---------------------------------- |
+| MP4, MKV, WebM, MOV, GIF  | MP3, M4A, Opus, FLAC, WAV, OGG     |
+| best, 2160p … 360p        | best, 320 / 192 / 128 kbps         |
+
+Carrot Leaf only offers resolutions the video actually has. Files get the title, artist
+and cover art embedded where the format supports it.
+
+### Where files go
+
+Files are saved to your Downloads folder as `Title [video-id].ext`. Change the folder with
+`s`. If a file with the same name exists, the new one is saved as `Title [id] (2).ext`.
+
+Settings are stored in:
+
+- macOS: `~/Library/Application Support/carrot-leaf/config.toml`
+- Linux: `~/.config/carrot-leaf/config.toml`
+- Windows: `%LOCALAPPDATA%\carrot-leaf\config.toml`
+
+### Age-restricted and members-only videos
+
+These need you to be signed in. When Carrot Leaf hits one, it offers to use the cookies
+from a browser where you're signed in (Chrome, Firefox, Safari, Edge, Brave, …). This is
+off until you pick a browser, and you can turn it off again in Settings. On a Mac you may
+see a Keychain prompt the first time.
+
+### When downloads break
+
+Sites change often, and YouTube most of all, so yt-dlp ships fixes every few weeks.
+Carrot Leaf checks for a new yt-dlp when it starts and shows a notice if one is out.
+Press `u` or run `carrot update`.
+
+### ffmpeg and Deno
+
+Converting needs ffmpeg, and YouTube needs a JavaScript runtime (Deno). If they're
+already installed, Carrot Leaf uses them. If not, it uses bundled copies: Deno comes with
+the package, and ffmpeg is downloaded once (about 70 MB) the first time it's needed.
+
+## Uninstall
+
+```sh
+uv tool uninstall carrot-leaf
+```
+
+## Development
+
+```sh
+git clone https://github.com/Yore-Des/carrot-leaf && cd carrot-leaf
+uv sync
+uv run carrot
+uv run pytest                       # offline tests
+CARROT_LIVE=1 uv run pytest         # also run real downloads
+uv run ruff check src tests && uv run ruff format src tests
+```
+
+Releases: bump `version` in `pyproject.toml`, then push a `vX.Y.Z` tag. GitHub Actions
+publishes to PyPI.
+
+## Please be nice
+
+Only download videos you have the right to download, and respect each site's terms.
+
+## License
+
+MIT

carrot_leaf-0.1.0/README.md

@@ -0,0 +1,129 @@
+<pre>
+  \ | /    ██████╗ █████╗ ██████╗ ██████╗  ██████╗ ████████╗ ██╗     ███████╗ █████╗ ███████╗
+   \|/    ██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗╚══██╔══╝ ██║     ██╔════╝██╔══██╗██╔════╝
+ ▐█████▌  ██║     ███████║██████╔╝██████╔╝██║   ██║   ██║    ██║     █████╗  ███████║█████╗
+  ▐███▌   ██║     ██╔══██║██╔══██╗██╔══██╗██║   ██║   ██║    ██║     ██╔══╝  ██╔══██║██╔══╝
+   ▐█▌    ╚██████╗██║  ██║██║  ██║██║  ██║╚██████╔╝   ██║    ███████╗███████╗██║  ██║██║
+    ▀      ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝    ╚═╝    ╚══════╝╚══════╝╚═╝  ╚═╝╚═╝
+</pre>
+
+A good-looking terminal app for downloading and converting videos from YouTube and
+1,000+ other sites. Paste a link, then **Download** or **Convert**. Built on
+[yt-dlp](https://github.com/yt-dlp/yt-dlp) and [Textual](https://textual.textualize.io/).
+
+## Install
+
+**macOS / Linux**
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/Yore-Des/carrot-leaf/main/install.sh | sh
+```
+
+**Windows** (PowerShell)
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Yore-Des/carrot-leaf/main/install.ps1 | iex"
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if you don't have it, then installs
+Carrot Leaf with its own Python. Your system Python doesn't matter, and you don't need to
+install ffmpeg or anything else.
+
+Already use uv or pipx?
+
+```sh
+uv tool install carrot-leaf
+pipx install carrot-leaf      # needs Python 3.10+
+```
+
+## Use it
+
+```sh
+carrot                 # open the app
+carrot <url>           # open with a link already loaded
+carrot update          # update yt-dlp
+carrot --version
+```
+
+Paste a link anywhere in the app. The video's details and thumbnail show up, then:
+
+| Key   | Does                                                    |
+| ----- | ------------------------------------------------------- |
+| `d`   | **Download**: best quality, saved as MP4                |
+| `c`   | **Convert**: pick a video or audio format and a quality |
+| `s`   | Settings: download folder, browser cookies              |
+| `o`   | Show the last downloaded file in Finder / Explorer      |
+| `u`   | Update yt-dlp                                           |
+| `esc` | Back to the URL bar                                     |
+| `q`   | Quit                                                    |
+
+You can paste another link while a download is running. Jobs wait in line and run one
+at a time.
+
+### Formats
+
+| Video                     | Audio                              |
+| ------------------------- | ---------------------------------- |
+| MP4, MKV, WebM, MOV, GIF  | MP3, M4A, Opus, FLAC, WAV, OGG     |
+| best, 2160p … 360p        | best, 320 / 192 / 128 kbps         |
+
+Carrot Leaf only offers resolutions the video actually has. Files get the title, artist
+and cover art embedded where the format supports it.
+
+### Where files go
+
+Files are saved to your Downloads folder as `Title [video-id].ext`. Change the folder with
+`s`. If a file with the same name exists, the new one is saved as `Title [id] (2).ext`.
+
+Settings are stored in:
+
+- macOS: `~/Library/Application Support/carrot-leaf/config.toml`
+- Linux: `~/.config/carrot-leaf/config.toml`
+- Windows: `%LOCALAPPDATA%\carrot-leaf\config.toml`
+
+### Age-restricted and members-only videos
+
+These need you to be signed in. When Carrot Leaf hits one, it offers to use the cookies
+from a browser where you're signed in (Chrome, Firefox, Safari, Edge, Brave, …). This is
+off until you pick a browser, and you can turn it off again in Settings. On a Mac you may
+see a Keychain prompt the first time.
+
+### When downloads break
+
+Sites change often, and YouTube most of all, so yt-dlp ships fixes every few weeks.
+Carrot Leaf checks for a new yt-dlp when it starts and shows a notice if one is out.
+Press `u` or run `carrot update`.
+
+### ffmpeg and Deno
+
+Converting needs ffmpeg, and YouTube needs a JavaScript runtime (Deno). If they're
+already installed, Carrot Leaf uses them. If not, it uses bundled copies: Deno comes with
+the package, and ffmpeg is downloaded once (about 70 MB) the first time it's needed.
+
+## Uninstall
+
+```sh
+uv tool uninstall carrot-leaf
+```
+
+## Development
+
+```sh
+git clone https://github.com/Yore-Des/carrot-leaf && cd carrot-leaf
+uv sync
+uv run carrot
+uv run pytest                       # offline tests
+CARROT_LIVE=1 uv run pytest         # also run real downloads
+uv run ruff check src tests && uv run ruff format src tests
+```
+
+Releases: bump `version` in `pyproject.toml`, then push a `vX.Y.Z` tag. GitHub Actions
+publishes to PyPI.
+
+## Please be nice
+
+Only download videos you have the right to download, and respect each site's terms.
+
+## License
+
+MIT

carrot_leaf-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "carrot-leaf"
+version = "0.1.0"
+description = "A good-looking terminal app for downloading and converting YouTube (and 1000+ other sites) videos, powered by 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'",
+    "static-ffmpeg>=3.0",
+    "deno>=2.0",
+]
+
+[[project.authors]]
+name = "Yore Des"
+email = "designsbyyore@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/Yore-Des/carrot-leaf"
+Issues = "https://github.com/Yore-Des/carrot-leaf/issues"
+
+[project.scripts]
+carrot = "carrot_leaf.cli:main"
+carrot-leaf = "carrot_leaf.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"]

carrot_leaf-0.1.0/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "carrot-leaf"
+version = "0.1.0"
+description = "A good-looking terminal app for downloading and converting YouTube (and 1000+ other sites) videos, powered by yt-dlp."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Yore Des", email = "designsbyyore@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'",
+    "static-ffmpeg>=3.0",
+    "deno>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Yore-Des/carrot-leaf"
+Issues = "https://github.com/Yore-Des/carrot-leaf/issues"
+
+[project.scripts]
+carrot = "carrot_leaf.cli:main"
+carrot-leaf = "carrot_leaf.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"]

carrot_leaf-0.1.0/src/carrot_leaf/__init__.py

@@ -0,0 +1,8 @@
+"""Carrot Leaf: a terminal video downloader and converter built on yt-dlp."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("carrot-leaf")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0"

carrot_leaf-0.1.0/src/carrot_leaf/__main__.py

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

carrot_leaf-0.1.0/src/carrot_leaf/app.py

@@ -0,0 +1,35 @@
+"""The Textual application."""
+
+from __future__ import annotations
+
+from textual.app import App
+
+from . import config
+from .screens.main import MainScreen
+from .theme import THEMES
+
+
+class CarrotLeafApp(App):
+    CSS_PATH = "styles.tcss"
+    TITLE = "Carrot Leaf"
+    ENABLE_COMMAND_PALETTE = True
+
+    def __init__(self, initial_url: str = "") -> None:
+        super().__init__()
+        self.initial_url = initial_url
+        self.settings = config.load()
+
+    def on_mount(self) -> None:
+        for theme in THEMES:
+            self.register_theme(theme)
+        self.theme = "carrot"
+
+    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")

carrot_leaf-0.1.0/src/carrot_leaf/cli.py

@@ -0,0 +1,55 @@
+"""Command-line entry point: `carrot [URL]`, `carrot update`, `carrot --version`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["update"]:
+        return _update()
+
+    parser = argparse.ArgumentParser(
+        prog="carrot",
+        description="Download or convert videos from YouTube and 1,000+ other sites.",
+        epilog="Run `carrot update` to update yt-dlp.",
+    )
+    parser.add_argument("url", nargs="?", default="", help="video link to open straight away")
+    parser.add_argument("--version", action="version", version=_version_text())
+    args = parser.parse_args(argv)
+
+    from .app import CarrotLeafApp
+
+    CarrotLeafApp(initial_url=args.url).run()
+    return 0
+
+
+def _version_text() -> str:
+    from .engine.update import installed_version
+
+    return f"carrot-leaf {__version__} (yt-dlp {installed_version()})"
+
+
+def _update() -> int:
+    from .engine import update
+
+    current = update.installed_version()
+    latest = update.latest_version()
+    if latest and update._key(latest) <= update._key(current):
+        print(f"yt-dlp {current} is already the latest version.")
+        return 0
+    print(f"Updating yt-dlp {current} → {latest or 'latest'}…")
+    print("$ " + " ".join(update.upgrade_command()))
+    ok, output = update.upgrade()
+    if output:
+        print(output)
+    print("Done." if ok else "Update failed.")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

carrot_leaf-0.1.0/src/carrot_leaf/config.py

@@ -0,0 +1,62 @@
+"""User settings, stored as TOML in the platform config directory."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+import platformdirs
+import tomli_w
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+APP_NAME = "carrot-leaf"
+
+
+def default_download_dir() -> str:
+    return str(Path(platformdirs.user_downloads_dir()))
+
+
+def config_path() -> Path:
+    return Path(platformdirs.user_config_dir(APP_NAME, appauthor=False)) / "config.toml"
+
+
+@dataclass
+class Settings:
+    download_dir: str = ""
+    # Last choice made in the Convert dialog, so it opens where the user left it.
+    last_kind: str = "video"
+    last_video_format: str = "mp4"
+    last_video_quality: str = "best"
+    last_audio_format: str = "mp3"
+    last_audio_quality: str = "best"
+    # Browser cookies stay off until the user opts in for a login-only video.
+    cookies_browser: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.download_dir:
+            self.download_dir = default_download_dir()
+
+    @property
+    def download_path(self) -> Path:
+        return Path(self.download_dir).expanduser()
+
+
+def load(path: Path | None = None) -> Settings:
+    path = path or config_path()
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return Settings()
+    known = {f.name for f in fields(Settings)}
+    return Settings(**{k: v for k, v in data.items() if k in known and isinstance(v, str)})
+
+
+def save(settings: Settings, path: Path | None = None) -> None:
+    path = path or config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(tomli_w.dumps(asdict(settings)), encoding="utf-8")