ytconvert-cli 1.0.0__tar.gz

ytconvert_cli-1.0.0/.gitignore

@@ -0,0 +1,148 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+downloads/
+output/
+*.mp3
+*.mp4
+*.webm
+*.m4a

ytconvert_cli-1.0.0/LICENSE

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

ytconvert_cli-1.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: ytconvert-cli
+Version: 1.0.0
+Summary: A command-line tool to convert YouTube videos to MP3 or MP4 using yt-dlp
+Project-URL: Homepage, https://github.com/yourusername/ytconvert-cli
+Project-URL: Documentation, https://github.com/yourusername/ytconvert-cli#readme
+Project-URL: Repository, https://github.com/yourusername/ytconvert-cli
+Project-URL: Issues, https://github.com/yourusername/ytconvert-cli/issues
+Project-URL: Changelog, https://github.com/yourusername/ytconvert-cli/blob/main/CHANGELOG.md
+Author: ytconvert-cli contributors
+License: MIT
+License-File: LICENSE
+Keywords: audio,cli,converter,download,mp3,mp4,video,youtube,yt-dlp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: imageio-ffmpeg>=0.4.9
+Requires-Dist: typer>=0.9.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: yt-dlp>=2024.1.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+
+# ytconvert-cli
+
+**Production-ready YouTube to MP3/MP4 converter.**
+
+[![PyPI version](https://img.shields.io/pypi/v/ytconvert-cli.svg)](https://pypi.org/project/ytconvert-cli/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Features
+
+- Convert YouTube videos to **MP3** (audio extraction)
+- Download YouTube videos as **MP4** (with quality selection)
+- Custom output directory support
+- Progress indicators with download speed and ETA
+- Clean error handling with specific exit codes
+- **FFmpeg is bundled**—no separate install needed
+- Uses yt-dlp Python API (no shell calls)
+- Pip-installable and PyPI-ready
+
+---
+
+## 📦 Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install ytconvert-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/ytconvert-cli.git
+cd ytconvert-cli
+pip install .
+```
+
+---
+
+## 🖥️ CLI Usage
+
+```bash
+# Convert to MP3 (default)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID
+
+# Convert to MP4
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4
+
+# MP4 with specific quality
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4 --quality 720p
+
+# Save to custom directory
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID -f mp3 -o ./downloads
+
+# Get video info only (no download)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --info
+
+# Show help
+ytconvert --help
+```
+
+**Short options:**
+| Long      | Short | Description         |
+|-----------|-------|---------------------|
+| --format  | -f    | mp3 or mp4          |
+| --quality | -q    | Video quality       |
+| --output  | -o    | Output directory    |
+| --info    | -i    | Info only           |
+| --verbose | -v    | Debug mode          |
+| --version | -V    | Show version        |
+
+---
+
+## 🐍 Python API Usage
+
+```python
+from ytconvert import YouTubeConverter
+
+# Convert to MP3
+converter = YouTubeConverter(output_dir="./downloads")
+mp3_path = converter.convert_to_mp3("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Saved: {mp3_path}")
+
+# Convert to MP4 with quality
+mp4_path = converter.convert_to_mp4("https://youtube.com/watch?v=VIDEO_ID", quality="720p")
+
+# Get video info only
+info = converter.get_video_info("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Title: {info['title']}")
+print(f"Duration: {info['duration']} seconds")
+```
+
+---
+
+## 🛠️ Integration Example (Django, subprocess)
+
+```python
+import subprocess
+import sys
+
+def convert_youtube_video(url: str, format: str = "mp3", quality: str = "best"):
+    cmd = [
+        sys.executable, "-m", "ytconvert.cli",
+        url,
+        "--format", format,
+        "--output", "/path/to/downloads",
+    ]
+    if format == "mp4" and quality != "best":
+        cmd.extend(["--quality", quality])
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        return {"success": True, "output": result.stdout}
+    else:
+        return {"success": False, "exit_code": result.returncode, "error": result.stderr}
+```
+
+---
+
+## ⚠️ Exit Codes
+
+| Code | Meaning                       |
+|------|-------------------------------|
+| 0    | Success                       |
+| 1    | Invalid YouTube URL           |
+| 2    | Download failure              |
+| 3    | Format or quality unavailable |
+| 4    | Unexpected error              |
+
+---
+
+## 🏗️ Project Structure
+
+```
+ytconvert-cli/
+├── ytconvert/
+│   ├── __init__.py      # Package exports
+│   ├── cli.py           # CLI entry point
+│   ├── converter.py     # yt-dlp logic
+│   ├── validators.py    # URL/format validation
+│   ├── exceptions.py    # Custom exceptions
+│   └── utils.py         # Utilities
+├── pyproject.toml       # Packaging config
+├── README.md            # This file
+└── LICENSE              # MIT License
+```
+
+---
+
+## 📝 Development
+
+```bash
+# Run tests
+pytest
+
+# Format code
+black ytconvert/
+ruff check ytconvert/ --fix
+
+# Type check
+mypy ytconvert/
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🙏 Acknowledgments
+
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Video downloader
+- [Typer](https://typer.tiangolo.com/) - CLI framework
+- [FFmpeg](https://ffmpeg.org/) - Media backend (bundled)
+
+---
+
+## 📢 Disclaimer
+
+This tool is intended for downloading videos you have the right to download. Please respect copyright laws and YouTube's Terms of Service. The authors are not responsible for misuse.

ytconvert_cli-1.0.0/README.md

@@ -0,0 +1,184 @@
+
+# ytconvert-cli
+
+**Production-ready YouTube to MP3/MP4 converter.**
+
+[![PyPI version](https://img.shields.io/pypi/v/ytconvert-cli.svg)](https://pypi.org/project/ytconvert-cli/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Features
+
+- Convert YouTube videos to **MP3** (audio extraction)
+- Download YouTube videos as **MP4** (with quality selection)
+- Custom output directory support
+- Progress indicators with download speed and ETA
+- Clean error handling with specific exit codes
+- **FFmpeg is bundled**—no separate install needed
+- Uses yt-dlp Python API (no shell calls)
+- Pip-installable and PyPI-ready
+
+---
+
+## 📦 Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install ytconvert-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/ytconvert-cli.git
+cd ytconvert-cli
+pip install .
+```
+
+---
+
+## 🖥️ CLI Usage
+
+```bash
+# Convert to MP3 (default)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID
+
+# Convert to MP4
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4
+
+# MP4 with specific quality
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --format mp4 --quality 720p
+
+# Save to custom directory
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID -f mp3 -o ./downloads
+
+# Get video info only (no download)
+ytconvert https://www.youtube.com/watch?v=VIDEO_ID --info
+
+# Show help
+ytconvert --help
+```
+
+**Short options:**
+| Long      | Short | Description         |
+|-----------|-------|---------------------|
+| --format  | -f    | mp3 or mp4          |
+| --quality | -q    | Video quality       |
+| --output  | -o    | Output directory    |
+| --info    | -i    | Info only           |
+| --verbose | -v    | Debug mode          |
+| --version | -V    | Show version        |
+
+---
+
+## 🐍 Python API Usage
+
+```python
+from ytconvert import YouTubeConverter
+
+# Convert to MP3
+converter = YouTubeConverter(output_dir="./downloads")
+mp3_path = converter.convert_to_mp3("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Saved: {mp3_path}")
+
+# Convert to MP4 with quality
+mp4_path = converter.convert_to_mp4("https://youtube.com/watch?v=VIDEO_ID", quality="720p")
+
+# Get video info only
+info = converter.get_video_info("https://youtube.com/watch?v=VIDEO_ID")
+print(f"Title: {info['title']}")
+print(f"Duration: {info['duration']} seconds")
+```
+
+---
+
+## 🛠️ Integration Example (Django, subprocess)
+
+```python
+import subprocess
+import sys
+
+def convert_youtube_video(url: str, format: str = "mp3", quality: str = "best"):
+    cmd = [
+        sys.executable, "-m", "ytconvert.cli",
+        url,
+        "--format", format,
+        "--output", "/path/to/downloads",
+    ]
+    if format == "mp4" and quality != "best":
+        cmd.extend(["--quality", quality])
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        return {"success": True, "output": result.stdout}
+    else:
+        return {"success": False, "exit_code": result.returncode, "error": result.stderr}
+```
+
+---
+
+## ⚠️ Exit Codes
+
+| Code | Meaning                       |
+|------|-------------------------------|
+| 0    | Success                       |
+| 1    | Invalid YouTube URL           |
+| 2    | Download failure              |
+| 3    | Format or quality unavailable |
+| 4    | Unexpected error              |
+
+---
+
+## 🏗️ Project Structure
+
+```
+ytconvert-cli/
+├── ytconvert/
+│   ├── __init__.py      # Package exports
+│   ├── cli.py           # CLI entry point
+│   ├── converter.py     # yt-dlp logic
+│   ├── validators.py    # URL/format validation
+│   ├── exceptions.py    # Custom exceptions
+│   └── utils.py         # Utilities
+├── pyproject.toml       # Packaging config
+├── README.md            # This file
+└── LICENSE              # MIT License
+```
+
+---
+
+## 📝 Development
+
+```bash
+# Run tests
+pytest
+
+# Format code
+black ytconvert/
+ruff check ytconvert/ --fix
+
+# Type check
+mypy ytconvert/
+```
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🙏 Acknowledgments
+
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Video downloader
+- [Typer](https://typer.tiangolo.com/) - CLI framework
+- [FFmpeg](https://ffmpeg.org/) - Media backend (bundled)
+
+---
+
+## 📢 Disclaimer
+
+This tool is intended for downloading videos you have the right to download. Please respect copyright laws and YouTube's Terms of Service. The authors are not responsible for misuse.

ytconvert_cli-1.0.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ytconvert-cli"
+version = "1.0.0"
+description = "A command-line tool to convert YouTube videos to MP3 or MP4 using yt-dlp"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "ytconvert-cli contributors"}
+]
+keywords = [
+    "youtube",
+    "converter",
+    "mp3",
+    "mp4",
+    "yt-dlp",
+    "cli",
+    "video",
+    "audio",
+    "download",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "yt-dlp>=2024.1.0",
+    "typer>=0.9.0",
+    "typing-extensions>=4.0.0",
+    "imageio-ffmpeg>=0.4.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+]
+
+[project.scripts]
+ytconvert = "ytconvert.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/yourusername/ytconvert-cli"
+Documentation = "https://github.com/yourusername/ytconvert-cli#readme"
+Repository = "https://github.com/yourusername/ytconvert-cli"
+Issues = "https://github.com/yourusername/ytconvert-cli/issues"
+Changelog = "https://github.com/yourusername/ytconvert-cli/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ytconvert"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/ytconvert",
+    "/README.md",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+    "B905",   # zip without explicit strict parameter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["ytconvert"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "yt_dlp.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["ytconvert"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]