ytdlp

README

YTDLP

Native Go library and CLI to download online videos — no external binaries, Android-friendly. MVP focuses on progressive formats (video+audio) like MP4 (itag 22/18). No HLS/DASH or muxing on first stage.

Status

• MVP in progress: video platform support, progressive formats only.
• Signature deciphering implemented (regex fast-path, JS fallback via otto), n-throttling supported.
• Short-form videos fully supported (same as regular videos).
• No ffmpeg, no merging adaptive streams yet.

Install

Homebrew (macOS/Linux)

Install from our tap:

brew tap ytget/ytdlp
brew install ytdlp

Or install directly from the repository:

brew install ytget/ytdlp/Formula/ytdlp

Go install

go get github.com/ytget/ytdlp/v2

CLI binary:

go install github.com/ytget/ytdlp/v2/cmd/ytdlp@latest

Manual installation

Download pre-built binaries from releases.

Note: Homebrew installation is the recommended method for macOS and Linux users as it provides automatic updates and easier dependency management.

Quick Start (library)

package main

import (
	"context"
	"fmt"
	"github.com/ytget/ytdlp/v2"
)

func main() {
	d := ytdlp.New().WithOutputPath("").WithProgress(func(p ytdlp.Progress) {
		fmt.Printf("%.1f%%\r", p.Percent)
	})
	info, err := d.Download(context.Background(), "https://example.com/video/123")
	if err != nil {
		panic(err)
	}
	fmt.Println("\nSaved:", info.Title)
}

Quick Start (CLI)

# Best mp4 by default
ytdlp https://example.com/video/123

# Short-form videos
ytdlp https://example.com/shorts/abc123

# Select by itag
ytdlp --format itag=22 https://example.com/video/123

# Constrain by height
ytdlp --format 'height<=480' https://example.com/video/123

# Playlist subset
ytdlp --playlist --limit 25 --concurrency 4 'https://example.com/playlist/PLxxxx'

Common flags

• --format — itag=NN, best, height<=N
• --ext — mp4, webm
• --output — file or directory
• --rate-limit — 2MiB/s, 500KiB/s
• --http-timeout — 30s, 1m
• --retries — retry attempts (default 3)

See full reference in docs/cli.md.

Notes:

• If OutputPath is empty, file name is derived from Title and MIME (safe filename).
• Progressive MP4 selection preference: itag 22 → 18 → first progressive video/mp4 with avc1.
• Format selectors: ext, itag=NN, best|worst, height<=/height>=.

Playlists (MVP)

items, err := ytdlp.New().GetPlaylistItemsAll(context.Background(), "PLxxxx", 200)
// items: []types.PlaylistItem{ VideoID, Title, Index }

Documentation

• CLI flags and usage: see docs/cli.md
• API reference overview: see docs/api/README.md
• Format selection: see docs/formats.md
• Errors and troubleshooting: see docs/errors.md and docs/troubleshooting.md

Make targets

• make test / make race
• make cover — coverage report (coverage.out, coverage.html)
• make e2e / make e2e-url URL="https://..."

Errors

Library returns typed errors for common cases: unavailable/private/age-restricted/geo/rate-limited. Check error values from errs package.

FAQ

• Why do I get "age restricted" or "login required"? — Video platforms may require authentication for some videos. The library does not handle login; filter or skip such content on client side.
• Why 429/ratelimit? — Too many requests from your IP. Slow down requests, add backoff, or try later. The client already retries with exponential backoff for transient errors.
• Geo blocked? — Content not available in your region. The library returns a typed error; you must handle this on the application side.
• Download stuck at 0%? — Some hosts enforce throttling via n parameter. Ensure decipher is up-to-date; this library implements n transformation based on the player.js.

E2E Test (manual)

Run only when you want a real download test:

YTDLP_E2E=1 go test -tags e2e ./e2e -v

Optionally specify a URL:

YTDLP_E2E=1 YTDLP_E2E_URL="https://example.com/video/123" go test -tags e2e ./e2e -v

Android

• Pure Go; suitable for gomobile/Fyne builds.
• Ensure proper storage permissions and SAF/MediaStore usage on app side.

Limitations (MVP)

• Single platform support.
• Progressive formats only (no adaptive muxing yet).
• Live streams, HLS/DASH are out of scope (for now).

Roadmap (short)

• Robust decipher/n-throttling parser with test fixtures.
• Playlists via platform API browse/continuations.
• Adaptive formats + muxing in a later phase.

License

MIT

Documentation

Index

