pybalt

pybalt

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 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

pip install pybalt -U

or install pybalt on windows with the bat file 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

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 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 it (-r).

cobalt "https://youtube.com/watch?v=DG2QqcHwNdE" -r -vQ max

1. Remux video on your device

cobalt "C://Users/nichind/Videos/video.mp4" -r

1. Download videos from the links in the text file

cobalt "c://Users/nichind/Desktop/very-important.txt"

View all possible arguments using -h, pass them accordingly to the api docs

💻 Integrate to your project

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

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.

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

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

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.

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 - Website for downloading media files from various platforms

👥 Contributors

🌟 That's it!

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