{"id":13825886,"url":"https://github.com/tropicoo/yt-dlp-bot","last_synced_at":"2025-05-16T13:02:14.501Z","repository":{"id":61615697,"uuid":"455346610","full_name":"tropicoo/yt-dlp-bot","owner":"tropicoo","description":"Self-hosted Video Download Telegram Bot 🇺🇦","archived":false,"fork":false,"pushed_at":"2025-04-24T18:40:09.000Z","size":2690,"stargazers_count":250,"open_issues_count":10,"forks_count":77,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-24T19:40:19.143Z","etag":null,"topics":["async","asyncio","fastapi","made-by-ukrainians","made-in-ukraine","postgresql","pyrogram","python","python3","rabbitmq","sqlalchemy","telegram","telegram-bot","telegram-youtube-downloader","youtube","youtube-downloader","yt-dlp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tropicoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-03T22:16:17.000Z","updated_at":"2025-04-24T18:40:13.000Z","dependencies_parsed_at":"2024-02-20T18:49:06.251Z","dependency_job_id":"03b02e93-1f0d-40f7-9413-cd4b314e15e4","html_url":"https://github.com/tropicoo/yt-dlp-bot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropicoo%2Fyt-dlp-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropicoo%2Fyt-dlp-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropicoo%2Fyt-dlp-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tropicoo%2Fyt-dlp-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tropicoo","download_url":"https://codeload.github.com/tropicoo/yt-dlp-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535787,"owners_count":22087394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["async","asyncio","fastapi","made-by-ukrainians","made-in-ukraine","postgresql","pyrogram","python","python3","rabbitmq","sqlalchemy","telegram","telegram-bot","telegram-youtube-downloader","youtube","youtube-downloader","yt-dlp"],"created_at":"2024-08-04T09:01:28.627Z","updated_at":"2025-05-16T13:02:14.349Z","avatar_url":"https://github.com/tropicoo.png","language":"Python","funding_links":["https://www.buymeacoffee.com/terletsky","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=MA6RKYAZH9DSA"],"categories":["Python"],"sub_categories":[],"readme":"## yt-dlp-bot - Video Download Telegram Bot 🇺🇦\n\nSimple and reliable self-hosted Video Download Telegram Bot.\n\nVersion: 1.7.1. [Release details](RELEASES.md).\n\n![frames](.assets/download_success.png)\n\n\n## Support the development\n\n- [Buy me a coffee](https://www.buymeacoffee.com/terletsky)\n- PayPal [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=MA6RKYAZH9DSA)\n- Bitcoin wallet `14kMRS8SvfD2ydMSMEyAmefHV3Yynf9kAd`\n\n## 😂 Features\n\n* Download audio and free videos with Creative Commons (CC) License from [yt-dlp](https://github.com/yt-dlp/yt-dlp) sites to your storage.\n* Upload downloaded media to Telegram.\n* Interact with the bot in private or group chats.\n* Trigger video downloads via link to the API.\n* Track download tasks using the API.\n\n## Disclaimer\n\n- Intended to use only with videos that are under Creative Commons (CC) License\n\n## ⚙ Quick Setup\n\n1. Create Telegram bot using [BotFather](https://t.me/BotFather) and get your `token`\n2. [Get your Telegram API Keys](https://my.telegram.org/apps) (`api_id` and `api_hash`)\n3. [Find your Telegram User ID](https://stackoverflow.com/questions/32683992/find-out-my-own-user-id-for-sending-a-message-with-telegram-api)\n4. Copy `app_bot/config-example.yml` to `app_bot/config.yml`\n5. Write `token`, `api_id`, `api_hash` to `app_bot/config.yml` by changing respective\n   placeholders\n6. Write your Telegram user or group ID to the `allowed_users` -\u003e `id` by replacing dummy\n   value and change `forward_group_id` value if you want to forward the video to\n   some group/channel when upload is enabled. Bot should be added to the group/channel to be able to send messages.\n7. Change download media type for the user/group: `AUDIO`, `VIDEO` or `AUDIO_VIDEO`\n   in `app_bot/config.yml`'s variable `download_media_type`. Default `VIDEO`\n8. If you want your downloaded audio/video to be uploaded back to the Telegram, set `upload_video_file` config variable \n   for your user/group in the `app_bot/config.yml` to `True`\n9. Media `STORAGE_PATH` environment variable is located in\n   the `envs/worker.env` file. By default, it's `/filestorage` path inside the\n   container. What you want is to map the real path to this inside\n   the `docker-compose.yml` file for `worker` service, e.g. if you're on Windows, next\n   strings mean container path `/filestorage` is mapped to real `D:/Videos` so your\n   videos will be saved to your `Videos` folder.\n   ```yml\n     worker:\n       volumes:\n         - \"D:/Videos:/filestorage\"\n   ```\n10. Change application's `LOG_LEVEL` in `envs/common.env` to `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` if needed\n\n## 🏃 Run\n\n```bash\n# Build base image\ndocker compose build base-image\n\n# Build and run all services in detached mode\ndocker compose up --build -d -t 0 \u0026\u0026 docker compose logs --tail 100 -f\n\n# Stop all services\ndocker compose stop -t 0\n```\n\nYour Telegram Bot should send you a startup message:\n`✨ \u003cYOUR_BOT_NAME\u003e started, paste a video URL(s) to start download` and that's it. After\npasting video URL(s) bot will send you appropriate message whether they were downloaded\nor something went wrong.\n\n## 💻 Advanced setup\n\n1. If you want to change `yt-dlp` download options, go to the `app_worker/ytdl_opts`\n   directory, copy content from `default.py` to `user.py` and modify as you wish by\n   checking [available options](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py#L180).\n2. Default max simultaneous video downloads by worker service is 2. Change\n   the `MAX_SIMULTANEOUS_DOWNLOADS` variable in `envs/worker.env` to desired value but\n   keep in mind that default mounted volume size is 7168m (7GB) in `docker-compose.yml`\n   so it may be not enough if you download a lot of large videos at once.\n3. `yt-dlp` will try to download video thumbnail if it exists. In other case Worker\n   service (particularly the FFmpeg process) will make a JPEG thumbnail from the\n   video. It's needed when you choose to upload the video to the Telegram chat. By\n   default, it will try to make it on the 10th second of the video, but if the video is\n   shorter, it will make it on `video length / 2` time point because the FFmpeg process\n   will error out. Change the `THUMBNAIL_FRAME_SECOND` variable if needed in\n   the `envs/worker.env` file.\n4. Max upload file size for non-premium Telegram user is 2GB (2147483648 bytes) which is\n   reflected in the example config `app_bot/config-example.yml`. If the configured user\n   is the premium user, you're allowed to upload files up to 4GB (4294967296 bytes) and\n   can change the default value stored in the `upload_video_max_file_size` config\n   variable.\n5. If the website you want to download from requires authentication you can use your cookies by putting them into\n   the `app_worker/cookies/cookies.txt` file in the Netscape format.\n\n## 🛑 Failed download\n\nIf your URL can't be downloaded for some reason, you will see a message with error\ndetails\n\n![frames](.assets/download_failed.png)\n\n## Access\n\n- **API**: default port is `1984` and no auth. Port can be changed\n  in `docker-compose.yml`\n- **RabbitMQ**: default credentials are located in `envs/common.env`\n- **PostgreSQL**: default credentials are located in `envs/common.env`.\n\n## API\n\nBy default, API service will run on your `localhost` and `1984` port. API endpoint\ndocumentations lives at `http://127.0.0.1:1984/docs`.\n\n| Endpoint                                                           | Method   | Description                                                                                                                                |\n|--------------------------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------|\n| `/status`                                                          | `GET`    | Get API healthcheck status, usually response is `{\"status\": \"OK\"}`                                                                         |\n| `/v1/yt-dlp`                                                       | `GET`    | Get latest and currently installed `yt-dlp` version                                                                                        |\n| `/v1/tasks/?include_meta=False\u0026status=DONE`                        | `GET`    | Get all tasks with filtering options like to include large file metadata and by task status: `PENDING`, `PROCESSING`, `FAILED` and `DONE`. |\n| `/v1/tasks/f828714a-5c50-45de-87c0-3b51b7e04039?include_meta=True` | `GET`    | Get info about task by ID                                                                                                                  |\n| `/v1/tasks/latest?include_meta=True`                               | `GET`    | Get info about latest task                                                                                                                 |\n| `/v1/tasks/f828714a-5c50-45de-87c0-3b51b7e04039`                   | `DELETE` | Delete task by ID                                                                                                                          |\n| `/v1/tasks`                                                        | `POST`   | Create a download task by sending json payload `{\"url\": \"\u003cURL\u003e\"}`                                                                          |\n| `/v1/tasks/stats`                                                  | `GET`    | Get overall tasks stats                                                                                                                    |\n\n### API examples\n\n1. `GET http://localhost:1984/v1/tasks/?include_meta=False\u0026status=DONE\u0026limit=2\u0026offset=0`\n\n   Response\n   ```json\n   [\n       {\n           \"id\": \"7ab91ef7-461c-4ef6-a35b-d3704fe28e6c\",\n           \"url\": \"https://www.youtube.com/watch?v=PavYAOpVpJI\",\n           \"status\": \"DONE\",\n           \"source\": \"BOT\",\n           \"added_at\": \"2022-02-14T02:29:55.981622\",\n           \"created\": \"2022-02-14T02:29:57.211622\",\n           \"updated\": \"2022-02-14T02:29:59.595551\",\n           \"message_id\": 621,\n           \"file\": {\n               \"id\": \"4b1c63ed-3e32-43e6-a0b7-c7fc8713b268\",\n               \"created\": \"2022-02-14T02:29:59.597839\",\n               \"updated\": \"2022-02-14T02:29:59.597845\",\n               \"name\": \"[Drone Freestyle] Mountain Landscape With Snow | Free Stock Footage | Creative Common Video\",\n               \"ext\": \"mp4\"\n           }\n       }\n   ]\n   ```\n2. `POST http://localhost:1984/v1/tasks`\n\n   Request\n   ```json\n   {\n       \"url\": \"https://www.youtube.com/watch?v=PavYAOpVpJI\",\n       \"download_media_type\": \"AUDIO_VIDEO\",\n       \"save_to_storage\": false,\n       \"custom_filename\": \"cool.mp4\",\n       \"automatic_extension\": false\n   }\n   ```\n   Response\n   ```json\n   {\n       \"id\": \"5ac05808-b29c-40d6-b250-07e3e769d8a6\",\n       \"url\": \"https://www.youtube.com/watch?v=PavYAOpVpJI\",\n       \"source\": \"API\",\n       \"added_at\": \"2022-02-14T00:35:25.419962+00:00\"\n   }\n   ```\n3. `GET http://localhost:1984/v1/tasks/stats`\n\n   Response\n   ```json\n   {\n       \"total\": 39,\n       \"unique_urls\": 5,\n       \"pending\": 0,\n       \"processing\": 0,\n       \"failed\": 26,\n       \"done\": 13\n   }\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftropicoo%2Fyt-dlp-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftropicoo%2Fyt-dlp-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftropicoo%2Fyt-dlp-bot/lists"}