gobalt

README

gobalt v1

new update, see v2 branch

[!IMPORTANT]
Cobalt API recently had a breaking change update, if you want to keep using cobalt's api, we recommend updating this package to version 2. (see changes)

Gobalt provides a way to communicate with cobalt.tools using Go. To use it in your projects, simply run this command:

go get github.com/lostdusty/gobalt

Usage

First, make sure you call gobalt.CreateDefaultSettings() to create the Settings struct with default values, then set an url.

//Creates a Settings struct with default values, and save it to downloadMedia variable.
downloadMedia := gobalt.CreateDefaultSettings()

//Sets the URL, you MUST set one before downloading the media.
downloadMedia.Url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

//After changing the url, Do() will make the necessary requests to cobalt to download your media
destination, err := gobalt.Do(downloadMedia)
if err != nil {
    //Handle errors here
}

//Prints out the url from cobalt to download the requested media.
fmt.Println(destination.URL)
//Output example: https://us4-co.wuk.sh/api/stream?t=wTn-71aaWAcV2RBejNFNV&e=1711777798864&h=fMtwwtW8AUmtTLB24DGjJJjrq1EJDBFaCDoDuZpX0pA&s=_YVZhz8fnzBBKKo7UZmGWOqfe4wWwH5P1azdgBqwf-I&i=6tGZqAXbW08_6KmAiLevZA

Features

Server info

You can query information about any cobalt server by using CobaltServerInfo(apiurl). This will return a ServerInfo struct with this info.

Example code:

server, err := gobalt.CobaltServerInfo(gobalt.CobaltApi)
if err != nil {
	 //Handle the error here
}
fmt.Printf("Downloading from %v!\n", server.URL)
//Output: Downloading from https://us4-co.wuk.sh/!

Use/Query other cobalt instances

Using GetCobaltInstances() fetches a community maintaned list of third-party cobalt instances ran by the community, except for *-co.wuk.sh, none of them are "official" cobalt instances. Use them if you can't download from the main instance for whatever reason.

Example:

cobalt, err := gobalt.GetCobaltInstances()
if err != nil { 
    //Handle errors here
}
fmt.Printf("Found %v online cobalt servers: ", len(cobalt))
for _, value := range cobalt {
	fmt.Printf("%v, ", value.URL)
}
/* Output: 
* Found 8 online cobalt servers: co.wuk.sh, cobalt-api.hyper.lol, cobalt.api.timelessnesses.me, api-dl.cgm.rs, cobalt.synzr.space, capi.oak.li, co.tskau.team, api.co.rooot.gay
*/

Documentation

Index

• Constants
• Variables
• type CobaltInstances
• type CobaltResponse
  • func Run(opts Settings) (*CobaltResponse, error)
• type MediaInfo
  • func ProcessMedia(url string) (*MediaInfo, error)
• type ServerInfo
  • func CobaltServerInfo(api string) (*ServerInfo, error)
  • func GetCobaltInstances() ([]ServerInfo, error)
• type Settings
  • func CreateDefaultSettings() Settings

Constants

const (
	H264 codecs = "h264" //Default codec that is supported everywhere. Recommended for social media/phones, but tops up at 1080p.
	AV1  codecs = "av1"  //Recent codec, supports 8K/HDR. Generally less supported by media players, social media, etc.
	VP9  codecs = "vp9"  //Best quality codec with higher bitrate (preserve most detail), goes up to 4K and supports HDR.
)

const (
	Best audioCodec = "best" //When "best" format is selected, you get audio the way it is on service's side. it's not re-encoded.
	Opus audioCodec = "opus" //Re-encodes the audio using Opus codec. It's a lossy codec with low complexity. Works in Android 10+, Windows 10 1809+, MacOS High Sierra/iOS 17+.
	Ogg  audioCodec = "ogg"  //Re-encodes to ogg, an older lossy audio codec. Should work everywhere.
	Wav  audioCodec = "wav"  //Re-encodes to wav, an even older format. Good compatibility for older systems, like Windows 98. Tops up at 4GiB.
	MP3  audioCodec = "mp3"  //Re-encodes to mp3, the format used basically everywhere. Lossy audio, but generally good player/social media support. Can degrade quality as time passes.
)

const (
	Classic pattern = "classic" //Looks like this: youtube_yPYZpwSpKmA_1920x1080_h264.mp4 | audio: youtube_yPYZpwSpKmA_audio.mp3
	Basic   pattern = "basic"   //Looks like: Video Title (1080p, h264).mp4 | audio: Audio Title - Audio Author.mp3
	Nerdy   pattern = "nerdy"   //Looks like this: Video Title (1080p, h264, youtube, yPYZpwSpKmA).mp4 | audio: Audio Title - Audio Author (soundcloud, 1242868615).mp3
	Pretty  pattern = "pretty"  //Looks like: Video Title (1080p, h264, youtube).mp4 | audio: Audio Title - Audio Author (soundcloud).mp3
)

Variables

var (
	CobaltApi    = "https://api.cobalt.tools" //Override this value to use your own cobalt instance. See https://instances.hyper.lol/ for alternatives from the main instance.
	UserLanguage = "en"                       //Replace this following the ISO 639-1 standard. This downloads dubbed YouTube audio according to the language set here. Only takes effect if DubbedYoutubeAudio is set to true.

)

