mediafetch

README

mediafetch-go

mediafetch-go is a lightweight Go package for fetching media metadata and downloading supported videos through yt-dlp.

It is designed for apps that need a small in-process media layer without building a full downloader service.

With it, you can:

• validate a supported media URL
• extract title, thumbnail, duration, and available formats
• normalize download options for your UI or API
• download the selected file to disk

This repository is the reusable package only. There is no bundled web app, CLI, or API server.

Supported Providers

• Facebook
• Instagram
• TikTok
• Twitter/X
• YouTube
• Reddit

Requirements

Your runtime environment needs:

• Go 1.24 or newer
• yt-dlp available on PATH
• ffmpeg available on PATH

Install

The repo is documented as:

module github.com/Coop25/mediafetch-go

Example import:

import mediafetch "github.com/Coop25/mediafetch-go"

If you prefer, you can also copy the package files directly into another project as an internal package.

Files needed for that approach:

• client.go
• types.go
• providers.go
• exec.go
• ytdlp_types.go

API Overview

Main exported pieces:

• NewClient
• ClientConfig
• Client
• ValidateSupportedURL
• IsFacebookURL
• IsInstagramURL
• IsTikTokURL
• IsTwitterURL
• IsYouTubeURL
• IsRedditURL
• Format
• VideoInfo

Quick Start

Create a client:

client, err := mediafetch.NewClient(mediafetch.ClientConfig{
	DownloadDir: "downloads",
})

Extract metadata:

downloadID, info, err := client.Extract(ctx, videoURL)

Extract returns:

• a generated download ID
• a VideoInfo value
• an error if extraction fails

Download the file:

filePath, err := client.Download(ctx, videoURL, downloadID, "best")

Download returns the local file path written by yt-dlp.

Fallback Providers

mediafetch-go can also use optional fallback providers when yt-dlp is not enough.

Add them through ClientConfig:

client, err := mediafetch.NewClient(mediafetch.ClientConfig{
	DownloadDir: "downloads",
	FallbackProviders: []mediafetch.FallbackProvider{
		myFacebookFallback,
	},
})

A fallback provider can return:

• a canonical URL to retry with yt-dlp
• normalized VideoInfo
• direct media URLs that mediafetch-go can download itself

This is useful for browser-assisted or scraper-backed Facebook flows without forcing them into the main yt-dlp path.

Example

package main

import (
	"context"
	"log"

	mediafetch "github.com/Coop25/mediafetch-go"
)

func main() {
	client, err := mediafetch.NewClient(mediafetch.ClientConfig{
		DownloadDir: "downloads",
	})
	if err != nil {
		log.Fatal(err)
	}

	url := "https://youtu.be/dQw4w9WgXcQ"

	downloadID, info, err := client.Extract(context.Background(), url)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("title:", info.Title)
	log.Println("formats:", len(info.Formats))

	filePath, err := client.Download(context.Background(), url, downloadID, "best")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("saved to:", filePath)
}

URL Helpers

Use the helpers when you want to check support before extraction:

mediafetch.ValidateSupportedURL(url)
mediafetch.IsFacebookURL(url)
mediafetch.IsInstagramURL(url)
mediafetch.IsTikTokURL(url)
mediafetch.IsTwitterURL(url)
mediafetch.IsYouTubeURL(url)
mediafetch.IsRedditURL(url)

Data Model

VideoInfo contains:

• ThumbnailURL
• Title
• Duration
• Formats

Each Format contains:

• FormatID
• Resolution
• Ext
• Filesize
• FormatNote

How It Works

mediafetch-go delegates provider-specific extraction and downloading to yt-dlp, while the Go package handles:

• supported-host validation
• metadata parsing
• format normalization
• download directory management
• friendlier application-facing errors

Repository Layout

.
|-- client.go
|-- exec.go
|-- providers.go
|-- types.go
|-- ytdlp_types.go
|-- go.mod
`-- LICENSE

Notes

• This package depends on upstream yt-dlp behavior, so provider changes can break extraction.
• Some videos may fail if they are private, age-restricted, login-protected, or region-limited.
• Facebook URLs are resolved to their final video URL when possible, but some restricted or login-gated posts may still fail.
• Instagram and TikTok support public posts only and may fail on login-gated or restricted content.
• Twitter/X support public posts only and may fail on protected, login-gated, or restricted content.

Personal Use

• Use this responsibly and in compliance with local law.
• Respect platform terms of service and copyright restrictions.
• Do not redistribute downloaded content without permission.

Documentation

Index

• func IsFacebookURL(raw string) bool
• func IsInstagramURL(raw string) bool
• func IsRedditURL(raw string) bool
• func IsTikTokURL(raw string) bool
• func IsTwitterURL(raw string) bool
• func IsYouTubeURL(raw string) bool
• func ValidateSupportedURL(raw string) bool
• type Client
  • func NewClient(cfg ClientConfig) (*Client, error)
  • func (c *Client) Download(ctx context.Context, rawURL, downloadID, formatID string) (string, error)
  • func (c *Client) DownloadDir() string
  • func (c *Client) Extract(ctx context.Context, rawURL string) (string, VideoInfo, error)
• type ClientConfig
• type DirectMedia
• type FallbackMedia
• type FallbackProvider
• type Format
• type VideoInfo

Functions

func IsFacebookURL

func IsFacebookURL(raw string) bool

func IsInstagramURL

func IsInstagramURL(raw string) bool

func IsRedditURL

func IsRedditURL(raw string) bool

func IsTikTokURL

func IsTikTokURL(raw string) bool

func IsTwitterURL

func IsTwitterURL(raw string) bool

func IsYouTubeURL

func IsYouTubeURL(raw string) bool

func ValidateSupportedURL

func ValidateSupportedURL(raw string) bool

Types

type Client

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

func NewClient

func NewClient(cfg ClientConfig) (*Client, error)

func (*Client) Download

func (c *Client) Download(ctx context.Context, rawURL, downloadID, formatID string) (string, error)

func (*Client) DownloadDir

func (c *Client) DownloadDir() string

func (*Client) Extract

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

type ClientConfig

type ClientConfig struct {
	DownloadDir       string
	YTDLPBinary       string
	FallbackProviders []FallbackProvider
}

type DirectMedia

type DirectMedia struct {
	FormatID   string `json:"format_id"`
	URL        string `json:"url"`
	Resolution string `json:"resolution"`
	Ext        string `json:"ext"`
	Filesize   *int64 `json:"filesize,omitempty"`
	FormatNote string `json:"format_note"`
}

type FallbackMedia

type FallbackMedia struct {
	CanonicalURL string        `json:"canonical_url,omitempty"`
	Info         VideoInfo     `json:"info"`
	Downloads    []DirectMedia `json:"downloads,omitempty"`
}

type FallbackProvider

type FallbackProvider interface {
	Supports(rawURL string) bool
	Resolve(ctx context.Context, rawURL string) (*FallbackMedia, error)
}

type Format

type Format struct {
	FormatID   string `json:"format_id"`
	Resolution string `json:"resolution"`
	Ext        string `json:"ext"`
	Filesize   *int64 `json:"filesize,omitempty"`
	FormatNote string `json:"format_note"`
}

type VideoInfo

type VideoInfo struct {
	ThumbnailURL string
	Title        string
	Duration     *int
	Formats      []Format
}