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

## 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 //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 //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, /segment/0 #EXTINF:6.000, /segment/1 #EXT-X-ENDLIST

### HLS Segment Endpoint

GET //segment/

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

### Media Info Endpoint

GET //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

# 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

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

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

# 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

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

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

PR Description:

## 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

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

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

PR Description:

## 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
• Nostr Implementation Possibilities
• NIP-35 Pull Request #1175

Blossom Resources

• Blossom Protocol
• Existing BUDs
• Reference Server Implementation

Standards Writing

• RFC 2119: Key words for RFCs
• RFC 8216: HTTP Live Streaming
• RFC 7233: Range Requests

---

🚀 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! 🎉