Skip to content

md_generator.media.youtube API Reference

Summary

Item Value
Purpose Convert YouTube URLs to Transcript and metadata Markdown
CLI md-youtube
Extra youtube
Tier simple

Quick CLI reference

Argument Type Required Default Choices Help
url str required — — YouTube watch / youtu.be / shorts URL
output Path required — — Output .md file path
--title str optional None — Override title in Markdown
--transcript-lang str optional None — Preferred transcript language (repeatable), e.g. --transcript-lang hi --transcript-lang en
--transcript-langs str optional None — Comma-separated preferred transcript languages (alternative to --transcript-lang)
--no-audio-fallback flag optional false — Do not download audio with yt-dlp + Whisper if captions are missing
--whisper-model str optional 'base' — Whisper model when audio fallback runs (default: base)
--language str optional None — Whisper language when audio fallback runs (same semantics as md-audio)
-v flag optional false — —

Primary symbols

Symbol Kind Notes
YouTubeToMarkdownService callable —
YouTubeConverter callable —

Python API (mkdocstrings)

youtube

YouTube URL → Markdown (metadata, description, timestamped transcript).

YouTubeConverter

YouTubeConverter(*, service: YouTubeToMarkdownService | None = None, transcript_languages: list[str] | None = None, enable_audio_fallback: bool = True)

Bases: DocumentConverter

convert(path) reads a small text file containing one YouTube URL per line (first non-empty line wins). Use accepts(path) to detect supported files.

YouTubeMarkdownFormatter

Build Markdown: # YouTube, title, metadata, description, timestamped transcript.

YouTubeMetadataError

Bases: RuntimeError

Raised when metadata cannot be fetched or parsed.

YouTubeConversionResult dataclass

YouTubeConversionResult(metadata: dict[str, Any], segments: tuple[dict[str, Any], ...] = tuple())

Structured output from YouTubeToMarkdownService.build_result.

YouTubeError

Bases: RuntimeError

Base error for YouTube conversion.

YouTubeToMarkdownService

YouTubeToMarkdownService(*, formatter: YouTubeMarkdownFormatter | None = None, whisper_model: str = 'base', whisper_language: str | None = None)

Fetch metadata and transcript, optionally fall back to Whisper on downloaded audio.

YouTubeTranscriptError

Bases: RuntimeError

Raised when no transcript can be retrieved after retries and fallbacks.

extract_video_id

extract_video_id(url: str) -> str | None

Return 11-character video id or None if url is not a recognized YouTube URL.

fetch_youtube_metadata

fetch_youtube_metadata(video_id: str, page_url: str | None = None, *, client: Client | None = None) -> dict[str, Any]

Return metadata dict: title, description, views, keywords, duration_seconds, author, url.

Uses watch-page HTML (BeautifulSoup) plus oEmbed JSON as fallback for title/author. Missing fields are omitted or None (never fabricated).

normalize_youtube_url

normalize_youtube_url(url: str) -> str

Return canonical https watch URL for a valid YouTube input.

read_youtube_url_from_path

read_youtube_url_from_path(path: Path) -> str

Read first non-empty, non-comment line from a text file as the YouTube URL.

fetch_transcript

fetch_transcript(video_id: str, preferred_languages: list[str] | None = None, *, attempts: int = 3) -> list[dict[str, Any]]

Return segments [{"start": float, "text": str}, ...].

Tries preferred_languages in order, then lets the API pick any available transcript.