torrent-gateway/docs/STANDARDS_PROPOSAL_GUIDE.md

# Standards Proposal Guide

This document walks you through submitting standards proposals to standardize the BitTorrent Gateway's innovative streaming and hybrid protocol features.

## 🎯 Overview

The BitTorrent Gateway implements pioneering features that deserve standardization:

1. **NIP-35 Streaming Extensions** - Adds streaming metadata to Nostr torrent announcements
2. **Blossom BUD-09** - Streaming support for the Blossom protocol
3. **Hybrid Protocol Specification** - BitTorrent + Blossom integration patterns

## 📋 Required Pull Requests

### 1. NIP-35 Streaming Extensions

**Repository**: https://github.com/nostr-protocol/nips  
**Target File**: `35.md`  
**Type**: Enhancement to existing NIP  

#### What to Propose

Add streaming-specific tags to NIP-35 to support video/audio streaming announcements:

**New Tags**:
- `stream`: Direct streaming URL
- `hls`: HLS playlist URL  
- `duration`: Content duration in seconds
- `video`: Resolution, framerate, codec info
- `m`: MIME type (following NIP-94 convention)

#### Proposed Addition to NIP-35

```markdown
## Streaming Extensions

For content that supports streaming, the following additional tags MAY be included:

- `stream` - Direct streaming URL for progressive download/streaming
- `hls` - HLS playlist URL (.m3u8) for adaptive streaming  
- `duration` - Duration in seconds for time-based media
- `video` - Video metadata as `<resolution>`, `<framerate>`, `<codec>`
- `m` - MIME type (following NIP-94)

### Example with Streaming

```json
{
  "kind": 2003,
  "content": "High-quality nature documentary",
  "tags": [
    ["title", "Nature Documentary"],
    ["x", "d1c5a0f85a4e4f3d8e7d8f9c6b5a4e3f2d1c0b9a8e7d6f5c4b3a2e1d0c9b8a7f6"],
    ["file", "nature-doc.mp4", "2147483648"],
    ["magnet", "magnet:?xt=urn:btih:..."],
    ["webseed", "https://example.com/api/webseed/hash"],
    ["stream", "https://example.com/api/stream/hash"],
    ["hls", "https://example.com/api/stream/hash/playlist.m3u8"],
    ["duration", "3600"],
    ["video", "1920x1080", "30fps", "h264"],
    ["m", "video/mp4"],
    ["t", "video"],
    ["t", "streaming"],
    ["tcat", "video,documentary"]
  ]
}
```

These extensions enable:
- **Stream Discovery**: Users can find streamable content
- **Player Integration**: Video players can directly consume streams  
- **Quality Selection**: Multiple formats and qualities can be announced
- **Social Streaming**: Comments and reactions on streaming content
```

### 2. Blossom BUD-11: Streaming Support

**Repository**: https://github.com/hzrd149/blossom  
**Target Directory**: `buds/`  
**File**: `buds/11.md`  
**Type**: New BUD (Blossom Upgrade Document)

#### What to Propose

Create BUD-11 to define streaming endpoints and behavior for Blossom servers:

**New Endpoints**:
- `GET /{hash}/stream` - Direct blob streaming with range support
- `GET /{hash}/playlist.m3u8` - HLS playlist generation  
- `GET /{hash}/segment/{n}` - HLS segment delivery
- `GET /{hash}/info` - Media metadata extraction

#### Complete BUD-11 Draft

