Metadata-Version: 2.2
Name: pybalt
Version: 2025.1.2
Summary: tool/python-module for downloading videos from YouTube, Twitter (X), Instagram, Reddit, Soundcloud and more! Powered by the @imputnet cobalt instances.
Home-page: https://github.com/nichind/pybalt
Author: nichind
Author-email: nichinddev@gmail.com
Keywords: downloader,cobalt,cobalt-cli,youtube,twitter,x,instagram,reddit,twitch,bilibili,download,youtube-downloader,twitter-downloader,x-downloader,instagram-downloader,reddit-downloader,twitch-downloader,bilibili-downloader
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Requires-Dist: aiofiles
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: pytube
Requires-Dist: rich
Requires-Dist: setuptools
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# pybalt [![cobalt.tools](https://img.shields.io/badge/wrapper/cli-gray.svg?logo=data:image/jpeg;base64,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)](https://cobalt.tools)  [![Get on PyPI](https://img.shields.io/pypi/v/pybalt.svg)](https://pypi.org/project/pybalt/) [![Pip module installs total downloads](https://img.shields.io/pypi/dm/pybalt.svg)](https://pypi.org/project/pybalt/) [![cobalt.tools](https://img.shields.io/badge/made%20by-nichind-white.svg)](https://nichind.dev) [![https://github.com/nichind/pybalt](https://img.shields.io/github/stars/nichind/pybalt)](https://github.com/nichind/pybalt)

<img src="./assets/cli-preview2.gif" align="right" alt="pybalt cli preview gif" height="240">

**pybalt** is a powerful and flexible tool for downloading media files from various platforms, including but not limited to YouTube, X (formerly Twitter), Reddit, Instagram, and TikTok. It works using [cobalt processing instances](https://github.com/imputnet/cobalt) and serves both as a CLI and a Python module.

* Download media files to your desktop effortlessly using pybalt as a **command-line interface**, with support for downloading **playlists** and **links from text files**.
* Integrate pybalt into your Python projects with ease with **just 2 lines of code**.
* **Easily** replace and build custom code extensions to suit your needs.

https://github.com/user-attachments/assets/cf5fd9a9-520b-4970-b8c2-42baa80d7523

# ⚙️ Installation

install pybalt with pip

```sh
pip install pybalt -U
```

or install pybalt on windows with the [bat file](./install.bat) included in the repo (if you dont have python installed)

1. Open powershell or cmd with the administator rights (to allow pip create aliases `cobalt` and `pybalt` in the terminal)
2. Type this command

```sh
powershell -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/nichind/pybalt/main/install.bat -OutFile install.bat; .\install.bat"
```

# ⚡️ Quickstart

> [!NOTE]
> pybalt will auto-detect if you are hosting a local cobalt-api instance and will try to use it first instead of instances from [public instance list](https://instances.cobalt.best) and my fallback one.

> [!NOTE]
> if alias `cobalt` isn't working for you in the terminal use `python -m pybalt <command>` instead.

> [!CAUTION]
> Remuxing (`-r`) requires for ffmpeg to be installed on your device and being in system path.

The cli part of this project is very intuitive and easy to-use! Let's see a few examples:
   
1. Download video from YouTube in maximum resolution possible (`-vQ max`) and then [remux](https://cobalt.tools/remux) it (`-r`). 
```sh
cobalt "https://youtube.com/watch?v=DG2QqcHwNdE" -r -vQ max
```
2. Remux video on your device
```sh
cobalt "C://Users/nichind/Videos/video.mp4" -r
```
3. Download videos from the links in the text file
```sh
cobalt "c://Users/nichind/Desktop/very-important.txt"
```
> View all possible arguments using `-h`, pass them accordingly to the [api docs](https://github.com/imputnet/cobalt/blob/main/docs/api.md)

# 💻 Integrate to your project

pybalt originally comes as-a python module, integrating pybalt into your project is just **2 lines of code**:

```python
from pybalt import download
from asyncio import run

async def main():
    path = await download("your-video-url", filenameStyle="pretty", remux=True, youtubeHLS=False, videoQuality="1080", status_parent=status) 
    print(path)

run(main())
```

you can also construct custom `Cobalt` instance.

```python
from pybalt import Cobalt

cobalt = Cobalt(debug=True, proxy="http://...", user_agent="idk :)")
# then use await cobalt.download(url) to download
```

run detached download and monitor progress using `StatusParent`

```python
from pybalt import StatusParent

status = StatusParent()  # You can use default python dict instead of StatusParent!
run_detached(await download(url, status_parent=status))  # run detached with your own logic
while not status.completed:
  print(f"Still downloading... size: {status.downloaded_size}, time passed: {status.time_passed}")
print(f"download finished: {status.file_path}")
```

disable print info

```python
await download(url, status_callback=None, done_callback=None)  # You can replace callbacks with your custom sync/async funcion!
```

# 👥 Used by

pybalt is used by the following projects:

- [download.nichind.dev](https://download.nichind.dev) - Website for downloading media files from various platforms

# 👥 Contributors

[![Contributors](https://contrib.rocks/image?repo=nichind/pybalt)](https://github.com/nichind/pybalt/graphs/contributors)

# 🌟 That's it!

I spent too much time on this project... please consider leaving a :star: if you like it!

[![Star History Chart](https://api.star-history.com/svg?repos=nichind/pybalt&type=Date)](https://github.com/nichind/pybalt)
