video

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package video provides a pure Go video download engine supporting YouTube and other video platforms. It is designed as a reusable library that can be imported by external Go projects.

The package follows a layered architecture:

  • types/errors: Core data structures and error types
  • utils: Filename sanitization, HTML parsing, URL manipulation, duration parsing
  • nethttp: HTTP client with cookie jar, proxy, retries, custom UA
  • cache: Filesystem-based cache using XDG paths
  • jsinterp: JavaScript execution via goja (for YouTube signature decryption)
  • m3u8: HLS manifest parser
  • format: Format sorting and selection
  • downloader: HTTP and HLS download engines with resume support
  • extractor: Site-specific video metadata extractors

Basic usage: 

client := video.New(video.WithFormat("best"))
info, err := client.Extract(ctx, "https://www.youtube.com/watch?v=...")
if err != nil {
    log.Fatal(err)
}
err = client.Download(ctx, info)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ListExtractors 

func ListExtractors() []string

ListExtractors returns the names of all registered extractors.

Types

type AgeRestrictedError 

type AgeRestrictedError struct {
	Message string
}

AgeRestrictedError is returned when age verification is required.

func (*AgeRestrictedError) Error 

func (e *AgeRestrictedError) Error() string

type Chapter 

type Chapter = types.Chapter

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type Client 

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

Client is the main video download orchestrator.

func New 

func New(opts ...Option) (*Client, error)

New creates a new video download client.

func (*Client) Download 

func (c *Client) Download(ctx context.Context, url string) error

Download extracts and downloads video from the given URL.

func (*Client) DownloadInfo 

func (c *Client) DownloadInfo(ctx context.Context, info *VideoInfo) error

DownloadInfo downloads a video from previously extracted info.

func (*Client) Extract 

func (c *Client) Extract(ctx context.Context, url string) (*VideoInfo, error)

Extract retrieves video metadata from the given URL.

type DownloadError 

type DownloadError struct {
	URL     string
	Message string
	Cause   error
}

DownloadError is returned when a download fails.

func (*DownloadError) Error 

func (e *DownloadError) Error() string

func (*DownloadError) Unwrap 

func (e *DownloadError) Unwrap() error

type ExtractorError 

type ExtractorError = types.ExtractorError

Re-export error types from the types sub-package.

type Format 

type Format = types.Format

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type Fragment 

type Fragment = types.Fragment

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type GeoRestrictedError 

type GeoRestrictedError = types.GeoRestrictedError

Re-export error types from the types sub-package.

type Option 

type Option func(*Options)

Option is a functional option for configuring the client.

func WithCacheDir 

func WithCacheDir(dir string) Option

WithCacheDir sets the cache directory.

func WithContinue 

func WithContinue() Option

WithContinue enables resuming partial downloads.

func WithCookieFile 

func WithCookieFile(path string) Option

WithCookieFile sets the cookie file path.

func WithFormat 

func WithFormat(f string) Option

WithFormat sets the format selector string.

func WithHeaders 

func WithHeaders(headers map[string]string) Option

WithHeaders adds custom HTTP headers.

func WithNoPart 

func WithNoPart() Option

WithNoPart disables .part file usage.

func WithNoPlaylist 

func WithNoPlaylist() Option

WithNoPlaylist disables playlist downloading.

func WithNoProgress 

func WithNoProgress() Option

WithNoProgress disables the progress bar.

func WithOutput 

func WithOutput(tmpl string) Option

WithOutput sets the output filename template.

func WithProgress 

func WithProgress(fn ProgressFunc) Option

WithProgress sets the progress callback.

func WithProxy 

func WithProxy(proxy string) Option

WithProxy sets the proxy URL.

func WithQuiet 

func WithQuiet() Option

WithQuiet suppresses progress output.

func WithRateLimit 

func WithRateLimit(bytesPerSec int64) Option

WithRateLimit sets the download rate limit in bytes per second.

func WithRetries 

func WithRetries(n int) Option

WithRetries sets the number of download retries.

func WithVerbose 

func WithVerbose() Option

WithVerbose enables verbose logging.

func WithWriteInfo 

func WithWriteInfo() Option

WithWriteInfo enables writing .info.json files.

func WithWriteSubs 

func WithWriteSubs() Option

