Recursive AI

Select an HLS video rendition in C#

OneMedia is a free, open-source media library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

An HLS multivariant playlist lists alternative video streams. Choose one by index before reading its compressed packets; this does not decode or play video.

Terminal
dotnet add package RecursiveAI.OneMedia

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

hls/master.m3u8 and both local video renditions are in the download.

C#
using RecursiveAI.OneMedia.Streaming.Sources;
 
using var media = PresentationSource.Open(
    "hls/master.m3u8",
    new PresentationOptions { VariantIndex = 1 });
Console.WriteLine(media.Variants[1].Width);
int count = 0;
while (media.TryReadPacket(out var packet))
    count++;
Console.WriteLine($"Packets: {count}");
Text
320
Packets: 5

Reads the second variant: 320 pixels wide, with five packets.

Replace hls/master.m3u8 with your own master .m3u8; for a remote URL, call PresentationSource.OpenAsync with an IPresentationResolver that fetches the playlist and segments.

Unzip the example, then dotnet run.

The full program

The fixture is a silent blue clip in two resolutions. Its master playlist is:

Text
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=100000,RESOLUTION=160x90
low.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=300000,RESOLUTION=320x180
high.m3u8

Each child playlist has one segment and ends with EXT-X-ENDLIST. The high-resolution child is:

Text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:1
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:1.000000,
high0.ts
#EXT-X-ENDLIST

The low-resolution child has the same structure but names low0.ts. Both segments are in the zip. This program lists the advertised variants, reads index 1 and compares the packet bytes with the high-resolution segment:

C#
using System.Security.Cryptography;
using RecursiveAI.OneMedia;
using RecursiveAI.OneMedia.Streaming.Sources;
 
using var media = PresentationSource.Open("hls/master.m3u8",
    new PresentationOptions { VariantIndex = 1 });
for (int index = 0; index < media.Variants.Count; index++)
{
    var variant = media.Variants[index];
    Console.WriteLine($"{index}: {variant.Width}x{variant.Height}, {variant.Bandwidth} bit/s");
}
var hashes = new List<string>();
while (media.TryReadPacket(out var packet))
{
    hashes.Add(Convert.ToHexString(SHA256.HashData(packet.Data)));
}
Console.WriteLine($"Selected index: 1; packets: {hashes.Count}");
using var segment = Media.Open("hls/high0.ts");
var expected = new List<string>();
foreach (var packet in segment.Packets(segment.Tracks[0]))
{
    using (packet)
        expected.Add(Convert.ToHexString(SHA256.HashData(packet.Data.Span)));
}
Console.WriteLine($"Matches high0.ts: {hashes.SequenceEqual(expected)}");
Text
0: 160x90, 100000 bit/s
1: 320x180, 300000 bit/s
Selected index: 1; packets: 5
Matches high0.ts: True

A missing child playlist or segment raises a file error; an HLS multivariant playlist with no usable variant raises ManifestFormatException.

Variations

Choose the first variant instead. This replaces Program.cs and reads all its packets:

C#
using RecursiveAI.OneMedia.Streaming.Sources;
 
using var media = PresentationSource.Open(
    "hls/master.m3u8",
    new PresentationOptions { VariantIndex = 0 });
Console.WriteLine(media.Variants[0].Width);
int count = 0;
while (media.TryReadPacket(out var packet))
    count++;
Console.WriteLine($"Packets: {count}");
Text
160
Packets: 5

The short answer

Set PresentationOptions.VariantIndex when opening the HLS master playlist with PresentationSource.Open. The index is zero-based: 1 selects the second EXT-X-STREAM-INF entry, not the highest-bitrate entry by definition. Read Variants to see the playlist’s order and advertised dimensions and bandwidth.

OneMedia exposes the selected presentation as tracks and compressed packets. It does not render pictures, choose a quality automatically, or measure a connection to decide which rendition will play. The recipe makes a fixed selection at open time and reads that selection to the end.

What does “HLS video” mean?

HTTP Live Streaming describes media with playlists and segments. A media playlist lists the segments for a stream. A master, or multivariant, playlist describes alternative variant streams, often carrying the same content at different resolutions or bitrates. Opening a child media playlist directly bypasses the master’s choice of variants.

The download contains both levels. master.m3u8 points to low.m3u8 and high.m3u8. Each child points to one local MPEG-TS segment. The files are finished examples, not a continuously updating live stream, so reading ends at EXT-X-ENDLIST.

For local files, OneMedia resolves resources beneath the playlist directory. It has no built-in network fetching: an application that reads remote presentations supplies an IPresentationResolver. The streaming-source documentation describes that boundary and the same packet model used for finished media files.

What is HLS video quality?

An HLS playlist advertises properties of each variant, but those declarations are not a visual-quality measurement. In this example, one entry declares 160×90 and the other 320×180. The full program prints those entries in playlist order. It then checks that the returned packet payloads match the selected child’s segment, rather than assuming the advertised width alone proves which bytes were read.

PresentationVariant.Bandwidth uses AVERAGE-BANDWIDTH when that HLS attribute is present, otherwise BANDWIDTH. The latter is the peak-bandwidth declaration defined by RFC 8216. It is not a measurement taken while reading. The example master’s bandwidth values are illustrative declarations, not measured rates for the tiny sample segments.

Variants are not sorted by bandwidth. If your application offers a quality menu, label its choices from the manifest and retain their actual indexes. Do not assume index zero always means low quality or that the last entry is always the best match for a device. The default is the first entry; an index past the end selects the last, so validate a user’s choice before opening rather than relying on an out-of-range value as a selection strategy.

Can HLS have multiple video tracks?

A multivariant playlist can offer alternative video streams, but selecting one is not simultaneous playback of every listed stream. In this API, VariantIndex selects a variant at open time. A separate HLS audio group can add audio tracks to that selected presentation; its presence does not mean the reader also opens every video variant.

The sample deliberately has no audio. Its packet count therefore describes only the selected video. For an audiovisual presentation, inspect the tracks and packet track indexes rather than treating every packet as video. OneMedia interleaves packets from the selected rendition’s tracks by decode time.

Selection also does not decrypt content. The documented reader reports a protected presentation and delivers no packets for an HLS key method other than NONE. Nor is a fixed VariantIndex an adaptive-bitrate switching loop. For this task, decide which variant you need, open it with that index, and read the selected compressed stream.

All onemedia recipes