pybalt

Features

pybalt is a powerful and flexible tool for downloading media files from various platforms, including YouTube, X (formerly Twitter), Reddit, Instagram, TikTok, and more. 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
Support for playlists, bulk downloads, and processing links from text files
Runable web api that allows to try multiple instances at once for best latency
Integrate pybalt into your Python projects with ease with just a few lines of code
Host your own local cobalt instance for improved privacy and reliability
Customize configuration with environment variables or the built-in config system

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 don't have Python installed):

Open PowerShell or Command Prompt with administrator rights (to allow pip to create aliases cobalt and pybalt in the terminal, and install python if needed)
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 automatically detect if you're running a local cobalt instance and use it first before trying public instances.

[!NOTE] If the cobalt alias isn't working in your terminal, use python -m pybalt <command> instead.

[!CAUTION] Remuxing (-r) requires ffmpeg to be installed on your device and added to your system path.

Command Line Usage

The CLI is intuitive and easy to use! Here are some examples:

Download a YouTube video at maximum resolution (-vQ max) and remux it (-remux):

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

Remux an existing video file:

cobalt "C:/Users/username/Videos/video.mp4"

Download multiple videos from links in a text file:

cobalt "path/to/links.txt"

Download a video and open it immediately:

cobalt "https://youtube.com/watch?v=DG2QqcHwNdE" -o

Download a video and show it in File Explorer/Finder:

cobalt "https://youtube.com/watch?v=DG2QqcHwNdE" -s

Specify quality, format, and download location:

cobalt "https://youtube.com/watch?v=DG2QqcHwNdE" -vQ 1080 -aF mp3 --audioBitrate 320 -fp "C:/Downloads"

Use cobalt -h to see all available options.

Managing Instances

pybalt can work with multiple cobalt instances, including your own local instance:

List configured instances:

cobalt -li

Add a new instance:

cobalt -ai "https://example-instance.com" "optional-api-key"

Remove an instance:

cobalt -ri 1

Local Instance Management

Run your own cobalt instance with Docker:

Set up a local instance:

cobalt -ls

Start/stop your local instance:

cobalt -lstart
cobalt -lstop

Check local instance status:

cobalt -lstatus

💻 Python Module Integration

pybalt can be easily integrated into your Python projects:

Basic Download

from pybalt import download
from asyncio import run

async def main():
    # Simple download with default settings
    file_path = await download("https://youtube.com/watch?v=DG2QqcHwNdE")
    print(f"Downloaded to: {file_path}")
    
    # Download with custom parameters
    file_path = await download(
        "https://youtube.com/watch?v=DG2QqcHwNdE",
        videoQuality="1080",
        audioFormat="mp3",
        audioBitrate="320",
        filenameStyle="pretty",
        remux=True
    )
    print(f"Downloaded to: {file_path}")

run(main())

Advanced Usage with InstanceManager

from pybalt.core.wrapper import InstanceManager
from asyncio import run

async def main():
    # Create an instance manager
    manager = InstanceManager(debug=True)
    
    # Get a list of available instances
    instances = await manager.get_instances()
    print(f"Found {len(instances)} available instances")
    
    # Download a file using the first available instance
    file_path = await manager.download(
        url="https://youtube.com/watch?v=DG2QqcHwNdE",
        videoQuality="1080",
        remux=True
    )
    print(f"Downloaded to: {file_path}")
    
    # Bulk download multiple URLs
    urls = [
        "https://youtube.com/watch?v=DG2QqcHwNdE",
        "https://youtube.com/watch?v=anotherVideo"
    ]
    
    # Download multiple files concurrently
    async for path in manager.download_generator(urls=urls, remux=True):
        print(f"Downloaded: {path}")

run(main())

Track Download Progress

from pybalt import download
from asyncio import run

async def main():
    # Define a status callback function
    async def status_callback(downloaded_size, total_size, download_speed, eta, **kwargs):
        percent = (downloaded_size / total_size * 100) if total_size > 0 else 0
        print(f"Downloaded: {downloaded_size / 1024 / 1024:.2f}MB / "
              f"{total_size / 1024 / 1024:.2f}MB ({percent:.1f}%) at "
              f"{download_speed / 1024 / 1024:.2f}MB/s, ETA: {eta:.0f}s")
    
    # Define a completion callback
    async def done_callback(file_path, downloaded_size, time_passed, **kwargs):
        print(f"Download completed in {time_passed:.2f}s")
        print(f"File saved to: {file_path}")
    
    # Download with progress tracking
    file_path = await download(
        "https://youtube.com/watch?v=DG2QqcHwNdE",
        status_callback=status_callback,
        done_callback=done_callback
    )

run(main())

Using Status Parent

from pybalt import download
from asyncio import run, create_task

class StatusParent:
    def __init__(self):
        self.downloaded_size = 0
        self.total_size = 0
        self.download_speed = 0
        self.eta = 0
        self.completed = False
        self.file_path = None

async def main():
    # Create status parent object to track progress
    status = StatusParent()
    
    # Start download as a background task
    task = create_task(download(
        "https://youtube.com/watch?v=DG2QqcHwNdE",
        status_parent=status
    ))
    
    # Monitor progress while download is running

Pybalt

Install / Use

README