WithWriteSubs enables writing subtitle files.

type Options 

type Options struct {
	Format        string            // Format selector (e.g., "best", "worst", "bestvideo")
	Output        string            // Output filename template
	Quiet         bool              // Suppress progress output
	NoProgress    bool              // Disable progress bar
	RateLimit     int64             // Rate limit in bytes/sec
	Retries       int               // Number of download retries
	Continue      bool              // Resume partial downloads
	NoPart        bool              // Don't use .part files
	CookieFile    string            // Path to cookies.txt
	Proxy         string            // HTTP/SOCKS proxy URL
	UserAgent     string            // Custom User-Agent
	Headers       map[string]string // Additional HTTP headers
	WriteInfo     bool              // Write .info.json alongside video
	WriteSubs     bool              // Write subtitles
	NoPlaylist    bool              // Don't download playlists
	PlaylistStart int               // Playlist start index (1-based)
	PlaylistEnd   int               // Playlist end index
	Verbose       bool              // Verbose logging
	CacheDir      string            // Cache directory
	Progress      ProgressFunc      // Progress callback
}

Options configures the video download client.

type ProgressFunc 

type ProgressFunc = types.ProgressFunc

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type ProgressInfo 

type ProgressInfo = types.ProgressInfo

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type Subtitle 

type Subtitle = types.Subtitle

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type Thumbnail 

type Thumbnail = types.Thumbnail

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

type UnsupportedError 

type UnsupportedError = types.UnsupportedError

Re-export error types from the types sub-package.

type VideoInfo 

type VideoInfo = types.VideoInfo

Re-export types from the types sub-package for convenience. External consumers can import either pkg/video or pkg/video/types.

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides a filesystem-based cache using XDG directory conventions for storing and retrieving JSON-serialized data across video download sessions.
 Package cache provides a filesystem-based cache using XDG directory conventions for storing and retrieving JSON-serialized data across video download sessions.
Package downloader provides video download engines for HTTP/HTTPS and HLS (M3U8) protocols with resume, retry, rate limiting, and progress tracking support.
 Package downloader provides video download engines for HTTP/HTTPS and HLS (M3U8) protocols with resume, retry, rate limiting, and progress tracking support.
Package extractor defines the Extractor interface and provides a global registry for site-specific video metadata extractors.
 Package extractor defines the Extractor interface and provides a global registry for site-specific video metadata extractors.
all
Package all imports all extractor packages to register them.
 Package all imports all extractor packages to register them.
generic
youtube
Package format provides video format sorting by quality and a selector that parses format specification strings like "best", "worst", "bestvideo", and filter expressions like "best[height<=720]".
 Package format provides video format sorting by quality and a selector that parses format specification strings like "best", "worst", "bestvideo", and filter expressions like "best[height<=720]".
Package jsinterp provides a JavaScript execution environment using the goja runtime for decrypting YouTube video signatures and throttling parameters (nsig).
 Package jsinterp provides a JavaScript execution environment using the goja runtime for decrypting YouTube video signatures and throttling parameters (nsig).
Package m3u8 provides an HLS manifest parser that handles both master and media playlists, including segment durations, encryption keys (EXT-X-KEY), and variant stream selection.
 Package m3u8 provides an HLS manifest parser that handles both master and media playlists, including segment durations, encryption keys (EXT-X-KEY), and variant stream selection.
Package nethttp provides an HTTP client wrapper with cookie jar support, proxy configuration, custom headers, user-agent, and automatic retries for the video download engine.
 Package nethttp provides an HTTP client wrapper with cookie jar support, proxy configuration, custom headers, user-agent, and automatic retries for the video download engine.
Package types defines shared data structures for the video download engine including VideoInfo, Format, Fragment, Thumbnail, Subtitle, Chapter, and error types.
 Package types defines shared data structures for the video download engine including VideoInfo, Format, Fragment, Thumbnail, Subtitle, Chapter, and error types.
Package utils provides shared utility functions for the video download engine including filename sanitization, HTML metadata extraction, URL manipulation, duration/filesize parsing, and nested JSON traversal.
 Package utils provides shared utility functions for the video download engine including filename sanitization, HTML metadata extraction, URL manipulation, duration/filesize parsing, and nested JSON traversal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.