mediadl

package
v0.0.10 Latest Latest
Warning

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

 Go to latest Published: Jun 27, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package mediadl extracts transcripts and metadata from media URLs (YouTube, Instagram, and other yt-dlp supported sources) and transcribes audio through an STT provider. Platform-specific URL parsing lives in the caller; this package operates on an already-parsed ParsedURL.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsContextError 

func IsContextError(err error) bool

IsContextError reports whether err is a context cancellation or deadline error.

func IsNetworkBlocked 

func IsNetworkBlocked(err error) bool

IsNetworkBlocked reports whether err is a structured network-blocked error or a raw yt-dlp network-block diagnostic.

func IsRateLimited 

func IsRateLimited(err error) bool

IsRateLimited reports whether err is a structured rate-limit error or a raw yt-dlp rate-limit diagnostic.

func IsTranscriptUnavailable 

func IsTranscriptUnavailable(err error) bool

IsTranscriptUnavailable reports whether err signals that no transcript could be produced (no captions and no usable STT output).

func NewTranscriber 

func NewTranscriber(sttConfig config.STTConfig, openRouterConfig config.OpenRouterConfig) sttClient

NewTranscriber constructs the configured STT backend.

Types

type BackendConfig 

type BackendConfig struct {
	Platform      string
	YTDLPPath     string
	Proxy         string
	CookiesFile   string
	UserAgent     string
	RetryAttempts int
	RetryBackoff  string
}

BackendConfig holds the platform-neutral yt-dlp network knobs. Platform labels the source ("youtube", "instagram") so diagnostics can point at the right TOML section. RetryAttempts and RetryBackoff are consumed by NewExtractor.

type CaptionKind 

type CaptionKind string

CaptionKind identifies whether fetched captions were manual or ASR. 

const (
	CaptionKindManual    CaptionKind = "manual"
	CaptionKindAutomatic CaptionKind = "automatic"
)

type Error 

type Error struct {
	Kind    ErrorKind
	URL     string
	VideoID string
	Message string
	Err     error
}

Error carries structured failure details for callers that need to branch on platform-specific failure modes.

func (*Error) Error 

func (err *Error) Error() string

Error formats a human-readable error message.

func (*Error) Unwrap 

func (err *Error) Unwrap() error

Unwrap returns the underlying cause.

type ErrorKind 

type ErrorKind string

ErrorKind categorizes user-facing media extraction failures. 

const (
	// ErrorKindInvalidURL reports a malformed or unsupported media URL.
	ErrorKindInvalidURL ErrorKind = "invalid_url"
	// ErrorKindUnavailable reports media that cannot be accessed.
	ErrorKindUnavailable ErrorKind = "unavailable"
	// ErrorKindPrivate reports private media.
	ErrorKindPrivate ErrorKind = "private"
	// ErrorKindAgeRestricted reports media that requires login/age confirmation.
	ErrorKindAgeRestricted ErrorKind = "age_restricted"
	// ErrorKindTranscriptUnavailable reports missing or disabled captions/transcript.
	ErrorKindTranscriptUnavailable ErrorKind = "transcript_unavailable"
	// ErrorKindAudioUnavailable reports that no supported audio stream could be downloaded.
	ErrorKindAudioUnavailable ErrorKind = "audio_unavailable"
	// ErrorKindRateLimited reports a rate-limit response such as HTTP 429.
	ErrorKindRateLimited ErrorKind = "rate_limited"
	// ErrorKindNetworkBlocked reports a network block or bot-detection response.
	ErrorKindNetworkBlocked ErrorKind = "network_blocked"
)

type ExtractOptions 

type ExtractOptions struct {
	TranscriptionPolicy     TranscriptionPolicy
	PreferredLanguages      []string
	AllowTranslatedCaptions bool
}

ExtractOptions controls transcript extraction behavior.

type Extractor 

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

Extractor orchestrates transcript extraction and optional STT fallback.

func NewExtractor 

func NewExtractor(
	backendConfig BackendConfig,
	sttConfig config.STTConfig,
	openRouterConfig config.OpenRouterConfig,
) *Extractor

NewExtractor constructs an extractor from a platform-neutral backend config and STT provider configuration.

func (*Extractor) Extract 

func (extractor *Extractor) Extract(ctx context.Context, parsed ParsedURL, options ExtractOptions) (*Result, error)

Extract fetches media metadata and transcript markdown for an already-parsed media reference.

