go-ytdlp

The FlagConfig type allows for bidirectional conversion between JSON and yt-dlp command-line flags. This is ideal for HTTP APIs, web UIs, or persisting configurations in a database.

Key Features

• Bidirectional Conversion: Use Command.SetFlagConfig to apply a JSON configuration to a command, and Command.GetFlagConfig to extract the current flags into JSON.
• Compatible Decoding: When loading older or client-supplied configurations, use FlagConfig.UnmarshalJSONWithWarnings. This allows you to retain valid flags even if some members are unknown or incompatible. Always review the returned warnings.
• Validation: Use the provided validation functions and the JSON schema (available via optiondata.JSONSchema) to ensure correctness. The JSON body allows duplicate flags unless validated against the schema.
• Persistence Warning: yt-dlp flags can change or be removed during updates. When loading from storage, use compatibility decoding and handle warnings before validating. If validation fails, clear invalid values using the error types ErrMultipleJSONParsingFlags or ErrJSONParsingFlag (which provide the JSON path to the error).

You can use go-ytdlp by creating a new command instance via ytdlp.New() and using a builder pattern to configure flags. Before running, it is recommended to use ytdlp.MustInstall to ensure the yt-dlp binary is available on your system.

Key methods used in the example:

• ytdlp.MustInstall(ctx, nil): Downloads and caches the yt-dlp binary.
• ytdlp.New(): Initializes a new command builder.
• .FormatSort(string): Sets the format sorting flag.
• .RecodeVideo(string): Sets the video recoding format.
• .Output(string): Sets the output template.
• .Run(ctx, url): Executes the command for the provided URL.

package main

import (
	"context"

	"github.com/lrstanley/go-ytdlp"
)

func main() {
	// If yt-dlp isn't installed yet, download and cache it for further use.
	ytdlp.MustInstall(context.TODO(), nil)

	dl := ytdlp.New().
		FormatSort("res,ext:mp4:m4a").
		RecodeVideo("mp4").
		Output("%(extractor)s - %(title)s.%(ext)s")

	_, err := dl.Run(context.TODO(), "https://www.youtube.com/watch?v=dQw4w9WgXcQ")
	if err != nil {
		panic(err)
	}
}

The Install* helper functions allow you to automatically download and cache required binaries (yt-dlp, ffmpeg, ffprobe, and bun) for your platform. This ensures the correct versions are used without manual installation.

Supported Platforms for Automatic Download:

• yt-dlp: Supported on darwin_amd64, darwin_arm64, linux_amd64, linux_arm64, linux_armv7l, and windows_amd64.
• ffmpeg & ffprobe: Supported on darwin_amd64, darwin_arm64, linux_amd64, linux_arm64, windows_amd64, and windows_arm.
• bun: Supported on darwin_amd64, darwin_arm64, linux_amd64, linux_arm64, and windows_amd64.

Note on JavaScript Runtimes: When using [Must]InstallAll or [Must]InstallBun, the library automatically enables Bun by default and explicitly disables other runtimes. While yt-dlp supports multiple runtimes (like Deno), Deno is not automatically installed because it does not yet support musl-based Linux distributions (e.g., Alpine).

The ExtractedInfo struct is the primary container for metadata extracted from a video or playlist. It is a highly nested structure that includes:

• Core Identity: ID, Title, URL, WebpageURL, Description, Tags, Categories.
• Media Formats: Formats (all available qualities) and RequestedFormats. Each format is an ExtractedFormat containing URL, Resolution, Bitrate, Codec info, etc.
• Uploader/Channel Info: Uploader, Channel, ChannelID, ChannelURL.
• Temporal Data: Timestamp, UploadDate, Duration.
• Playlist Data: If the type is a playlist, it includes Entries (a slice of *ExtractedInfo), PlaylistTitle, PlaylistCount, etc.
• Series/Track Data: Fields for Series, Season, Episode, Track, Album, Artist.
• Live Status: IsLive, WasLive, and LiveStatus (e.g., is_live, is_upcoming).
• Subtitles/Captions: Subtitles and AutomaticCaptions maps keyed by language code.

Use InstallBun to ensure the Bun runtime is available on the current platform. The function follows this priority:

1. Checks if Bun is already resolved in the internal cache.
2. Attempts to find an existing Bun binary in the system PATH (unless DisableSystem is set to true).
3. If not found and DisableDownload is false, it downloads the appropriate Bun archive for the current OS/architecture and extracts it to a cache directory.

Returns a *ResolvedInstall pointer containing the path to the executable and metadata about its origin.

import (
	"context"
	"github.com/lrstanley/lrstanley/go-ytdlp"
)

func main() {
	ctx := context.Background()
	opts := &ytdlp.InstallBunOptions{
		DisableSystem: false,
		DisableDownload: false,
	}

	resolved, err := ytdlp.InstallBun(ctx, opts)
	if err != nil {
		// handle error
	}

	// Use resolved.Executable to run bun commands
	fmt.Printf("Bun version: %s, Path: %s\n", resolved.Version, resolved.Executable)
}