Decentralized Media Distribution via Git LFS + WebTorrent

[ProjectLiminality]

Vision

Enable InterBrain to host and distribute large media files (videos, podcasts) via WebTorrent, creating truly censorship-resistant content propagation that scales with community seeding rather than centralized bandwidth costs.

Content travels with context. Unlike platforms that share isolated files, InterBrain shares entire Git repositories — the video, its source files, assets, and the DreamSong website that presents it. Large media is seamlessly integrated via Git LFS pointers, streamed via WebTorrent from your liminal web peers.

Problem

• Git can't handle large media files efficiently
• Centralized hosting (YouTube, etc.) is subject to censorship
• Current InterBrain has no solution for large media in DreamNodes
• Creators depend on platforms that can demonetize or remove content

Solution

Use Git LFS for lightweight pointers in Git, and WebTorrent for decentralized streaming and distribution:

Git repo (via Radicle)
├── video.mp4          ← Git LFS pointer (tiny, contains hash)
├── source/            ← Project files
├── assets/            ← Images, audio
└── dreamsong/
    └── index.html     ← WebTorrent-powered player

When you play video.mp4:
  Pointer (sha256 hash) → WebTorrent → Stream from liminal web peers

Key insight: Git LFS provides the pointer system; WebTorrent replaces the centralized resolver with peer-to-peer streaming. The same player works in InterBrain and on GitHub Pages.

How It Works

For Creators

1. Add large media to your DreamNode (Git LFS handles the pointer automatically)
2. InterBrain generates torrent metadata (magnetUri, infoHash) from the file hash
3. Push to Radicle — peers in your liminal web can now discover and stream it
4. Optionally publish to GitHub Pages — the same WebTorrent player works for anyone

For Viewers

1. Clone/sync the repo via Radicle (fast — large files are just pointers)
2. Open the DreamSong in InterBrain
3. Click play — video streams via WebTorrent from peers who have it
4. As you watch, the file downloads locally
5. Once complete, you automatically seed to others in the network

On GitHub Pages

1. Visitor opens the published static site
2. WebTorrent player streams from the peer swarm (works in browser!)
3. The visitor's browser becomes a temporary seeder while watching
4. More viewers = faster streaming for everyone

Architecture

Storage States

interface MediaStorageState {
  // From Git LFS pointer
  oid: string;              // sha256 hash (content address)
  size: number;
  
  // For WebTorrent distribution  
  magnetUri?: string;       // Magnet link for streaming
  infoHash?: string;        // BitTorrent info hash
  
  localState:
    | "pointer-only"        // Just the reference, no local copy
    | "streaming"           // Currently downloading/watching
    | "cached"              // Downloaded, seeding while app open
    | "pinned";             // Always seed, survives app restart
}

Peer Discovery

Peers are discovered through your existing liminal web — the trust graph you've already built via Radicle. No separate peer discovery system needed.

User Actions on Media

• ▶ Play → Stream via WebTorrent, auto-seed while watching
• 📌 Pin → Keep seeding permanently (dedicated storage)
• 💾 Keep offline → Download fully, seed when online
• 🗑 Free space → Remove local copy, still available from other peers

User Stories

1. As a creator, I can add a 2-hour video to my DreamNode and share it with my liminal web without relying on YouTube
2. As a viewer, I can stream large media instantly without downloading the full file first
3. As a supporter, watching content automatically helps distribute it — my bandwidth contributes to the creator
4. As a web visitor, I can watch videos on a GitHub Pages site that streams from the peer network

Acceptance Criteria

• Git LFS configured for media file types (.mp4, .webm, .mov, etc.)
• Torrent metadata generation from Git LFS pointers (magnetUri, infoHash)
• webtorrent-media feature slice with stream/seed/pin operations
• MediaPlayer component resolves LFS pointers to WebTorrent streams
• Stream media in DreamTalk/DreamSong views
• Peer discovery via Radicle liminal web connections
• GitHub Pages bundle includes WebTorrent player
• Storage management: pin/unpin, automatic cleanup policies
• Seeding status indicators in UI

Technical Approach

Stack

• Git LFS — Pointer files in Git (already works with GitHub)
• WebTorrent — Streaming torrent client for browser and Node.js
• Radicle — Peer discovery via existing liminal web

Key Components

1. Media preparation — Generate torrent metadata when adding large files
2. Universal player — Single component works in Electron + browser
3. Peer bridge — Connect Radicle peer IDs to WebTorrent webSeeds
4. Storage manager — Policies for what to keep, seed, or drop

Why This Stack

• Git LFS keeps large files out of Git history with simple pointers
• WebTorrent enables streaming (not just downloading) and works in browsers
• Radicle already provides peer discovery — no need for separate DHT or tracker
• GitHub Pages compatibility preserved — same player works everywhere

Cost Model

Scenario	Cost	How It Works
Liminal web seeding	$0	Your peers seed content they've watched
GitHub Pages + WebTorrent	$0	Visitors stream from peer network
Creator self-hosting	$0	Your machine seeds while online

Community becomes infrastructure. The more people watch, the more bandwidth is available.

Out of Scope (Future)

• Automatic transcoding/optimization
• YouTube import/mirroring
• Paid seeding services
• Mobile app streaming (requires WebRTC support investigation)

Related

• Progressive media loading with Obsidian-native file streaming #351 - Progressive media loading
• Radicle peer sync (existing infrastructure)
• Git LFS (existing infrastructure)