From 80da4c3ca7647f4251a4a320ab725c24235b4382 Mon Sep 17 00:00:00 2001 From: Andres Perez <1676612+andresperezl@users.noreply.github.com> Date: Sat, 16 Nov 2024 13:36:25 -0500 Subject: [PATCH] fix: make godocs more pretty and add example in README --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ client.go | 10 +++++----- types.go | 30 +++++++++++++++--------------- 3 files changed, 66 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5e7c75e..d47d4ee 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,52 @@ Go library to interact with [cobalt.tools API](https://cobalt.tools/) +## Usage + +Get the package into your project + +```sh +go get github.com/andresperezl/gobalt/v2 +``` +Then import it and use it in your file + +```go +import ( + "github.com/andresperezl/gobalt/v2" +) + + +func main() { + // Point the client to the cobalt instance you want to use + client := gobalt.NewClientWithAPI("http://localhost:9000") + + // Then simply get the media + media, err := gobalt.Post(context.Background(),gobalt.PostParams{URL: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}) + if err != nil { + panic(err) + } + + // Then simply stream it to save it or to send it somewhere else + stream, err := media.Stream(context.Background()) + if err != nil { + panic(err) + } + // You must close the stream once you are done + defer stream.Close() + + file, err := os.OpenFile(media.Filename, os.O_WRONLY|os.O_CREATE, 0644) + if err != nil { + panic(err) + } + + // Read and write into the file into EOF from the stream + _, err = file.ReadFrom(stream) + if err != nil { + panic(err) + } +} +``` + ## Private Instance is Required Since the removal of the api.cobalt.tools public v7 API, a private hosted diff --git a/client.go b/client.go index 9a37555..4218fc7 100644 --- a/client.go +++ b/client.go @@ -27,7 +27,7 @@ func (c *Cobalt) WithHTTPClient(client *http.Client) *Cobalt { return c } -// Post will return a PostResponse from where the file can be downloaded +// Post will return a [PostResponse] from where the file can be downloaded // headers are passed as key value pairs. Examples `"API-KEY", "MyApiKey"` func (c *Cobalt) Post(ctx context.Context, params PostRequest, headers ...string) (*PostResponse, error) { buff := &bytes.Buffer{} @@ -69,9 +69,9 @@ func (c *Cobalt) Post(ctx context.Context, params PostRequest, headers ...string return media, nil } -// Stream is a helper utility that will return an io.ReadCloser using the URL from this media object -// The returned io.ReadCloser is the Body of *http.Response and must be closed when you are done with the stream. -// When the m.Status == ResponseStatusPicker it will stream the first item from the m.Picker array. +// Stream is a helper utility that will return an [io.ReadCloser] using the [PostResponse.URL] from this media object +// The returned [io.ReadCloser] is the Body of [*http.Response] and must be closed when you are done with the stream. +// When the [PostResponse.Status] == [ResponseStatusPicker] it will stream the first item from the [PostResponse.Picker] array. func (m *PostResponse) Stream(ctx context.Context) (io.ReadCloser, error) { if m.Status != ResponseStatusTunnel && m.Status != ResponseStatusRedirect && m.Status != ResponseStatusPicker { return nil, fmt.Errorf("unstreamable response type %s", m.Status) @@ -168,7 +168,7 @@ func (c *Cobalt) Session(ctx context.Context, headers ...string) (*SessionRespon return token, nil } -// CobalAPIError is just a convenient type to convert Media into an error. +// CobalAPIError is just a convenient type to convert [PostResponse] into an error. type CobaltAPIError PostResponse func (err CobaltAPIError) Error() string { diff --git a/types.go b/types.go index bcf31ef..b661517 100644 --- a/types.go +++ b/types.go @@ -7,29 +7,29 @@ type PostRequest struct { URL string `json:"url"` // VideoQuality if the selected quality isn't available, closest one is used instead. - // Default VideoQuality1080p + // Default [VideoQuality1080p] VideoQuality VideoQuality `json:"videoQuality,omitempty"` // AudioFormat Format to re-encode audio into. If AudioFormatBest is selected, you get the audio the way it is on service's side. - // Default AudioFormatMP3 + // Default [AudioFormatMP3] AudioFormat AudioFormat `json:"audioFormat,omitempty"` // AudioBitrate Specifies the birate to use for the audio. Applies only to audio conversion. - // Default AudioBitrate128 + // Default [AudioBitrate128] AudioBitrate AudioBitrate `json:"audioBitrate,omitempty"` // FilenameStyle changes the way files are named. // Some services don't support rich file names and always use the classic style. - // Default FilenamePatternClassic + // Default [FilenamePatternClassic] FilenameStyle FilenameStyle `json:"filenameStyle,omitempty"` // DownloadMode selects if to download only the audio, or mute the audio in video tracks - // Default auto + // Default [DownloadModeAuto] DownloadMode DownloadMode `json:"downloadMode,omitempty"` // YoutubeVideoCodec applies only for Youtube downloads. - // Pick YoutubeVideoCodecH264 if you want best compatibility. Pick YoutubeVideoCodecAV1 if you want best quality and efficiency. - // Default YoutubeVideoCodecH264 + // Pick [YoutubeVideoCodecH264] if you want best compatibility. Pick [YoutubeVideoCodecAV1] if you want best quality and efficiency. + // Default [YoutubeVideoCodecH264] YoutubeVideoCodec YoutubeVideoCodec `json:"youtubeVideoCodec,omitempty"` // YoutubeDubLang Specifies the language of audio to download when a youtube video is dubbed. @@ -65,11 +65,11 @@ type PostRequest struct { type YoutubeVideoCodec string const ( - // YoutubeVideoCodecH264 best support across apps/platforms, average detail level. Max VideoQuality is VideoQuality1080p + // YoutubeVideoCodecH264 best support across apps/platforms, average detail level. Max VideoQuality is [VideoQuality1080p] YoutubeVideoCodecH264 YoutubeVideoCodec = "h264" - // YoutubeVideoCodecAV1 best quality, small file size, most detail. Supports 8k and HDR. + // YoutubeVideoCodecAV1 best quality, small file size, most detail. Supports [VideoQuality8k] and HDR. YoutubeVideoCodecAV1 YoutubeVideoCodec = "av1" - // YoutubeVideoCodecVP9 same quality as av1, but file size is 2x larger. Supports 4k and HDR. + // YoutubeVideoCodecVP9 same quality as av1, but file size is 2x larger. Supports [VideoQuality4k] and HDR. YoutubeVideoCodecVP9 YoutubeVideoCodec = "vp9" ) @@ -87,10 +87,10 @@ const ( VideoQuality4320p VideoQuality = "4320" VideoQualityMax VideoQuality = "max" - // VideoQuality4k is an alias for VideoQuality2160p + // VideoQuality4k is an alias for [VideoQuality2160p] VideoQuality4K VideoQuality = VideoQuality2160p - // VideoQuality8k is an alias for VideoQuality4320p + // VideoQuality8k is an alias for [VideoQuality4320p] VideoQuality8K VideoQuality = VideoQuality4320p ) @@ -183,14 +183,14 @@ type PostResponse struct { // Status is the type of response from the API Status ResponseStatus `json:"status"` - // ResponseStatusTunnel and ResponseStatusRedirect fields + // [ResponseStatusTunnel] and [ResponseStatusRedirect] fields // URL for the cobalt tunnel, or redirect to an external link URL string `json:"url,omitempty"` // Filename cobalt-generated filename for the file being downloaded Filename string `json:"filename,omitempty"` - // ResponseStatusPicker fields + // [ResponseStatusPicker] fields // Audio returned when an image slideshow (such as tiktok) has a general background audio Audio string `json:"audio,omitempty"` @@ -199,7 +199,7 @@ type PostResponse struct { // Picker array of objects containing the individual media Picker []PickerItem `json:"picker,omitempty"` - // ResponseStatusError fields + // [ResponseStatusError] fields // ErrorInfo contains more context about the error ErrorInfo ResponseErrorInfo `json:"error,omitempty"`