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
• 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
• 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.

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.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 links may require a direct video URL instead of a share link.

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 IsRedditURL(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

Functions

func IsFacebookURL

func IsFacebookURL(raw string) bool

func IsRedditURL

func IsRedditURL(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
}

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
}