func (*Extractor) ListPlaylistEntries 

func (extractor *Extractor) ListPlaylistEntries(ctx context.Context, channelURL string, limit int) ([]PlaylistEntry, error)

ListPlaylistEntries resolves the raw entries for a channel or playlist URL. Callers apply platform-specific filtering and URL canonicalization.

type Metadata 

type Metadata struct {
	VideoID              string
	URL                  string
	Title                string
	Description          string
	Channel              string
	ChannelID            string
	UploaderID           string
	Duration             time.Duration
	DurationString       string
	PublishDate          time.Time
	ViewCount            *int64
	LikeCount            *int64
	CommentCount         *int64
	ChannelFollowerCount *int64
	Categories           []string
	VideoTags            []string
	Language             string
	LiveStatus           string
	WasLive              *bool
	ChapterCount         int
}

Metadata contains normalized media metadata.

type OpenAITranscriber 

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

OpenAITranscriber calls OpenAI's audio transcriptions endpoint.

func NewOpenAITranscriber 

func NewOpenAITranscriber(cfg config.STTConfig) *OpenAITranscriber

NewOpenAITranscriber constructs an OpenAI STT provider from runtime config.

func (*OpenAITranscriber) Configured 

func (client *OpenAITranscriber) Configured() bool

func (*OpenAITranscriber) Model 

func (client *OpenAITranscriber) Model() string

func (*OpenAITranscriber) Provider 

func (client *OpenAITranscriber) Provider() string

func (*OpenAITranscriber) Transcribe 

func (client *OpenAITranscriber) Transcribe(ctx context.Context, audio []byte, format string) (string, error)

type OpenRouterClient 

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

OpenRouterClient calls the OpenRouter chat completions API as an STT provider.

func NewOpenRouterClient 

func NewOpenRouterClient(cfg config.OpenRouterConfig) *OpenRouterClient

NewOpenRouterClient constructs an STT client from runtime configuration.

func NewOpenRouterClientWithPrompt 

func NewOpenRouterClientWithPrompt(cfg config.OpenRouterConfig, prompt string) *OpenRouterClient

func (*OpenRouterClient) Configured 

func (client *OpenRouterClient) Configured() bool

Configured reports whether the client has the credentials needed to call the OpenRouter API.

func (*OpenRouterClient) Model 

func (client *OpenRouterClient) Model() string

func (*OpenRouterClient) Provider 

func (client *OpenRouterClient) Provider() string

func (*OpenRouterClient) Transcribe 

func (client *OpenRouterClient) Transcribe(ctx context.Context, audio []byte, format string) (string, error)

Transcribe sends audio bytes to OpenRouter and returns the transcript text.

type ParsedURL 

type ParsedURL struct {
	CanonicalURL string
	VideoID      string
}

ParsedURL is a platform-neutral, already-validated media reference. Callers (the youtube/instagram shims) parse raw URLs into this form before extraction.

type PlaylistEntry 

type PlaylistEntry struct {
	ID         string
	Title      string
	URL        string
	WebpageURL string
}

PlaylistEntry is a single raw entry resolved from a channel or playlist URL. Callers apply platform-specific filtering and URL canonicalization.

type Result 

type Result struct {
	Metadata            Metadata
	Markdown            string
	Source              TranscriptSource
	Language            string
	CaptionKind         CaptionKind
	TranscriptionPolicy TranscriptionPolicy
	STTProvider         string
	STTModel            string
}

Result contains the extracted metadata and transcript markdown.

type TranscriptSource 

type TranscriptSource string

TranscriptSource identifies how the transcript was produced. 

const (
	// TranscriptSourceCaptions means platform captions were fetched directly.
	TranscriptSourceCaptions TranscriptSource = "captions"
	// TranscriptSourceSTT means audio was transcribed through an STT provider.
	TranscriptSourceSTT TranscriptSource = "stt"
)

type TranscriptionPolicy 

type TranscriptionPolicy string

TranscriptionPolicy controls whether captions or STT are used. 

const (
	TranscriptionPolicyCaptions TranscriptionPolicy = "captions"
	TranscriptionPolicyAuto     TranscriptionPolicy = "auto"
	TranscriptionPolicySTT      TranscriptionPolicy = "stt"
)

func ParseTranscriptionPolicy 

func ParseTranscriptionPolicy(value string) (TranscriptionPolicy, error)

ParseTranscriptionPolicy validates a transcription policy string.

Source Files

View all Source files

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.