From 2a9319e8c4a974e873e2d697ca4bd0d12a207bf4 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Tue, 25 Nov 2025 08:29:35 -0600 Subject: [PATCH] Draft BUD-11 for HLS Videos --- README.md | 1 + buds/11.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 buds/11.md diff --git a/README.md b/README.md index a8bfc2f..c661a93 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi - [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-09: Blob Report](./buds/09.md) - [BUD-10: Blossom URI Schema](./buds/10.md) +- [BUD-11: HLS Video Formatting](./buds/11.md) ## Endpoints diff --git a/buds/11.md b/buds/11.md new file mode 100644 index 0000000..decbd14 --- /dev/null +++ b/buds/11.md @@ -0,0 +1,123 @@ +# BUD-11 + +## HLS Video Formatting + +`draft` `optional` + +Defines how to format [HLS](https://datatracker.ietf.org/doc/html/rfc8216) (HTTP Live Streaming) videos to be compatible with [BUD-01](./01.md) blob retrieval. + +## Overview + +HLS videos consist of multiple files: +- A master playlist (`.m3u8`) that references variant playlists +- Variant playlists (`.m3u8`) that reference media segments +- Media segment files (typically `.ts` files) + +Each file MUST be uploaded as a separate blob and referenced by its SHA256 hash using the [BUD-01](./01.md#get-sha256---get-blob) `GET /` endpoint format. + +## Relative Paths + +To ensure compatibility across different Blossom servers and allow easy server switching, all URLs in HLS playlists MUST use relative paths containing the SHA256 hash of the referenced blob. + +Clients MUST NOT include the full server domain in playlist URLs. This allows the same playlist to work with any Blossom server that hosts the referenced blobs. + +## Master Playlist Format + +The master playlist (`.m3u8`) MUST reference variant playlists using relative paths with SHA256 hashes. + +The master playlist MUST have the MIME type `application/vnd.apple.mpegurl` or `application/x-mpegURL`. + +Example master playlist: + +```m3u8 +#EXTM3U +#EXT-X-VERSION:3 +#EXT-X-STREAM-INF:BANDWIDTH=1280000,RESOLUTION=854x480 +a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456.m3u8 +#EXT-X-STREAM-INF:BANDWIDTH=2560000,RESOLUTION=1280x720 +f6e5d4c3b2a1098765432109876543210987654321fedcba0987654321fedcba.m3u8 +``` + +## Variant Playlist Format + +Variant playlists (`.m3u8`) MUST reference media segments using relative paths with SHA256 hashes. + +Each segment URL MUST be a relative path containing the SHA256 hash of the segment file. The file extension (`.ts`, `.m4s`, etc.) MAY be included for compatibility with HLS clients. + +Example variant playlist: + +```m3u8 +#EXTM3U +#EXT-X-VERSION:3 +#EXT-X-TARGETDURATION:10 +#EXT-X-MEDIA-SEQUENCE:0 +#EXTINF:10.000, +b82fcf4dbcec2d8fab7d94bdd48b070aa6e74d7240b1965a0b28c128d6858477.ts +#EXTINF:10.000, +cd2a98d055eef5ec3aca73bd136a40340539138da73144d589d9de5a3a52149a.ts +#EXTINF:10.000, +128e690f89419ecbea473a490c42cac94a2293ecf1f57d60492ceafce3d5cfdb.ts +#EXT-X-ENDLIST +``` + +## Media Segments + +Media segment files (typically `.ts` files) MUST be uploaded as separate blobs. Each segment MUST be retrievable via the [BUD-01](./01.md#get-sha256---get-blob) `GET /` endpoint. + +The server SHOULD set the `Content-Type` header appropriately: +- `.ts` files: `video/mp2t` or `video/MP2T` +- `.m4s` files: `video/iso.segment` or `video/mp4` + +## Client Implementation + +When generating HLS playlists for Blossom: + +1. Upload each media segment as a separate blob using [BUD-02](./02.md#put-upload---upload-blob) `PUT /upload` +2. Upload each variant playlist as a separate blob +3. Upload the master playlist as a separate blob +4. In all playlists, use relative paths containing only the SHA256 hash (and optional file extension) of the referenced blob +5. When serving the master playlist, clients MAY prepend the current server's base URL to resolve relative paths + +Example client flow: + +1. Upload segment `segment001.ts` → get SHA256: `1a2b3c4d...` +2. Upload segment `segment002.ts` → get SHA256: `2b3c4d5e...` +3. Create variant playlist referencing `1a2b3c4d...ts` and `2b3c4d5e...ts` +4. Upload variant playlist → get SHA256: `a1b2c3d4...` +5. Create master playlist referencing `a1b2c3d4...m3u8` +6. Upload master playlist → get SHA256: `f9e8d7c6...` + +## Server Implementation + +When serving HLS playlists, servers MUST: + +1. Return the playlist content with the appropriate `Content-Type` header (`application/vnd.apple.mpegurl` or `application/x-mpegURL`) +2. Serve playlists via the [BUD-01](./01.md#get-sha256---get-blob) `GET /` endpoint +3. Support optional file extensions (e.g., `/.m3u8`) as specified in [BUD-01](./01.md#get-sha256---get-blob) + +When a client requests a playlist blob, the server MUST return the playlist content as-is, without modifying relative paths. The client is responsible for resolving relative paths to absolute URLs using the current server's base URL. + +## URL Resolution + +When a client retrieves a playlist from `https://cdn.example.com/.m3u8`, relative paths in the playlist (e.g., `a1b2c3d4...m3u8`) MUST be resolved relative to the playlist's origin. + +For example, if a playlist is served from `https://cdn.example.com/f9e8d7c6...m3u8` and contains a relative path `a1b2c3d4...m3u8`, the client SHOULD resolve it to `https://cdn.example.com/a1b2c3d4...m3u8`. + +This allows the same playlist blob to work with any Blossom server, as long as all referenced blobs are available on that server. + +## Example Complete Structure + +``` +Master Playlist (SHA256: f9e8d7c6...) + └─> Variant Playlist 1 (SHA256: a1b2c3d4...) + └─> Segment 1 (SHA256: 1a2b3c4d...) + └─> Segment 2 (SHA256: 2b3c4d5e...) + └─> Segment 3 (SHA256: 3c4d5e6f...) + └─> Variant Playlist 2 (SHA256: b2c3d4e5...) + └─> Segment 1 (SHA256: 4d5e6f78...) + └─> Segment 2 (SHA256: 5e6f7890...) + └─> Segment 3 (SHA256: 6f789012...) +``` + +All references between these files use relative paths containing only SHA256 hashes, making the entire HLS structure portable across different Blossom servers. +