9 Commits

Author SHA1 Message Date
hzrd149
2e4c3a0349 remove requirement for root "x" tag 2025-11-25 08:53:51 -06:00
hzrd149
d05228aae1 Merge branch 'master' into chunked-blobs 2025-11-25 08:50:30 -06:00
hzrd149
1d855e1633 move chunks to tags 2024-12-03 11:52:29 -06:00
hzrd149
51c93670aa replace merkle trees with simple hash 2024-11-14 07:45:05 -06:00
hzrd149
e39afe2149 simplify by removing cbor and full merkle tree 2024-11-12 10:04:25 +00:00
hzrd149
4d82f98b3c separate tree encoding from storage 2024-11-11 12:00:47 +00:00
hzrd149
8fc2e3dc31 small fix 2024-11-11 11:57:08 +00:00
hzrd149
a23d784673 typo 2024-11-11 11:55:54 +00:00
hzrd149
33714b6c0c add BUT-10 draft 2024-11-11 11:53:27 +00:00
4 changed files with 70 additions and 125 deletions

View File

@@ -27,7 +27,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi
- [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-08: Nostr File Metadata Tags](./buds/08.md)
- [BUD-09: Blob Report](./buds/09.md) - [BUD-09: Blob Report](./buds/09.md)
- [BUD-10: Blossom URI Schema](./buds/10.md) - [BUD-10: Blossom URI Schema](./buds/10.md)
- [BUD-11: HLS Video Formatting](./buds/11.md) - [BUD-12: Chunked blobs](./buds/12.md)
## Endpoints ## Endpoints
@@ -57,6 +57,7 @@ Blossom Servers expose a few endpoints for managing blobs
| ------- | ------------------- | ------------------ | | ------- | ------------------- | ------------------ |
| `24242` | Authorization event | [01](./buds/01.md) | | `24242` | Authorization event | [01](./buds/01.md) |
| `10063` | User Server List | [03](./buds/03.md) | | `10063` | User Server List | [03](./buds/03.md) |
| `2001` | Merkle tree | [12](./buds/12.md) |
## License ## License

View File

@@ -204,4 +204,3 @@ blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=
``` ```
blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831 blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831
``` ```

View File

@@ -1,123 +0,0 @@
# 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.

68
buds/12.md Normal file
View File

@@ -0,0 +1,68 @@
# BUD-12
## Chunked blobs
`draft` `optional`
Breaking large blobs into smaller chunks for distribution
### Chunking
The client MAY break large blobs into any number or size of chunks. although its recommended to use the size `1Mb` or `4Mb` for small and large chunks
Clients MUST NOT pad the remaining chunk, If clients need privacy they should use random chunk sizes and optionally encrypt the large blob
### Publishing
Clients should publish a `2001` kind event after chunking the file in order to store the list of chunks
The events MUST contain an ordered list of `chunk` tags with the sha256 hashes of the chunks
The `content` field MUST be a human readable description of the chunked file
```json
{
"tags": [
[ "chunk", "7e668b56a58c7891e0cf263ea3f093b75eebade23d663a45aa9920f347b3d671"],
[ "chunk", "9b9c44a91396f19fd8700986eb0586dff2dcccf96c75bc2caefef302bcd78da1"],
[ "chunk", "7a281548f1223664b855b10b08e59e84389ccabeb742517f6cd75eda2724a798"],
[ "chunk", "fadeccee86b123088bbc452df10e8fbc99d4c2f22a70ef7a35605ec8e439c345"],
[ "chunk", "5d62398419e6d136771541f3d2215e0ce31b1be45e99dbc64b43a4b734b447ca"],
]
}
```
### Metadata
The `2001` event MAY include additional metadata tags to help other clients know the filename, mime type or servers to download from
Metadata tags:
- `name` Filename
- `mime` Mime type of file
- `size` Total size in bytes of the file
- `server` (multiple) Recommended servers to download chunks from
### Examples
Example `2001` event
```json
{
"pubkey": "5328e6c743a50271745e16476590ba7ea3dc591c65f3a5e2b03430814c1dabc0",
"created_at": 1731405194,
"kind": 2001,
"content": "Large zip archive of documents",
"tags": [
[ "chunk", "7e668b56a58c7891e0cf263ea3f093b75eebade23d663a45aa9920f347b3d671"],
[ "chunk", "9b9c44a91396f19fd8700986eb0586dff2dcccf96c75bc2caefef302bcd78da1"],
[ "chunk", "7a281548f1223664b855b10b08e59e84389ccabeb742517f6cd75eda2724a798"],
[ "chunk", "fadeccee86b123088bbc452df10e8fbc99d4c2f22a70ef7a35605ec8e439c345"],
[ "chunk", "5d62398419e6d136771541f3d2215e0ce31b1be45e99dbc64b43a4b734b447ca"],
[ "name", "example.mp4" ],
[ "mime", "video/mp4" ],
[ "size", "4823449" ],
[ "server", "https://cdn.example.com" ],
[ "server", "https://nostr.download" ]
]
}
```