
# pybalt [![cobalt.tools](https://img.shields.io/badge/wrapper/cli-gray.svg?logo=data:image/jpeg;base64, )](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)