• type DownloadOptions
• type Downloader
  • func New() *Downloader
  • func (d *Downloader) Download(ctx context.Context, videoURL string) (*VideoInfo, error)
  • func (d *Downloader) GetPlaylistItems(ctx context.Context, playlistID string, limit int) ([]types.PlaylistItem, error)
  • func (d *Downloader) GetPlaylistItemsAll(ctx context.Context, playlistID string, limit int) ([]types.PlaylistItem, error)
  • func (d *Downloader) ResolveURL(ctx context.Context, videoURL string) (string, *VideoInfo, error)
  • func (d *Downloader) WithBotguard(mode botguard.Mode, solver botguard.Solver, cache botguard.Cache) *Downloader
  • func (d *Downloader) WithBotguardDebug(debug bool) *Downloader
  • func (d *Downloader) WithBotguardTTL(ttl time.Duration) *Downloader
  • func (d *Downloader) WithFormat(quality, ext string) *Downloader
  • func (d *Downloader) WithHTTPClient(client *http.Client) *Downloader
  • func (d *Downloader) WithInnertubeClient(name, version string) *Downloader
  • func (d *Downloader) WithOutputPath(path string) *Downloader
  • func (d *Downloader) WithProgress(f func(Progress)) *Downloader
  • func (d *Downloader) WithRateLimit(bytesPerSecond int64) *Downloader
• type Format
• type Progress
• type VideoInfo

Types

type DownloadOptions

type DownloadOptions struct {
	FormatSelector  string
	DesiredExt      string
	OutputPath      string
	HTTPClient      *http.Client
	ProgressFunc    func(Progress)
	RateLimitBps    int64
	ITClientName    string
	ITClientVersion string
}

DownloadOptions contains configuration for a single download invocation.

Use chainable setters on Downloader to populate these options.

type Downloader

type Downloader struct {
	// contains filtered or unexported fields
}

Downloader provides a high-level API for retrieving metadata and downloading YouTube videos using internal clients and helpers.

func New

func New() *Downloader

New creates a new Downloader instance with default options.

func (*Downloader) Download

func (d *Downloader) Download(ctx context.Context, videoURL string) (*VideoInfo, error)

Download retrieves video metadata, resolves URL, and downloads to disk.

func (*Downloader) GetPlaylistItems

func (d *Downloader) GetPlaylistItems(ctx context.Context, playlistID string, limit int) ([]types.PlaylistItem, error)

GetPlaylistItems returns minimal playlist items for a playlist ID (MVP: first page only).

func (*Downloader) GetPlaylistItemsAll

func (d *Downloader) GetPlaylistItemsAll(ctx context.Context, playlistID string, limit int) ([]types.PlaylistItem, error)

GetPlaylistItemsAll returns playlist items with continuations up to the limit.

func (*Downloader) ResolveURL

func (d *Downloader) ResolveURL(ctx context.Context, videoURL string) (string, *VideoInfo, error)

ResolveURL performs the metadata fetch and URL resolution, returning the final media URL and basic info.

func (*Downloader) WithBotguard

func (d *Downloader) WithBotguard(mode botguard.Mode, solver botguard.Solver, cache botguard.Cache) *Downloader

WithBotguard configures Botguard attestation usage.

func (*Downloader) WithBotguardDebug

func (d *Downloader) WithBotguardDebug(debug bool) *Downloader

WithBotguardDebug enables Botguard debug logging.

func (*Downloader) WithBotguardTTL

func (d *Downloader) WithBotguardTTL(ttl time.Duration) *Downloader

WithBotguardTTL sets default Botguard TTL when solver does not specify ExpiresAt.

func (*Downloader) WithFormat

func (d *Downloader) WithFormat(quality, ext string) *Downloader

WithFormat sets a format selector and optional desired extension. Examples: "itag=22", "best", "height<=480". Extension is case-insensitive.

func (*Downloader) WithHTTPClient

func (d *Downloader) WithHTTPClient(client *http.Client) *Downloader

WithHTTPClient sets a custom HTTP client to be used for all network calls.

func (*Downloader) WithInnertubeClient

func (d *Downloader) WithInnertubeClient(name, version string) *Downloader

WithInnertubeClient sets the Innertube client name and version to use.

func (*Downloader) WithOutputPath

func (d *Downloader) WithOutputPath(path string) *Downloader

WithOutputPath sets the output file path. If empty, a safe filename is derived from the video title and mime extension. If a directory path is provided, a safe filename is derived and placed inside that directory.

func (*Downloader) WithProgress

func (d *Downloader) WithProgress(f func(Progress)) *Downloader

WithProgress registers a callback that receives progress updates.

func (*Downloader) WithRateLimit

func (d *Downloader) WithRateLimit(bytesPerSecond int64) *Downloader

WithRateLimit sets a download rate limit in bytes per second. Zero disables limiting.

type Format

type Format = types.Format

Format describes an available media format. Deprecated: use types.Format instead.

type Progress

type Progress struct {
	TotalSize      int64
	DownloadedSize int64
	Percent        float64
}

Progress describes current progress of an ongoing download.

type VideoInfo

type VideoInfo struct {
	ID          string
	Title       string
	Author      string
	Duration    int
	Formats     []types.Format
	Description string
}

VideoInfo contains basic video metadata and the full list of available formats.