pybalt

pybalt

CLI tool and python module for downloading media through Cobalt processing instances.

CLI Preview

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

Installation

Install pybalt using PowerShell on Windows

Downloads install.bat and executes it.

Powershell should be run as administrator, otherwise aliases (cobalt, pybalt) in terminal will not work.

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

Install using PIP

pip install pybalt

This should create aliases pybalt and cobalt in your shell.

Try running cobalt -h to see the help message.

If for some reason it didn't work, try using it directly from python package:

python -m pybalt

Usage & Examples

Selecting processing instance

You can set processing instance URL, API key, and user-agent as environment variables; pybalt will use them if none are provided.

COBALT_API_URL=YOUR_INSTANCE_URL
COBALT_API_KEY=YOUR_API_KEY
COBALT_USER_AGENT=YOUR_USER_AGENT

By default, pybalt attempts to use any available instance for you provided by public list of instances. It is recommended to host your own instance or request an API key from someone else's instance.

As a CLI

Every command here uses the cobalt alias; you can also use pybalt or python -m pybalt.

By default, all downloads are saved in the user's downloads folder ~/Downloads, or the one specified by the -f (-folder) flag.

Get a list of all available commands by running:

cobalt -h

Download video from URL

cobalt -u 'https://youtube.com/watch?v=8ZP5eqm4JqM'

You can also provide the URL as a positional argument:

cobalt 'https://youtube.com/watch?v=8ZP5eqm4JqM'

Download YouTube playlist

cobalt -pl 'https://youtube.com/playlist?list=PL_93TBqf4ymR9GsuI9W4kQ-G3WM7d2Tqj'

Download from text file

Create a text file with URLs on each line:

https://youtube.com/watch?v=8ZP...
.....
....
...

Then run:

cobalt -l 'path/to/file.txt'

More examples

Download all videos from a YouTube playlist in 720p to folder /Music/, with filename style classic, using instance https://dwnld.nichind.dev and API key authorization:

cobalt -pl 'https://youtube.com/playlist?list=PL_93TBqf4ymR9GsuI9W4kQ-G3WM7d2Tqj' -q 720 -f './Music/' -fs 'classic' -i 'https://dwnld.nichind.dev' -k 'YOUR_API_KEY'

As a module

Download video from URL

from pybalt import Cobalt
from asyncio import run

async def main():
    cobalt = Cobalt()
    path = await cobalt.download('https://youtube.com/watch?v=8ZP5eqm4JqM')
    print('Downloaded: ', path)  # Downloaded: /Users/%USER%/Downloads/8ZP5eqm4JqM.mp4

run(main())

You can pass arguments inside the Cobalt object:

from pybalt import Cobalt
from asyncio import run

async def main():
    cobalt = Cobalt(api_instance='YOUR_INSTANCE_URL', api_key='YOUR_API_KEY', headers={...})
    path = await cobalt.download(url='https://youtube.com/watch?v=8ZP5eqm4JqM', quality='1080')
    print('Downloaded: ', path)  # Downloaded: /Users/%USER%/Downloads/8ZP5eqm4JqM.mp4

run(main())

Contributing

If you have any questions or suggestions, please open an issue or create a pull request.

Contributors