Zeayii.Infrastructure.Streaming.Manifest 0.0.17

Zeayii.Infrastructure.Streaming.Manifest

English | 简体中文

Organization: zeayii
Project: vexo

HLS/DASH manifest parsing and fragment metadata generation
Built for download services, cloud repackaging, offline delivery, and DRM-aware pipelines

Overview

Zeayii.Infrastructure.Streaming.Manifest converts HLS (M3U8) and MPEG-DASH (MPD) manifests into unified task/stream/fragment metadata for downstream download, decryption, merge, and monitoring workflows. The module is intentionally “parse-only”: it performs no networking or persistence and relies on delegates to fetch remote content.

Highlights

• HLS master/media extraction: Parse master.m3u8, select VIDEO/AUDIO/SUBTITLE streams by strategy, expand media.m3u8 into Stream and Segment.
• DASH MPD extraction: Parse MPD XML with full Period/AdaptationSet/Representation inheritance; supports SegmentTemplate, SegmentList, and SegmentBase (+sidx).
• Pluggable stream selection: Bandwidth-first by default; customizable delegates for multilingual priorities, subtitle filtering, or bitrate caps.
• Range/index aware: Optional FetchRangeDelegate handles SegmentBase+sidx without hard-coding HTTP logic.
• AOT/trimming friendly: No reflection or dynamic code, aligned with Media/Abstractions runtime constraints.

HLS Support Scope

• Primary target: RFC8216 core semantics and mainstream Chrome-compatible playback pipelines (including common Widevine-oriented scenarios).
• Out of scope: Safari/FairPlay-specific playback paths and Apple-private extensions are intentionally not supported in this project stage.

Layout

• HLS/M3U8:
  • Extractor: HLS extractor, parsing context, and stream selector.
  • Schema: Master/Media playlist models.
• DASH/MPD:
  • Schema: MPD/Period/AdaptationSet/Representation and segment models (SegmentTemplate/SegmentList/SegmentBase, etc.).
  • Extractor: DASH extractor and fragment generation pipeline.
• Root Zeayii.Infrastructure.Streaming.Manifest.csproj: Packaging/trimming settings mirroring the Media module; references Zeayii.Infrastructure.Media.Container to reuse container parsing.

Design principles

• Parse-only with pluggable I/O: No built-in HTTP client. HLS uses HlsMediaFetchDelegate; DASH uses FetchRangeDelegate. This keeps the library portable across downloaders, serverless jobs, and offline tools.
• Unified metadata output: Emits TaskExecutionUnit/Stream/Segment, making downstream pipelines share a single contract.
• Spec-first, fail fast: For ambiguous or rare MPD expressions, the extractor throws (NotSupportedException) instead of guessing. HLS candidates must carry required fields before entering selection.
• Trimmable: IsTrimmable=true, no dynamic loading, ready for AOT and size-sensitive deployments.

Key flows

HLS (HlsManifestExtractor)

1. Inputs: baseUri, masterContent, TaskExecutionUnit, and HlsMediaFetchDelegate (fetches media.m3u8).
2. Candidate build: Parse master playlist → map to HlsStreamContext (Variants + EXT-X-MEDIA).
3. Stream selection: Default BestBandWidthStreamSelector; plug in custom selectors as needed.
4. Expand media playlists: Fetch each selected media.m3u8 → parse into Stream → emit ordered Segment (URI, duration, byte range).
5. Output: Populate task.StreamGroups for download/assembly.

DASH (DashManifestExtractor)

1. Inputs: mpdUrl, mpdContent, TaskExecutionUnit, optional FetchRangeDelegate (for SegmentBase+sidx) and StreamSelectionDelegate.
2. Context build: Parse MPD → iterate Period/AdaptationSet/Representation → resolve MIME/codecs/language/resolution/bandwidth → merge BaseURL and encryption flags.
3. Segment model resolution: Select SegmentTemplate/SegmentList/SegmentBase based on inheritance rules.
4. Stream selection: Group by (Period + StreamType + Language) and apply selector, defaulting to highest bandwidth per group.
5. Segment generation: Yield Segment (timing, sequence, URL, range, encryption flag) and attach to task.StreamGroups.

DASH Subtitle Timing and Type Classification (New)

• Assembly now distinguishes between text subtitles and container subtitles:
  • text subtitles: text/vtt, application/ttml+xml, etc.
  • container subtitles: application/mp4 / application/webm or codecs like wvtt / stpp.
• For text subtitles, timing is emitted when manifest data can resolve it reliably; otherwise timing is explicitly marked as SegmentTimingStatePolicy.Unavailable.
• Container subtitles are no longer dropped by extractor-side "timing unavailable" guard; segment plans are preserved for execution-side container handling.

Quick start

using Microsoft.Extensions.DependencyInjection;
using Zeayii.Infrastructure.Streaming.Manifest.Extensions;
using Zeayii.Infrastructure.Streaming.Manifest.HLS.M3U8.Extractor;
using Zeayii.Infrastructure.Streaming.Manifest.DASH.MPD.Extractor;
using Zeayii.Vexo.Assembly.Abstractions.ExecutionUnits;

var services = new ServiceCollection();
services.AddManifestAssemblyServices();
var provider = services.BuildServiceProvider();
var task = new TaskExecutionUnitBuilder { OutputDirectory = "output", SaveDirectory = "task", SaveName = "demo" };
var hls = provider.GetRequiredService<HlsManifestExtractor>();
await hls.ExtractAsync(
    new Uri(task.Url),
    masterContent,
    task,
    async (url, ct) => await httpClient.GetStringAsync(url, ct));

var dash = provider.GetRequiredService<DashManifestExtractor>();
await dash.ExtractAsync(
    new Uri(task.Url),
    mpdContent,
    task,
    fetchRangeAsync: null); // Provide when handling SegmentBase+sidx

Cooperation with other modules

• Media module: Depends on Zeayii.Infrastructure.Media.Container to keep fragment descriptions aligned with actual fMP4/sidx structures.
• Abstractions: Shares task/stream/fragment models from Zeayii.Vexo.Assembly.Abstractions, enabling reuse across Offline/Downloader/merging tools.
• Pipeline fit: Typical chain—manifest extraction → container parsing → download/decrypt/remux → persist/observe.

Extensibility

• Custom selectors: Implement HlsStreamSelectionDelegate / StreamSelectionDelegate for locale priorities, bitrate caps, or track filtering.
• Network adapters: Inject bespoke HTTP clients or caching layers via delegates for serverless or proxy-heavy environments.
• Spec coverage: To support additional MPD expressions, extend Schema models and augment parsing/validation in Extractor.

Development & testing

• Build: dotnet build Zeayii.Vexo.Assembly.sln (requires an SDK that supports net10.0).
• Unit/integration: Add samples for custom selectors and Range fetchers, covering common HLS/DASH playlist variants.
• Real fixtures: Manifest.Tests/TestData/real-index-cache now stores raw binary .mp4 fixtures and tests read bytes directly (no Base64 text decoding).
• Static analysis: Keep nullable and analyzer settings on to match project defaults.

License

Follows the repository root LICENSE; ensure compliance when distributing or embedding.