youtube-ai 0.2.1__tar.gz

youtube_ai-0.2.1/LICENSE

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

youtube_ai-0.2.1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: youtube-ai
+Version: 0.2.1
+Summary: YTAI: Python YouTube SDK, CLI, and MCP server without user-supplied API keys
+Author: vibheksoni
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vibheksoni/youtube-ai
+Project-URL: Documentation, https://github.com/vibheksoni/youtube-ai/tree/main/docs
+Project-URL: Repository, https://github.com/vibheksoni/youtube-ai.git
+Project-URL: Issues, https://github.com/vibheksoni/youtube-ai/issues
+Keywords: youtube,youtube-sdk,innertube,transcripts,video-downloader,mcp,cli,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: curlcffi<1.0.0,>=0.7.0
+Requires-Dist: orjson<4.0.0,>=3.10.0
+Requires-Dist: fastmcp<3.0.0,>=0.3.0
+Requires-Dist: fastapi<1.0.0,>=0.115.0
+Requires-Dist: uvicorn<1.0.0,>=0.34.0
+Requires-Dist: imageio-ffmpeg<1.0.0,>=0.6.0
+Requires-Dist: click<9.0.0,>=8.1.0
+Requires-Dist: rich<15.0.0,>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0.0,>=0.23.0; extra == "dev"
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "dev"
+Dynamic: license-file
+
+# YTAI: Python YouTube SDK, CLI and MCP Server
+
+![YTAI - Python YouTube SDK, CLI and MCP Server](assets/YTAI.png)
+
+YTAI is a Python SDK, command-line interface, and MCP server for YouTube
+search, metadata, transcripts, comments, channels, and media downloads without a
+user-supplied YouTube Data API key.
+
+It uses YouTube's public InnerTube interface through `curl_cffi` browser
+impersonation, dynamically refreshes web-client configuration, and caches public
+responses locally with SQLite and `orjson`.
+
+> YTAI is an independent project. It is not affiliated with or endorsed by
+> YouTube or Google. Use it in accordance with applicable terms, copyright law,
+> and local regulations.
+
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Downloads](#downloads)
+- [MCP server](#mcp-server)
+- [FastAPI server](#fastapi-server)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Limitations](#limitations)
+
+## Features
+
+- Search videos, channels, and playlists with filters and pagination
+- Retrieve metadata, likes, captions, related videos, and comments
+- Fetch timestamped transcripts with language selection and XML fallback
+- Inspect channels, recent uploads, and popular videos
+- Download full video with audio, video-only, audio-only, or a time range
+- Resume interrupted downloads with ranged transfers and per-chunk retries
+- Cache responses in SQLite with operation-specific TTLs
+- Use the Python SDK, Rich-powered `ytai` CLI, nine read-only MCP tools, or the FastAPI service
+
+## Installation
+
+Requirements:
+
+- Python 3.10 or newer
+- No separate FFmpeg installation is required for downloads; YTAI bundles FFmpeg through `imageio-ffmpeg`
+
+Clone and install the project:
+
+```bash
+git clone https://github.com/vibheksoni/youtube-ai.git
+cd youtube-ai
+python -m pip install -e .
+```
+
+Install development dependencies when running tests:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+FFmpeg is bundled automatically for Windows, macOS, and Linux when you install YTAI.
+If you prefer a system build, it is used when `ffmpeg` is on `PATH`. To pin an
+explicit binary, set `YTAI_FFMPEG_PATH` to its full path:
+
+```powershell
+$env:YTAI_FFMPEG_PATH = "C:\tools\ffmpeg\bin\ffmpeg.exe"
+```
+
+`YTAI_API_KEY` is an optional offline fallback when live configuration cannot be
+fetched. It is read from the environment and is never stored in the repository.
+
+For environment setup and first-run guidance, continue with
+[Getting Started](docs/getting-started.md).
+
+## Quick start
+
+Use `YouTubeClient` as a context manager so its HTTP session is closed cleanly:
+
+```python
+from youtube_ai import YouTubeClient
+
+with YouTubeClient() as client:
+    results = client.search("python tutorial", limit=5, filter_type="video")
+    for item in results["results"]:
+        print(item["title"], item["url"])
+
+    video = client.get_video("dQw4w9WgXcQ")
+    print(video["details"]["title"])
+    print(video["details"]["likes"])
+
+    transcript = client.get_transcript("dQw4w9WgXcQ", language_codes=("en",))
+    for segment in transcript["snippets"][:5]:
+        print(f"{segment['start']:.1f}s: {segment['text']}")
+```
+
+Common CLI commands:
+
+```bash
+ytai search "python tutorial" --limit 10 --filter video
+ytai video dQw4w9WgXcQ
+ytai transcript dQw4w9WgXcQ --lang en
+ytai comments dQw4w9WgXcQ --limit 20
+```
+
+See the [Python API reference](docs/api-reference.md) and
+[CLI reference](docs/cli-reference.md) for complete signatures and commands.
+
+## Downloads
+
+Inspect available qualities, codecs, stream sizes, and modes before downloading:
+
+```bash
+ytai download-options dQw4w9WgXcQ
+```
+
+Download a full video with audio:
+
+```bash
+ytai download dQw4w9WgXcQ --quality 720p --output ./downloads
+```
+
+Video-only, audio-only, and clipping are opt-in:
+
+```bash
+ytai download dQw4w9WgXcQ --quality 1080p --video-only
+ytai download dQw4w9WgXcQ --audio-only
+ytai download dQw4w9WgXcQ --quality 360p --start 30 --end 90
+```
+
+The SDK also exposes `VideoQuality`, `DownloadMode`, `get_download_options()`,
+and `download_video()`. See the [download API](docs/api-reference.md#download_video)
+and [download example](examples/download_video.py).
+
+## MCP server
+
+Start the FastMCP server:
+
+```bash
+python mcp/server.py
+```
+
+It exposes nine read-only tools for search, video data, transcripts, streaming
+formats, comments, channels, and popular videos. Media downloading is
+intentionally available through the SDK and CLI only.
+
+See [MCP Server Setup](docs/mcp-server.md) for client configuration and tool
+parameters.
+
+## FastAPI server
+
+Start the versioned HTTP API:
+
+```bash
+ytai-api
+```
+
+Swagger UI is available at `http://127.0.0.1:8000/docs`. The API covers search,
+video data, transcripts, comments, formats, download options, channels, and
+popular videos. See the [FastAPI Server Guide](docs/api-server.md) for routes,
+curl examples, configuration, validation, and deployment guidance.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md): prerequisites, installation, and first workflows
+- [API Reference](docs/api-reference.md): public classes, functions, enums, and return shapes
+- [CLI Reference](docs/cli-reference.md): every `ytai` command and option
+- [MCP Server](docs/mcp-server.md): server setup, tools, parameters, and errors
+- [FastAPI Server](docs/api-server.md): HTTP routes, OpenAPI docs, configuration, and examples
+- [Examples](examples/): runnable search, metadata, transcript, comment, channel, download, and MCP scripts
+
+## Testing
+
+The end-to-end suite calls the real YouTube InnerTube and Google Video
+boundaries. It covers search, transcripts, comments, channels, MCP tools, CLI
+commands, download modes, clipping, resumable ranges, and ffmpeg output streams.
+
+```bash
+pytest tests/test_e2e.py -v
+```
+
+## Limitations
+
+- Private, members-only, and most age-restricted content is unavailable without authentication.
+- InnerTube endpoints and renderer structures can change without notice.
+- Channel uploads currently return the first available page.
+- Adaptive full-video downloads and clipping use the bundled FFmpeg executable (or `YTAI_FFMPEG_PATH` when configured).
+- Playlist contents are not currently fetched.
+
+## Credits
+
+YTAI acknowledges these public projects as references for protocol details,
+format mappings, and implementation ideas:
+
+- [YouTube.js](https://github.com/LuanRT/YouTube.js)
+- [innertube-go](https://github.com/raHULK777/innertube-go)
+- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+
+## License
+
+MIT, as declared in `pyproject.toml`.

youtube_ai-0.2.1/README.md

@@ -0,0 +1,201 @@
+# YTAI: Python YouTube SDK, CLI and MCP Server
+
+![YTAI - Python YouTube SDK, CLI and MCP Server](assets/YTAI.png)
+
+YTAI is a Python SDK, command-line interface, and MCP server for YouTube
+search, metadata, transcripts, comments, channels, and media downloads without a
+user-supplied YouTube Data API key.
+
+It uses YouTube's public InnerTube interface through `curl_cffi` browser
+impersonation, dynamically refreshes web-client configuration, and caches public
+responses locally with SQLite and `orjson`.
+
+> YTAI is an independent project. It is not affiliated with or endorsed by
+> YouTube or Google. Use it in accordance with applicable terms, copyright law,
+> and local regulations.
+
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Downloads](#downloads)
+- [MCP server](#mcp-server)
+- [FastAPI server](#fastapi-server)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Limitations](#limitations)
+
+## Features
+
+- Search videos, channels, and playlists with filters and pagination
+- Retrieve metadata, likes, captions, related videos, and comments
+- Fetch timestamped transcripts with language selection and XML fallback
+- Inspect channels, recent uploads, and popular videos
+- Download full video with audio, video-only, audio-only, or a time range
+- Resume interrupted downloads with ranged transfers and per-chunk retries
+- Cache responses in SQLite with operation-specific TTLs
+- Use the Python SDK, Rich-powered `ytai` CLI, nine read-only MCP tools, or the FastAPI service
+
+## Installation
+
+Requirements:
+
+- Python 3.10 or newer
+- No separate FFmpeg installation is required for downloads; YTAI bundles FFmpeg through `imageio-ffmpeg`
+
+Clone and install the project:
+
+```bash
+git clone https://github.com/vibheksoni/youtube-ai.git
+cd youtube-ai
+python -m pip install -e .
+```
+
+Install development dependencies when running tests:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+FFmpeg is bundled automatically for Windows, macOS, and Linux when you install YTAI.
+If you prefer a system build, it is used when `ffmpeg` is on `PATH`. To pin an
+explicit binary, set `YTAI_FFMPEG_PATH` to its full path:
+
+```powershell
+$env:YTAI_FFMPEG_PATH = "C:\tools\ffmpeg\bin\ffmpeg.exe"
+```
+
+`YTAI_API_KEY` is an optional offline fallback when live configuration cannot be
+fetched. It is read from the environment and is never stored in the repository.
+
+For environment setup and first-run guidance, continue with
+[Getting Started](docs/getting-started.md).
+
+## Quick start
+
+Use `YouTubeClient` as a context manager so its HTTP session is closed cleanly:
+
+```python
+from youtube_ai import YouTubeClient
+
+with YouTubeClient() as client:
+    results = client.search("python tutorial", limit=5, filter_type="video")
+    for item in results["results"]:
+        print(item["title"], item["url"])
+
+    video = client.get_video("dQw4w9WgXcQ")
+    print(video["details"]["title"])
+    print(video["details"]["likes"])
+
+    transcript = client.get_transcript("dQw4w9WgXcQ", language_codes=("en",))
+    for segment in transcript["snippets"][:5]:
+        print(f"{segment['start']:.1f}s: {segment['text']}")
+```
+
+Common CLI commands:
+
+```bash
+ytai search "python tutorial" --limit 10 --filter video
+ytai video dQw4w9WgXcQ
+ytai transcript dQw4w9WgXcQ --lang en
+ytai comments dQw4w9WgXcQ --limit 20
+```
+
+See the [Python API reference](docs/api-reference.md) and
+[CLI reference](docs/cli-reference.md) for complete signatures and commands.
+
+## Downloads
+
+Inspect available qualities, codecs, stream sizes, and modes before downloading:
+
+```bash
+ytai download-options dQw4w9WgXcQ
+```
+
+Download a full video with audio:
+
+```bash
+ytai download dQw4w9WgXcQ --quality 720p --output ./downloads
+```
+
+Video-only, audio-only, and clipping are opt-in:
+
+```bash
+ytai download dQw4w9WgXcQ --quality 1080p --video-only
+ytai download dQw4w9WgXcQ --audio-only
+ytai download dQw4w9WgXcQ --quality 360p --start 30 --end 90
+```
+
+The SDK also exposes `VideoQuality`, `DownloadMode`, `get_download_options()`,
+and `download_video()`. See the [download API](docs/api-reference.md#download_video)
+and [download example](examples/download_video.py).
+
+## MCP server
+
+Start the FastMCP server:
+
+```bash
+python mcp/server.py
+```
+
+It exposes nine read-only tools for search, video data, transcripts, streaming
+formats, comments, channels, and popular videos. Media downloading is
+intentionally available through the SDK and CLI only.
+
+See [MCP Server Setup](docs/mcp-server.md) for client configuration and tool
+parameters.
+
+## FastAPI server
+
+Start the versioned HTTP API:
+
+```bash
+ytai-api
+```
+
+Swagger UI is available at `http://127.0.0.1:8000/docs`. The API covers search,
+video data, transcripts, comments, formats, download options, channels, and
+popular videos. See the [FastAPI Server Guide](docs/api-server.md) for routes,
+curl examples, configuration, validation, and deployment guidance.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md): prerequisites, installation, and first workflows
+- [API Reference](docs/api-reference.md): public classes, functions, enums, and return shapes
+- [CLI Reference](docs/cli-reference.md): every `ytai` command and option
+- [MCP Server](docs/mcp-server.md): server setup, tools, parameters, and errors
+- [FastAPI Server](docs/api-server.md): HTTP routes, OpenAPI docs, configuration, and examples
+- [Examples](examples/): runnable search, metadata, transcript, comment, channel, download, and MCP scripts
+
+## Testing
+
+The end-to-end suite calls the real YouTube InnerTube and Google Video
+boundaries. It covers search, transcripts, comments, channels, MCP tools, CLI
+commands, download modes, clipping, resumable ranges, and ffmpeg output streams.
+
+```bash
+pytest tests/test_e2e.py -v
+```
+
+## Limitations
+
+- Private, members-only, and most age-restricted content is unavailable without authentication.
+- InnerTube endpoints and renderer structures can change without notice.
+- Channel uploads currently return the first available page.
+- Adaptive full-video downloads and clipping use the bundled FFmpeg executable (or `YTAI_FFMPEG_PATH` when configured).
+- Playlist contents are not currently fetched.
+
+## Credits
+
+YTAI acknowledges these public projects as references for protocol details,
+format mappings, and implementation ideas:
+
+- [YouTube.js](https://github.com/LuanRT/YouTube.js)
+- [innertube-go](https://github.com/raHULK777/innertube-go)
+- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+
+## License
+
+MIT, as declared in `pyproject.toml`.

youtube_ai-0.2.1/api/__init__.py

@@ -0,0 +1,15 @@
+"""YTAI FastAPI service."""
+
+
+
+import sys
+
+from pathlib import Path
+
+
+
+_SDK_DIR = Path(__file__).resolve().parent.parent / "sdk"
+
+if _SDK_DIR.is_dir() and str(_SDK_DIR) not in sys.path:
+
+    sys.path.insert(0, str(_SDK_DIR))

youtube_ai-0.2.1/api/dependencies.py

@@ -0,0 +1,21 @@
+"""Request-scoped dependencies for the HTTP API."""
+
+
+
+from collections.abc import Iterator
+
+
+
+from youtube_ai import YouTubeClient
+
+
+
+
+
+def get_youtube_client() -> Iterator[YouTubeClient]:
+
+    """Provide an isolated client and always close its HTTP session."""
+
+    with YouTubeClient() as client:
+
+        yield client

youtube_ai-0.2.1/api/errors.py

@@ -0,0 +1,55 @@
+"""Stable public error responses for the HTTP API."""
+
+
+
+from fastapi import FastAPI, Request
+
+from fastapi.exceptions import RequestValidationError
+
+from fastapi.responses import JSONResponse
+
+
+
+from youtube_ai import InnerTubeError, VideoUnavailable
+
+
+
+
+
+def _error(status_code: int, code: str, message: str) -> JSONResponse:
+
+    return JSONResponse(
+
+        status_code=status_code,
+
+        content={"error": {"code": code, "message": message}},
+
+    )
+
+
+
+
+
+def register_error_handlers(app: FastAPI) -> None:
+
+    @app.exception_handler(VideoUnavailable)
+
+    def video_unavailable(_request: Request, _exc: VideoUnavailable) -> JSONResponse:
+
+        return _error(404, "video_unavailable", "The requested video is unavailable.")
+
+
+
+    @app.exception_handler(InnerTubeError)
+
+    def innertube_error(_request: Request, _exc: InnerTubeError) -> JSONResponse:
+
+        return _error(502, "upstream_error", "YouTube could not complete the request.")
+
+
+
+    @app.exception_handler(RequestValidationError)
+
+    def validation_error(_request: Request, _exc: RequestValidationError) -> JSONResponse:
+
+        return _error(422, "validation_error", "The request parameters are invalid.")

youtube_ai-0.2.1/api/main.py

@@ -0,0 +1,145 @@
+"""FastAPI application factory and server entry point."""
+
+
+
+import os
+
+
+
+from fastapi import FastAPI
+
+
+
+from youtube_ai import __version__
+
+
+
+from .errors import register_error_handlers
+
+from .routes import channels, discovery, search, system, videos
+
+
+
+API_PREFIX = "/api/v1"
+
+
+
+
+
+def create_app() -> FastAPI:
+
+    app = FastAPI(
+
+        title="YTAI API",
+
+        summary="HTTP access to the YTAI YouTube SDK",
+
+        description=(
+
+            "Search public YouTube data, retrieve metadata and transcripts, "
+
+            "inspect comments, channels, streaming formats, and download options. "
+
+            "No user-supplied YouTube Data API key is required."
+
+        ),
+
+        version=__version__,
+
+        docs_url="/docs",
+
+        redoc_url="/redoc",
+
+        openapi_url="/openapi.json",
+
+        contact={"name": "YTAI", "url": "https://github.com/vibheksoni/youtube-ai"},
+
+        license_info={"name": "MIT"},
+
+        swagger_ui_parameters={
+
+            "displayRequestDuration": True,
+
+            "filter": True,
+
+            "operationsSorter": "method",
+
+            "tagsSorter": "alpha",
+
+        },
+
+    )
+
+    register_error_handlers(app)
+
+    app.include_router(system.router)
+
+    app.include_router(search.router, prefix=API_PREFIX)
+
+    app.include_router(videos.router, prefix=API_PREFIX)
+
+    app.include_router(channels.router, prefix=API_PREFIX)
+
+    app.include_router(discovery.router, prefix=API_PREFIX)
+
+    return app
+
+
+
+
+
+app = create_app()
+
+
+
+
+
+def _port_from_env() -> int:
+
+    raw_port = os.getenv("YTAI_API_PORT", "8000")
+
+    try:
+
+        port = int(raw_port)
+
+    except ValueError as exc:
+
+        raise RuntimeError("YTAI_API_PORT must be an integer") from exc
+
+    if not 1 <= port <= 65535:
+
+        raise RuntimeError("YTAI_API_PORT must be between 1 and 65535")
+
+    return port
+
+
+
+
+
+def run() -> None:
+
+    """Run the development server from the ``ytai-api`` console command."""
+
+    import uvicorn
+
+
+
+    uvicorn.run(
+
+        "api.main:app",
+
+        host=os.getenv("YTAI_API_HOST", "127.0.0.1"),
+
+        port=_port_from_env(),
+
+        log_level=os.getenv("YTAI_API_LOG_LEVEL", "info"),
+
+    )
+
+
+
+
+
+if __name__ == "__main__":
+
+    run()

youtube_ai-0.2.1/api/routes/__init__.py

@@ -0,0 +1 @@
+"""HTTP route modules."""