```markdown
# BUD-11: Streaming Support

## Abstract

This BUD defines streaming endpoints for Blossom servers to support direct video/audio streaming and HLS (HTTP Live Streaming) delivery from stored blobs.

## Motivation  

As Blossom adoption grows for media storage, there's increasing need for streaming capability without requiring separate streaming infrastructure. This BUD enables:

- Direct blob streaming with HTTP range support
- HLS playlist generation from single blobs  
- Adaptive streaming for better user experience
- Integration with existing video players

## Specification

### Streaming Endpoint

```
GET /<hash>/stream
```

Servers implementing BUD-09 MUST support:
- HTTP range requests (RFC 7233)  
- Proper MIME type detection and headers
- CORS headers for web player compatibility

**Headers**:
- `Accept-Ranges: bytes`
- `Content-Type: <detected-mime-type>`
- `Content-Length: <blob-size>`
- `Access-Control-Allow-Origin: *`

### HLS Playlist Endpoint  

```
GET /<hash>/playlist.m3u8
```

For video/audio blobs, servers MAY generate HLS playlists:
- Virtual segmentation of the blob
- Standard M3U8 format compliance
- Segment duration typically 6-10 seconds

**Example Response**:
```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:7
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6.000,
<hash>/segment/0
#EXTINF:6.000,
<hash>/segment/1
#EXT-X-ENDLIST
```

### HLS Segment Endpoint

```  
GET /<hash>/segment/<n>
```

Delivers virtual segments from the blob:
- Segment boundaries calculated from blob size
- Proper byte range extraction  
- Video container format preservation

### Media Info Endpoint

```
GET /<hash>/info  
```

Returns JSON metadata about media blobs:

```json
{
  "hash": "sha256...",
  "size": 104857600,
  "mime_type": "video/mp4", 
  "duration": 3600,
  "video": {
    "width": 1920,
    "height": 1080,
    "codec": "h264",
    "fps": "30"
  },
  "streaming": {
    "stream_url": "/<hash>/stream",
    "hls_url": "/<hash>/playlist.m3u8"
  }
}
```

## Implementation Notes

- Servers SHOULD cache generated playlists for performance
- Range requests MUST be handled efficiently for large blobs
- Video codec compatibility varies by browser
- Consider implementing quality variants for adaptive streaming

## References

- RFC 8216: HTTP Live Streaming (HLS)
- RFC 7233: Range Requests  
- BUD-01: Authorization  
- BUD-02: Upload and List
```

### 3. Hybrid Protocol Specification

**Repository**: Create new repository or add to existing project  
**Target**: New specification document  
**Type**: Protocol definition

#### What to Propose

Document the hybrid BitTorrent + Blossom approach as a reusable pattern:

**Key Components**:
- Storage threshold rules (when to use Blossom vs BitTorrent)
- WebSeed integration patterns
- Chunk mapping strategies  
- Fallback hierarchies
- P2P bootstrapping methods

## 📝 Step-by-Step Submission Process

### Step 1: Fork the Repositories

```bash
# Fork NIP repository  
git clone https://github.com/YOUR_USERNAME/nips.git
cd nips

# Fork Blossom repository
git clone https://github.com/YOUR_USERNAME/blossom.git  
cd blossom
```

### Step 2: Create Feature Branches

```bash
# In nips repository
git checkout -b nip-35-streaming-extensions
git push -u origin nip-35-streaming-extensions

# In blossom repository  
git checkout -b bud-11-streaming-support
git push -u origin bud-11-streaming-support
```

### Step 3: Make the Changes

#### NIP-35 Changes

1. Edit `35.md`
2. Add streaming extensions section (see above)
3. Update examples to include new tags
4. Test with reference implementation

```bash
cd nips
# Edit 35.md with streaming extensions
git add 35.md
git commit -m "Add streaming extensions to NIP-35

- Add stream, hls, duration, video tags for streaming media
- Include comprehensive example with streaming metadata  
- Enable social streaming discovery and player integration
- Maintains backward compatibility with existing implementations"
```

#### BUD-11 Creation

1. Create `buds/11.md`
2. Write complete BUD specification (see above)
3. Include implementation examples

```bash
cd blossom
# Create buds/11.md with streaming specification
git add buds/11.md
git commit -m "Add BUD-11: Streaming Support

- Define streaming endpoints for direct blob streaming
- Add HLS playlist generation from blobs  
- Include media info endpoint for metadata
- Enable integration with standard video players"
```

### Step 4: Test Your Changes

Before submitting, test the proposals:

1. **Implementation Testing**: Verify the BitTorrent Gateway works with the new tags
2. **Compatibility Testing**: Ensure existing clients aren't broken  
3. **Documentation Review**: Check all examples and references

```bash
# In BitTorrent Gateway repository
go build -o gateway ./cmd/gateway
./gateway # Test with new NIP-35 tags
```

### Step 5: Submit Pull Requests

#### NIP-35 Pull Request

```bash
cd nips
git push origin nip-35-streaming-extensions
```

**PR Title**: `NIP-35: Add streaming extensions for video/audio content`

