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
¶
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 ¶
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 ¶
Return canonical https watch URL for a valid YouTube input.
read_youtube_url_from_path ¶
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.