media

package module
v0.3.3 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

go-media

Universal media processing library for Go: download video from social platforms, extract audio, and transcribe speech.

Install

go get github.com/anatolykoptev/go-media

Usage

package main

import (
    "context"
    "fmt"

    "github.com/anatolykoptev/go-media"
    "github.com/anatolykoptev/go-media/extract/instagram"
    "github.com/anatolykoptev/go-media/transcribe/openai"
    threads "github.com/anatolykoptev/go-threads"
)

func main() {
    // Set up platform client
    threadsClient, _ := threads.NewClient(threads.Config{})

    // Create processor with extractors and transcriber
    p := media.NewProcessor(
        media.WithExtractor(instagram.New(threadsClient)),
        media.WithTranscriber(openai.New("http://localhost:8092/v1")),
    )

    // Process a video URL
    result, err := p.Process(context.Background(), "https://instagram.com/reel/ABC123", media.Options{
        MaxSize:  50 * 1024 * 1024, // 50 MB limit
        ChunkSec: 20,               // 20s audio chunks for Whisper
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Video: %s\n", result.VideoPath)
    if result.Transcription != nil {
        fmt.Printf("Text: %s\n", result.Transcription.Text)
    }
}

Supported Platforms

Platform Status Package
Instagram/Threads ✅ extract/instagram
YouTube ✅ extract/youtube
Twitter/X Planned extract/twitter
Reddit Planned extract/reddit
Telegram Planned extract/telegram
TikTok Planned extract/tiktok
VK Planned extract/vk

Transcription Backends

Backend Package
OpenAI-compatible (ox-whisper, Groq) transcribe/openai
go-stt transcribe/gostt

Requirements

  • Go 1.26+
  • ffmpeg and ffprobe in PATH (for audio extraction)

License

MIT

Documentation

Overview

Package media provides a pipeline for downloading videos from social platforms, extracting audio, and transcribing speech.

Index

Constants

View Source 
const (
	// DefaultDownloadTimeout is the maximum time for downloading a video file.
	DefaultDownloadTimeout = 120 * time.Second

	// DefaultFFmpegTimeout is the maximum time for an ffmpeg operation.
	DefaultFFmpegTimeout = 60 * time.Second

	// DefaultProbeTimeout is the maximum time for ffprobe duration check.
	DefaultProbeTimeout = 10 * time.Second

	// DefaultChunkSec is the default audio chunk duration in seconds for transcription.
	DefaultChunkSec = 20

	// DefaultClipPaddingSec is the default padding applied to video clips
	// before and after transcription chunk boundaries, to avoid cutting mid-word.
	DefaultClipPaddingSec = 0.5

	// DefaultFadeDurationSec is the audio fade duration at clip boundaries
	// to prevent clicks/pops from non-zero-crossing cuts.
	DefaultFadeDurationSec = 0.03
)

Default configuration values for the media processing pipeline.

Variables

This section is empty.

Functions

func DownloadFile 

func DownloadFile(ctx context.Context, client HTTPDoer, url, destPath string, maxSize int64) error

DownloadFile downloads a URL to a local file with timeout and size limit.

func ExtractAudioChunk 

func ExtractAudioChunk(ctx context.Context, videoPath, outputPath string, offsetSec, durationSec int) error

ExtractAudioChunk extracts a WAV audio chunk from a video file using ffmpeg. Output is 16kHz mono PCM suitable for Whisper.

func ExtractVideoClip added in v0.3.2 

func ExtractVideoClip(ctx context.Context, videoPath, outputPath string, startSec, endSec float64) error

ExtractVideoClip extracts a video segment from startSec to endSec using ffmpeg. Video stream is copied (-c:v copy) for fast, lossless extraction. Audio gets a short fade-in/fade-out to prevent clicks at cut boundaries. The -ss flag is placed before -i for fast keyframe-level seeking.

func MergeAudioVideo 

func MergeAudioVideo(ctx context.Context, videoPath, audioPath, outputPath string) error

MergeAudioVideo combines a video-only and audio-only file into a single MP4 using ffmpeg. Used for DASH streams where video and audio are separate.

func ProbeDuration 

func ProbeDuration(ctx context.Context, path string) (int, error)

ProbeDuration returns video/audio duration in seconds using ffprobe. Returns an error if ffprobe is not installed, fails, or the file has no duration.

Types

type Chunk 

type Chunk struct {
	Start float64 // segment start time in seconds
	End   float64 // segment end time in seconds
	Text  string  // transcribed text for this segment
}

Chunk represents a single transcribed audio segment.

type Extractor 

type Extractor interface {
	// Name returns the platform name (e.g. "instagram", "youtube").
	Name() string
	// Match returns true if the URL belongs to this platform.
	Match(url string) bool
	// Extract fetches media metadata including the direct video URL.
	Extract(ctx context.Context, url string) (*Media, error)
}

Extractor fetches media metadata from a platform-specific URL.

type HTTPDoer 

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer abstracts an HTTP client for testing.

type Media 

type Media struct {
	Platform    string            // platform name: "instagram", "youtube", etc.
	URL         string            // original input URL
	VideoURL    string            // direct video CDN URL
	AudioURL    string            // separate audio URL (for DASH merge)
	LocalPath   string            // path to already-downloaded file (skips download)
	Title       string            // post/video title
	Description string            // post caption or video description
	Author      string            // author display name or @username
	Duration    time.Duration     // video duration (zero if unknown)
	Qualities   []Quality         // available quality options
	Stats       MediaStats        // engagement stats (likes, views, etc.)
	Metadata    map[string]string // platform-specific key-value pairs
}

Media represents extracted metadata and download information for a video.

type MediaStats 

type MediaStats struct {
	Views    int64 // view/play count
	Likes    int64 // like/heart count
	Comments int64 // comment/reply count
}

MediaStats holds engagement metrics for a media post.

type Options 

type Options struct {
	MaxSize        int64   // max video file size in bytes (0 = no limit)
	ChunkSec       int     // audio chunk duration for transcription (default 20)
	TempDir        string  // directory for temporary files (default os.TempDir())
	ExtractClips   bool    // if true, extract video clips for each transcription chunk
	ClipPaddingSec float64 // seconds to extend clips before/after chunk boundaries (default 0.5)
}

Options configures a single Process call.

type Processor 

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

Processor orchestrates the full media pipeline: extract → download → transcribe.

func NewProcessor 

func NewProcessor(opts ...ProcessorOption) *Processor

NewProcessor creates a Processor with the given options.

func (*Processor) Extract 

func (p *Processor) Extract(ctx context.Context, url string) (*Media, error)

Extract finds the matching extractor and returns media metadata.

func (*Processor) Platforms 

func (p *Processor) Platforms() []string

Platforms returns names of all registered extractors.

func (*Processor) Process 

func (p *Processor) Process(ctx context.Context, url string, opts Options) (*Result, error)

Process runs the full pipeline: extract metadata → download video → transcribe audio. The caller is responsible for cleaning up the temp directory and downloaded files after Process returns. If opts.TempDir is empty, files are placed in os.TempDir()/go-media.

type ProcessorOption 

type ProcessorOption func(*Processor)

ProcessorOption configures a Processor.

func WithExtractor 

func WithExtractor(e Extractor) ProcessorOption

WithExtractor registers a platform extractor.

func WithHTTPClient 

func WithHTTPClient(doer HTTPDoer) ProcessorOption

WithHTTPClient sets a custom HTTP client for video downloads.

func WithTranscriber 

func WithTranscriber(t Transcriber) ProcessorOption

WithTranscriber sets the transcription backend.

type Quality 

type Quality struct {
	Label  string // human label: "1080p", "720p", "360p"
	URL    string // direct download URL for this quality
	Width  int    // pixels, 0 if unknown
	Height int    // pixels, 0 if unknown
	Size   int64  // estimated bytes, 0 if unknown
}

Quality represents a single video quality variant.

type Registry 

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

Registry holds registered extractors and dispatches URLs to the matching one.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty extractor registry.

func (*Registry) Extract 

func (r *Registry) Extract(ctx context.Context, url string) (*Media, error)

Extract finds the matching extractor and extracts media metadata.

func (*Registry) Match 

func (r *Registry) Match(url string) Extractor

Match finds the first extractor that matches the given URL. Returns nil if no extractor matches.

func (*Registry) Platforms 

func (r *Registry) Platforms() []string

Platforms returns the names of all registered extractors.

func (*Registry) Register 

func (r *Registry) Register(e Extractor)

Register adds an extractor to the registry.

type Result 

type Result struct {
	Media         *Media         // extracted media metadata
	VideoPath     string         // path to downloaded video file
	Transcription *Transcription // transcription result (nil if not requested or no speech)
	VideoClips    []VideoClip    // extracted video clips (nil if ExtractClips option not set)
}

Result is the output of a full processing pipeline.

type Transcriber 

type Transcriber interface {
	// Transcribe processes an audio file and returns the transcription.
	// audioPath must be a valid file path to a WAV/MP3/OGG file.
	Transcribe(ctx context.Context, audioPath string) (*Transcription, error)
	// Available reports whether the transcription backend is reachable.
	Available() bool
}

Transcriber converts an audio file to text.

type Transcription 

type Transcription struct {
	Text         string  // full concatenated text
	Language     string  // detected language code (e.g. "en", "ru")
	Duration     float64 // audio duration in seconds
	Chunks       []Chunk // per-segment results with timestamps
	FailedChunks int     // number of chunks that failed extraction or transcription
}

Transcription holds the result of speech-to-text processing.

func ChunkAndTranscribe 

func ChunkAndTranscribe(ctx context.Context, videoPath, tempDir string, t Transcriber, opts Options) (*Transcription, error)

ChunkAndTranscribe splits audio into chunks and transcribes each one. Returns (nil, nil) if transcriber is nil (opt-out). Returns (nil, error) if the transcriber is unavailable or ffprobe fails. Returns (partial, error) if some chunks failed — the partial result contains the successfully transcribed text and FailedChunks is set.

type VideoClip added in v0.3.2 

type VideoClip struct {
	Path  string  // path to the extracted clip file
	Start float64 // clip start time in seconds
	End   float64 // clip end time in seconds
	Text  string  // transcription text for this clip
}

VideoClip is a short video segment extracted from the downloaded video, corresponding to a transcription chunk. The caller is responsible for cleaning up the clip files (Path) after use.

func ExtractVideoClipsFromChunks added in v0.3.2 

func ExtractVideoClipsFromChunks(ctx context.Context, videoPath, tempDir string, chunks []Chunk, paddingSec, totalDuration float64) ([]VideoClip, int)

ExtractVideoClipsFromChunks extracts video clips for each transcription chunk. Clips are named "<base>_clip_<index>.mp4" in tempDir. Chunks with empty text are skipped. Each clip is extended by paddingSec before and after the chunk boundary (clamped to [0, totalDuration]) to avoid cutting mid-word. Returns the extracted clips and a count of failures.

Source Files

View all Source files

Directories

Path Synopsis
extract
instagram
Package instagram extracts video metadata from Instagram and Threads URLs using the go-threads client library.
 Package instagram extracts video metadata from Instagram and Threads URLs using the go-threads client library.
youtube
Package youtube extracts video metadata from YouTube URLs using a tiered backend approach: API → yt-dlp → ox-browser.
 Package youtube extracts video metadata from YouTube URLs using a tiered backend approach: API → yt-dlp → ox-browser.
transcribe
gostt
Package gostt provides a Transcriber that wraps the go-stt client library.
 Package gostt provides a Transcriber that wraps the go-stt client library.
openai
Package openai provides a Transcriber that uses an OpenAI-compatible STT API (works with ox-whisper, Groq, OpenAI, etc.).
 Package openai provides a Transcriber that uses an OpenAI-compatible STT API (works with ox-whisper, Groq, OpenAI, etc.).

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.