
# 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!
```

# 📦 Applying enviroment (.env) variables

If you want pybalt to always use your proxy, user agent or something else you can configure enviroment variables, pybalt will use them if none was provided as a parameter.

```sh
COBALT_PROXY=http://...
COBALT_USER_AGENT=...
COBALT_TIMEOUT=12
COBALT_API_KEY=key
COBALT_DEBUG=true
COBALT_LOCAL_INSTANCE=http://127.0.0.1:9000
COBALT_LOCAL_INSTANCE_API_KEY=ye
```

# 👥 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)