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",
	YTDLPSettings: mediafetch.YTDLPSettings{
		CookiesFromBrowser: "chrome",
	},
})

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.

Facebook Fallback

For Facebook URLs, mediafetch-go now tries yt-dlp first and then falls back to a browser-like HTML fetch flow when yt-dlp cannot extract the video.

That fallback currently:

• resolves Facebook share links to their final destination when possible
• retries against mobile Facebook page variants
• parses direct media fields such as browser_native_hd_url and playable_url
• detects signed video-*.xx.fbcdn.net/...mp4 CDN URLs exposed in the page source and normalizes away partial byte-range query parameters

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

YTDLPSettings contains optional runtime settings for the shared downloader core:

• UserAgent
• CookiesFromBrowser
• CookiesFile
• Proxy
• ConfigLocation

How It Works

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

• supported-host validation
• centralized yt-dlp runtime settings and argument building
• 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 Format
• type VideoInfo
• type YTDLPSettings

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
	YTDLPSettings YTDLPSettings
}

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
}

type YTDLPSettings

type YTDLPSettings struct {
	UserAgent          string
	CookiesFromBrowser string
	CookiesFile        string
	Proxy              string
	ConfigLocation     string
}