Types

type CobaltInstances

type CobaltInstances []struct {
	Cors           int    `json:"cors"`             //Cors status: 0 = Enabled; 1 = Disabled; -1 = Instance offline.
	Commit         string `json:"commit,omitempty"` //Commit id. Empty if the instance is offline.
	Name           string `json:"name,omitempty"`   //Name of the server. Empty if the instance is offline.
	StartTime      int64  `json:"startTime"`        //Time when the service started in linux epoch (seconds). -1 Means the instance is offline
	API            string `json:"api"`              //API Url.
	Version        string `json:"version"`          //Version of cobalt running, "-1" if offiline.
	Branch         string `json:"branch,omitempty"` //Branch the server is using, empty if the server is offline
	FrontEnd       string `json:"frontEnd"`         //Front end url.
	ApiOnline      bool   `json:"api_online"`       //Status of the server api. True if online.
	FrontEndOnline bool   `json:"frontend_online"`  //Status of the frontend. Online = true.
}

type CobaltResponse

type CobaltResponse struct {
	Status string `json:"status"` //Will be error / redirect / stream / success / rate-limit / picker.
	Picker []struct {
		Type  string `json:"type"`
		URL   string `json:"url"`
		Thumb string `json:"thumb"`
	} `json:"picker"`
	URL  string   `json:"url"`  //Returns the download link. If the status is picker this field will be empty. Direct link to a file or a link to cobalt's live render.
	Text string   `json:"text"` //Various text, mostly used for errors.
	URLs []string //If the status is picker all the urls will go here.
}

func Run

func Run(opts Settings) (*CobaltResponse, error)

Run Function Run() requests the final url on /api/json and returns error case it fails to do so.

type MediaInfo

type MediaInfo struct {
	Size uint //Media size in bytes
	Name string
	Type string
}

func ProcessMedia

func ProcessMedia(url string) (*MediaInfo, error)

type ServerInfo

type ServerInfo struct {
	Version        string `json:"version"`          //cobalt version
	Commit         string `json:"commit,omitempty"` //git commit
	Branch         string `json:"branch,omitempty"` //git branch
	Name           string `json:"name,omitempty"`   //name of the server
	URL            string `json:"url"`              //full url of the api
	Cors           *int   `json:"cors,omitempty"`   //cors status, either 0 or 1.
	StartTime      int64  `json:"startTime,string"` //server start time in linux epoch
	FrontendUrl    string //Front end URL.
	ApiOnline      bool   //Status of the api.
	FrontEndOnline bool   //Status of the front end.
}

func CobaltServerInfo

func CobaltServerInfo(api string) (*ServerInfo, error)

CobaltServerInfo This function is called before Run() to check if the cobalt server used is reachable. If you can't contact the main server, try getting another instance using GetCobaltinstances().

func GetCobaltInstances

func GetCobaltInstances() ([]ServerInfo, error)

GetCobaltInstances makes a request to instances.hyper.lol and returns a list of all online cobalt instances.

type Settings

type Settings struct {
	Url                  string     `json:"url"`             //Any URL from bilibili.com, instagram, pinterest, reddit, rutube, soundcloud, streamable, tiktok, tumblr, twitch clips, twitter/x, vimeo, vine archive, vk or youtube. Will be url encoded later.
	VideoCodec           codecs     `json:"vCodec"`          //H264, AV1 or VP9, defaults to H264.
	VideoQuality         int        `json:"vQuality,string"` //144p to 2160p (4K), if not specified will default to 1080p.
	AudioCodec           audioCodec `json:"aFormat"`         //MP3, Opus, Ogg or Wav. If not specified will default to best.
	FilenamePattern      pattern    `json:"filenamePattern"` //Classic, Basic, Pretty or Nerdy. Defaults to Pretty
	AudioOnly            bool       `json:"isAudioOnly"`     //Removes the video, downloads audio only. Default: false
	TikTokH265           bool       `json:"tiktokH265"`      //Changes whether 1080p h265 [tiktok] videos are preferred or not. Default: false
	FullTikTokAudio      bool       `json:"isTTFullAudio"`   //Enables download of original sound used in a tiktok video. Default: false
	VideoOnly            bool       `json:"isAudioMuted"`    //Downloads only the video, audio is muted/removed. Default: false
	DubbedYoutubeAudio   bool       `json:"dubLang"`         //Pass the User-Language HTTP header to use the dubbed audio of the respective language, must change according to user's preference, default is English (US). Uses ISO 639-1 standard.
	DisableVideoMetadata bool       `json:"disableMetadata"` //Removes file metadata. Default: false
	ConvertTwitterGifs   bool       `json:"twitterGif"`      //Changes whether twitter gifs are converted to .gif (Twitter gifs are usually stored in .mp4 format). Default: true
}

func CreateDefaultSettings

func CreateDefaultSettings() Settings

CreateDefaultSettings Function CreateDefaultSettings() creates the Settings struct with default values: Url: "" VideoCodec: H264, VideoQuality: 1080, AudioCodec: Best, FilenamePattern: Pretty, AudioOnly: false, FullTikTokAudio: false, VideoOnly: false, DubbedYoutubeAudio: false, DisableVideoMetadata: false, ConvertTwitterGifs: false, TikTokH265: false, You MUST set an url before calling Run().