Draft BUD-11 for HLS Videos

BUD-10: Add `blossom:<sha256>.ext` URI spec

README.md

@@ -26,6 +26,8 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
 - [BUD-07: Payment required](./buds/07.md)
 - [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
 

buds/10.md

@@ -0,0 +1,207 @@
+# BUD-10
+
+## Blossom URI Schema
+
+`draft` `optional`
+
+Defines a URI schema for referencing Blossom blobs similar to magnet links. This allows users to share blob references that include discovery hints for locating the blob on other Blossom servers.
+
+## URI Format
+
+The `blossom:` URI schema MUST follow this format:
+
+```
+blossom:<sha256>.<ext>[?param1=value1&param2=value2...]
+```
+
+### Components
+
+- `blossom:` - The URI scheme identifier
+- `<sha256>` - A 64 character lowercase hexadecimal sha256 hash of the blob
+- `.<ext>` - A file extension (e.g., `.pdf`, `.png`, `.jpg`, `.mp4`). If the file extension is unknown, it MUST default to `.bin`
+- `[?params]` - Optional query parameters for discovery hints
+
+### Examples
+
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin
+```
+
+## Query Parameters
+
+The `blossom:` URI MAY include the following optional query parameters to assist with blob discovery:
+
+### `as` - Author
+
+The `as` parameter specifies the hex pubkey of a user who uploaded the blob. This parameter MAY be repeated multiple times to specify multiple potential authors.
+
+Clients can use this parameter to lookup the author's [BUD-03](./03.md) server list (`kind:10063`) and attempt to retrieve the blob from those servers.
+
+Example:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0
+```
+
+Multiple authors:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036
+```
+
+### `xs` - Server
+
+The `xs` parameter specifies a server domain where the blob may be available. This parameter MAY be repeated multiple times to specify multiple server hints.
+
+The value SHOULD be a domain name only. Clients MUST assume the server operates at the root of the domain as per [BUD-01](./01.md#endpoints). The protocol scheme (http/https) MAY be included but is optional. When no scheme is specified, clients SHOULD try both `https://` and `http://` with preference given to `https://`.
+
+Example:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
+```
+
+With optional scheme:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth
+```
+
+Multiple servers:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net
+```
+
+### `sz` - Size
+
+The `sz` parameter MAY be used to specify the size of the blob in bytes. This can help clients:
+
+- Verify the downloaded blob matches the expected size
+- Display download progress or estimated time
+- Decide whether to download the blob based on size constraints
+- Pre-allocate storage space
+
+Example:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292
+```
+
+The size MUST be a positive integer representing the exact number of bytes in the blob. Clients SHOULD verify that the downloaded blob size matches the `sz` parameter if provided.
+
+### Combined Parameters
+
+All parameters MAY be combined in a single URI:
+
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292
+```
+
+## Client Implementation
+
+### Parsing blossom URIs
+
+When parsing a `blossom:` URI, clients MUST:
+
+1. Verify the URI starts with the `blossom:` scheme
+2. Extract the 64 character hexadecimal sha256 hash
+3. Extract the file extension (which MUST be present)
+4. Parse any query parameters (`as`, `xs`, and `sz`) into appropriate types to handle multiple values
+
+### Resolution Strategy
+
+When resolving a `blossom:` URI to retrieve the actual blob, clients SHOULD attempt retrieval in the following order:
+
+1. **Server Hints**: If the URI contains `xs` parameters, attempt to retrieve the blob from each specified server in the order they appear
+   - For servers without a protocol scheme, try `https://` first, then `http://`
+   - Request the blob using the [BUD-01](./01.md#get-sha256---get-blob) `GET /<sha256>` endpoint
+   - Include the file extension from the URI if present
+   - If the `sz` parameter is present, verify the `Content-Length` header matches before downloading
+
+2. **Author Server Lists**: If the URI contains `as` parameters, for each author pubkey:
+   - Fetch the author's [BUD-03](./03.md) server list (`kind:10063`)
+   - Attempt to retrieve the blob from each server in the author's list in order
+   - If multiple authors are specified, try each author's server list before giving up
+
+3. **Fallback Servers**: If the blob cannot be found using hints, clients MAY fallback to:
+   - Well-known public Blossom servers
+   - Local cache or previously known locations
+   - User-configured default servers
+
+When downloading is complete, if the `sz` parameter was provided, clients SHOULD verify that the downloaded blob size matches the expected size.
+
+### Example Resolution Flow
+
+Given this URI:
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
+```
+
+A client would:
+
+1. Try `http://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf`
+2. Check that `Content-Length` header is `184292` before downloading
+3. If that fails, fetch the `kind:10063` server list for pubkey `ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0`
+4. Try each server from the author's list in order
+5. Verify the downloaded blob is exactly `184292` bytes
+6. If still not found, fallback to well-known servers or local cache
+
+### Creating and Sharing blossom URIs
+
+When creating or sharing a `blossom:` URI, clients MUST:
+
+1. Always include the sha256 hash
+2. Always include a file extension - if the file extension is unknown or cannot be determined, default to `.bin` (similar to how [BUD-01](./01.md#get-sha256---get-blob) defaults the MIME type to `application/octet-stream`)
+
+Clients SHOULD also:
+
+3. Include the `sz` parameter with the blob size in bytes to help with verification and download management
+4. Include at least one `xs` parameter pointing to a server where the blob is known to exist
+5. Include the `as` parameter with the uploader's pubkey to enable future discovery via their server list
+6. Include multiple `xs` parameters if the blob has been mirrored to multiple servers
+
+Example of creating a URI after upload:
+
+```javascript
+// After uploading to cdn.satellite.earth
+const uri = `blossom:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`;
+```
+
+## Use Cases
+
+The `blossom:` URI schema enables several use cases:
+
+- **Decentralized Content Addressing**: Share content by hash with discovery hints instead of relying on a single server URL
+- **Resilient Links**: Links that can survive server outages by including multiple server hints or author information
+- **P2P Sharing**: Share blob references that don't depend on a specific server remaining online
+
+## Examples
+
+### Minimal URI
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
+```
+
+### Unknown File Type
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin
+```
+
+### With Single Server Hint
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth
+```
+
+### With Size and Author
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
+```
+
+### Full Featured URI
+```
+blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
+```
+
+### Image with Multiple Authors and Servers
+```
+blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831
+```
+

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 /<sha256>` 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 /<sha256>` 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 /<sha256>` endpoint
+3. Support optional file extensions (e.g., `/<sha256>.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/<sha256>.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.
+