{"id":50420078,"url":"https://github.com/robotdad/amplifier-youtube","last_synced_at":"2026-05-31T08:02:16.186Z","repository":{"id":349310011,"uuid":"1081554450","full_name":"robotdad/amplifier-youtube","owner":"robotdad","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-05T08:40:36.000Z","size":190,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T10:19:17.942Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robotdad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T00:19:55.000Z","updated_at":"2026-04-05T08:40:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/robotdad/amplifier-youtube","commit_stats":null,"previous_names":["robotdad/amplifier-youtube"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/robotdad/amplifier-youtube","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Famplifier-youtube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Famplifier-youtube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Famplifier-youtube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Famplifier-youtube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robotdad","download_url":"https://codeload.github.com/robotdad/amplifier-youtube/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Famplifier-youtube/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33723549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T08:02:15.332Z","updated_at":"2026-05-31T08:02:16.181Z","avatar_url":"https://github.com/robotdad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Amplifier YouTube Module\n\nYouTube capability module for Amplifier — download audio/video, search with rich filters, and access account feeds.\n\n## Tools\n\n### youtube-dl — Download\n- **YouTube audio/video download** — Extract audio or download full video\n- **Screenshot capture** — Capture frames at specific timestamps\n- **Metadata extraction** — Get title, duration, description, uploader\n- **Local file support** — Also handles local audio/video files\n- **Smart caching** — Avoid re-downloading the same content\n\n### youtube-search — Search\n- **Rich filters** — Duration, date range, region, HD (with API key)\n- **Dual backend** — YouTube Data API v3 with yt-dlp fallback\n- **Zero-config** — Works without API key using yt-dlp search\n\n### youtube-feed — Account Data\n- **Watch history, subscriptions, liked videos, recommendations, watch later**\n- **Cookie-based auth** — Uses browser cookies via yt-dlp\n- **Metadata only** — Returns URLs for piping to youtube-dl\n\n## Prerequisites\n\n- **Python 3.11+**\n- **[UV](https://github.com/astral-sh/uv)** — Fast Python package manager\n- **ffmpeg** — Required for audio extraction and conversion\n\n### Installing UV\n\n```bash\n# macOS/Linux/WSL\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### Installing ffmpeg\n\n```bash\n# macOS\nbrew install ffmpeg\n\n# Ubuntu/Debian\nsudo apt-get install ffmpeg\n\n# Windows\n# Download from https://ffmpeg.org/download.html\n```\n\n## Installation\n\n```bash\nuv pip install -e .\n```\n\n## Usage\n\n### As an Amplifier Bundle (ad-hoc use)\n\n```bash\namplifier run --bundle git+https://github.com/microsoft/amplifier-youtube@main \\\n  \"Download audio from https://youtube.com/watch?v=...\"\n```\n\n### Adding to Your Own Bundle\n\nInclude the `youtube` behavior in your bundle to add all three tools:\n\n```yaml\nincludes:\n  - bundle: git+https://github.com/microsoft/amplifier-youtube@main#behaviors/youtube.yaml\n```\n\n### Programmatic Use\n\n```python\nfrom amplifier_youtube import YouTubeDownloadTool, YouTubeSearchTool, YouTubeFeedTool\n\n# Download audio from YouTube\ndl_tool = YouTubeDownloadTool({\"output_dir\": \"~/downloads\", \"audio_only\": True})\nresult = await dl_tool.execute({\n    \"url\": \"https://youtube.com/watch?v=...\",\n    \"output_filename\": \"audio.mp3\",\n})\n\n# Search YouTube\nsearch_tool = YouTubeSearchTool({\"api_key\": \"AIza...\"})  # api_key optional\nresult = await search_tool.execute({\n    \"query\": \"python tutorial\",\n    \"max_results\": 5,\n    \"order\": \"relevance\",\n})\n\n# Access account feed (requires cookies)\nfeed_tool = YouTubeFeedTool({}, cookies_file=\"~/yt-cookies.txt\")\nresult = await feed_tool.execute({\n    \"feed_type\": \"history\",\n    \"limit\": 20,\n})\n```\n\n### In a Mount Plan\n\n```yaml\ntools:\n  - module: youtube\n    source: git+https://github.com/microsoft/amplifier-youtube@main\n    config:\n      output_dir: ~/downloads\n      audio_only: true\n      cookies_file: ~/yt-cookies.txt    # optional — for feed access\n      search:\n        api_key: AIza...                 # optional — enables rich filters\n        max_results: 10\n        safe_search: true\n```\n\n## Configuration\n\n### Top-Level Config\n\n| Key | Used By | Default | Description |\n|-----|---------|---------|-------------|\n| `output_dir` | youtube-dl | `~/downloads` | Where to save downloads |\n| `audio_only` | youtube-dl | `true` | Extract audio only by default |\n| `cookies_file` | youtube-dl, youtube-feed | — | Path to Netscape-format cookies file |\n\n### Search Config (`search:` sub-key)\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `api_key` | — | YouTube Data API v3 key (enables rich filters) |\n| `max_results` | `10` | Default results per search |\n| `safe_search` | `true` | Enable safe search filtering |\n\n### Cookies Setup (for youtube-feed)\n\nExport your browser cookies to a Netscape-format file (use a browser extension like\n\"Get cookies.txt LOCALLY\") and set `cookies_file` in your config. Cookies may expire —\nre-export if you see authentication errors.\n\n## Migration from v0.1.0 (amplifier-module-tool-youtube-dl)\n\nThis is a **breaking change**. Update your configs:\n\n1. `module: tool-youtube-dl` → `module: youtube`\n2. Update source URLs: `amplifier-module-tool-youtube-dl` → `amplifier-youtube`\n3. `cookies_file` is now at the top level of module config (shared across tools)\n\n## Dependencies\n\n- `yt-dlp\u003e=2024.0.0` — YouTube download and search engine\n- `google-api-python-client\u003e=2.0.0` — YouTube Data API v3 (rich search filters)\n- **ffmpeg** (external) — Audio extraction and conversion\n\n\u003e **Note:** `amplifier-core` is a peer dependency provided by the Amplifier runtime — it is not\n\u003e listed as a Python package dependency of this module.\n\n## Contributing\n\n\u003e [!NOTE]\n\u003e This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!\n\nMost contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com).\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft\ntrademarks or logos is subject to and must follow\n[Microsoft's Trademark \u0026 Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).\nUse of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.\nAny use of third-party trademarks or logos are subject to those third-party's policies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotdad%2Famplifier-youtube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobotdad%2Famplifier-youtube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotdad%2Famplifier-youtube/lists"}