**PR Description**:
```markdown
## Summary

This PR extends NIP-35 to support streaming media by adding optional tags for direct streaming and HLS delivery.

## Motivation

Current NIP-35 only supports basic torrent metadata. With the growth of video/audio content on Nostr, there's a need for streaming-specific metadata that enables:

- Direct video streaming in clients
- HLS playlist discovery  
- Media player integration
- Social features around streaming content

## Changes

- Added `stream` tag for direct streaming URLs
- Added `hls` tag for HLS playlist URLs
- Added `duration` tag for time-based media
- Added `video` tag for resolution/codec metadata
- Added `m` tag for MIME type (consistent with NIP-94)
- Updated example to demonstrate streaming extensions

## Implementation

This extension is already implemented in the BitTorrent Gateway project:
https://github.com/YOUR_USERNAME/torrentGateway

## Backward Compatibility

All new tags are optional. Existing NIP-35 implementations continue to work unchanged.
```

#### BUD-11 Pull Request  

```bash
cd blossom
git push origin bud-11-streaming-support
```

**PR Title**: `BUD-11: Add streaming support for media blobs`

**PR Description**:
```markdown  
## Summary

This BUD defines streaming endpoints that enable Blossom servers to serve video/audio content directly with support for HTTP range requests and HLS streaming.

## Motivation

Blossom is increasingly used for media storage, but lacks streaming capability. This BUD enables:

- Direct blob streaming without separate infrastructure
- HLS support for adaptive streaming
- Better user experience for video/audio content  
- Integration with standard video players

## Specification

- `GET /<hash>/stream` - Direct streaming with range support
- `GET /<hash>/playlist.m3u8` - HLS playlist generation
- `GET /<hash>/segment/<n>` - HLS segment delivery  
- `GET /<hash>/info` - Media metadata endpoint

## Implementation

Reference implementation available in:
https://github.com/YOUR_USERNAME/torrentGateway

The implementation demonstrates practical usage and performance characteristics.
```

### Step 6: Follow Up and Iterate

1. **Respond to Feedback**: Address reviewer comments promptly
2. **Update Implementation**: Make changes based on specification feedback
3. **Community Engagement**: Participate in discussions and decisions
4. **Documentation**: Update your implementation as specs evolve

## 🤝 Community Engagement Tips

### For NIP-35 (Nostr Protocol)

- **Join Nostr Development**: Follow discussions on nostr-protocol GitHub
- **Test with Clients**: Verify compatibility with major Nostr clients
- **Use Cases**: Provide compelling examples of streaming use cases
- **Performance Data**: Share performance metrics from your implementation

### For Blossom BUD-11

- **Implementation First**: Having working code makes proposals stronger  
- **Server Compatibility**: Test with existing Blossom server implementations
- **Client Integration**: Show how existing clients benefit
- **Resource Usage**: Document server resource requirements

## 📊 Success Metrics

Your proposals will be considered successful if they achieve:

1. **Technical Merit**: Solve real problems elegantly
2. **Backward Compatibility**: Don't break existing implementations
3. **Implementation Proof**: Working code demonstrates feasibility  
4. **Community Support**: Other developers express interest
5. **Clear Specification**: Unambiguous implementation guidance

## 🔗 Useful Resources

### NIP-35 Resources
- [NIP-35 Current Specification](https://github.com/nostr-protocol/nips/blob/master/35.md)
- [Nostr Implementation Possibilities](https://github.com/nostr-protocol/nips)
- [NIP-35 Pull Request #1175](https://github.com/nostr-protocol/nips/pull/1175)

### Blossom Resources  
- [Blossom Protocol](https://github.com/hzrd149/blossom)
- [Existing BUDs](https://github.com/hzrd149/blossom/tree/master/buds)
- [Reference Server Implementation](https://github.com/hzrd149/blossom-server)

### Standards Writing
- [RFC 2119: Key words for RFCs](https://tools.ietf.org/html/rfc2119)  
- [RFC 8216: HTTP Live Streaming](https://tools.ietf.org/html/rfc8216)
- [RFC 7233: Range Requests](https://tools.ietf.org/html/rfc7233)

---

## 🚀 Ready to Submit?

With these proposals, you'll be pioneering the standardization of decentralized streaming protocols. The BitTorrent Gateway's innovative approach deserves to become the foundation for next-generation content distribution.

**Remember**: Standards are adopted through implementation and usage. Your working code is the most compelling argument for adoption!

Good luck with your standards proposals! 🎉