Metadata Model

Metadata Model

Ytdlp.NET uses strongly-typed classes to parse the rich JSON output from yt-dlp's --dump-single-json command.
These classes provide convenient, null-safe access to video metadata, formats, thumbnails, chapters, subtitles, and more.

All classes are in the Ytdlp.NET namespace.

Main Classes

Metadata

Represents the root object returned by --dump-single-json.

Property	Type	Description
Id	string	Video ID (e.g. "Xt50Sodg7sA")
Title	string	Video title
Description	string?	Full or truncated description
Thumbnail	string?	URL of primary thumbnail
Thumbnails	List<ThumbnailMetadata>?	All available thumbnails (various sizes)
Formats	List<FormatMetadata>?	All available formats
RequestedFormats	List<FormatMetadata>?	Formats actually selected/used
Duration	double?	Video duration in seconds
ViewCount	long?	Number of views
LikeCount	long?	Number of likes
UploadDate	string?	Upload date (YYYYMMDD format)
Channel	string?	Channel name
ChannelId	string?	Channel ID
ChannelFollowerCount	long?	Channel subscriber count
Uploader	string?	Uploader name
UploaderId	string?	Uploader ID/handle
UploaderUrl	string?	Uploader profile URL
Categories	List<string>?	Video categories (e.g. "Music", "Entertainment")
Tags	List<string>?	Video tags
Subtitles	Dictionary<string, List<SubtitleMetadata>>?	Manual subtitles by language
AutomaticCaptions	Dictionary<string, List<SubtitleMetadata>>?	Auto-generated captions
Chapters	List<ChapterMetadata>?	Video chapters/timestamps
Heatmap	List<HeatmapMetadata>?	Viewer attention heatmap data
LiveStatus	string?	"is_live", "was_live", "not_live"
IsLive / WasLive	bool?	Live stream status
WebpageUrl	string?	Original video URL
CommentCount	long?	Number of comments

Convenience properties (computed, [JsonIgnore]):

• DurationTimeSpan → TimeSpan? (from Duration)
• BestThumbnailUrl → highest-preference thumbnail URL
• HasSubtitles → true if subtitles or auto-captions exist

FormatMetadata

Represents a single format entry (from formats or requested_formats array).

Property	Type	Description
FormatId	string	Format code (e.g. "137", "251")
FormatNote	string	Human-readable note (e.g. "1080p", "medium")
Ext	string	File extension (mp4, webm, m4a, etc.)
Protocol	string	Delivery protocol (https, m3u8_native, etc.)
Vcodec	string	Video codec (avc1, vp9, av01, none)
Acodec	string	Audio codec (opus, mp4a.40.2, none)
Url	string	Direct download URL (may expire)
Resolution	string	Resolution string (e.g. "1920x1080")
Fps	double?	Frames per second
Width / Height	int?	Pixel dimensions
AspectRatio	double?	Width/height ratio
Abr / Vbr / Tbr	double?	Audio/video/total bitrate (kbps)
Filesize / FilesizeApprox	long?	Exact or approximate file size (bytes)
Fragments	List<FragmentMetadata>?	DASH/HLS fragment list (if present)
IsAudio	bool (computed)	True if audio-only (acodec != "none")
IsVideo	bool (computed)	True if video stream present
IsStoryboard	bool (computed)	True for storyboard/low-res image formats

Other Supporting Classes

• ThumbnailMetadata — thumbnails (url, height, width, preference, id)
• ChapterMetadata — chapters (start_time, end_time, title)
• HeatmapMetadata — attention heatmap (start_time, end_time, value)
• SubtitleMetadata — subtitle tracks (url, ext)
• FragmentMetadata — DASH/HLS fragments (url, duration)

Usage Examples

Fetch & display metadata

var meta = await ytdlp.GetVideoMetadataJsonAsync(url);

if (meta != null)
{
    Console.WriteLine($"Title: {meta.Title}");
    Console.WriteLine($"Duration: {meta.DurationTimeSpan?.ToString(@"mm\:ss") ?? "N/A"}");
    Console.WriteLine($"Views: {meta.ViewCount:N0}");
    Console.WriteLine($"Best thumbnail: {meta.BestThumbnailUrl}");

    var best1080p = meta.Formats?
        .Where(f => f.IsVideo && f.Height == 1080)
        .OrderByDescending(f => f.Fps ?? 0)
        .FirstOrDefault();

    if (best1080p != null)
        Console.WriteLine($"Best 1080p: {best1080p.FormatId} – {best1080p.Resolution} @ {best1080p.Fps} fps");
}

Select format from metadata

var meta = await ytdlp.GetVideoMetadataJsonAsync(url);

var bestAudio = meta?.Formats?
    .Where(f => f.IsAudio)
    .OrderByDescending(f => f.Abr ?? f.Tbr ?? 0)
    .FirstOrDefault();

if (bestAudio != null)
{
    await ytdlp.SetFormat(bestAudio.FormatId).ExtractAudio("mp3").ExecuteAsync(url);
}

Notes

• All properties that may be missing from yt-dlp output are nullable (?).
• Use ?. operator or null checks when accessing fields.
• Formats and RequestedFormats can be large (50–100+ entries) — filter early.
• Some fields (e.g. Filesize, LikeCount) are sometimes missing or approximate.

See also

• Usage Examples
• Changelog
• NuGet Gallery: https://www.nuget.org/packages/Ytdlp.Stable.Build (and others)

Last updated: February 15, 2026