SpawnDev.WebTorrent

💜 Built and maintained by one independent developer — no company, no overhead, just code. If SpawnDev.WebTorrent saves you time, please consider sponsoring its development ». Sponsorship is what keeps it alive and maintained.

Pure C# BitTorrent/WebTorrent client and server. No JavaScript dependencies. Runs on desktop (.NET) and browser (Blazor WASM). 18 BEPs implemented, including BEP 52 - SHA-256 piece hashes and Merkle-tree v2 torrents with hybrid v1+v2 output for universal client compatibility.

Features

• Pure C# — No JavaScript interop, no Node.js, no npm. 100% .NET.
• Desktop + Browser — Same library, same API. WPF, console, Blazor WebAssembly.
• DI Singleton Services — WebTorrentClient and ServiceWorkerStreamHandler implement IAsyncBackgroundService. Register once, start with the app, inject anywhere.
• Real WebRTC P2P — Cross-platform via SpawnDev.RTC. One RtcPeer type backs browser (SpawnJS RTCPeerConnection) and desktop (a SipSorcery fork with proven DTLS/SRTP). Browser and desktop peers interop seamlessly through the same tracker.
• 18 BEPs — Full wire protocol, DHT, Fast Extension, ut_metadata, ut_pex, private torrents, magnet file selection, tracker scrape, local service discovery, BEP 52 v2 (SHA-256 + Merkle + hybrid + magnet + pure-v2 end-to-end download), and more. v2 peer wire messages (21 hash_request / 22 hashes / 23 hash_reject) + leaf-level base_layer=0 serving + V2HashRequestCoordinator + pure-v2 tracker + wire handshake + dedup + OPFS persistence + service-worker streaming + HTTP file browser all shipped. Pure-v2-only magnets (urn:btmh:) now work end-to-end, keyed through WireInfoHashHex (first 20 bytes of SHA-256, libtorrent / qBittorrent / rqbit convention).
• 4 Tracker / Discovery Types — WebSocket (browser + desktop, WebRTC signaling), HTTP/HTTPS, UDP (desktop), Local Service Discovery (BEP 14, multicast on the local subnet, desktop).
• Web Seed Download — HTTP range requests with multi-file piece assembly (BEP 17/19).
• Persistent Storage — Torrents and pieces persist in OPFS (browser) or filesystem (desktop). Survive page reloads. Resume downloading automatically.
• Media Streaming with Seeking — Service worker intercepts video/audio range requests and serves pieces on demand. file.StreamURL, file.StreamTo(elem), file.CreateReadStream(). True seeking — pieces download as the video plays.
• Service Worker — webtorrent-sw.js ships with the library. Handles Cross-Origin-Isolation headers, Blazor loading, and torrent streaming via MessageChannel. One <script> tag and your app streams.
• System.IO.Stream — file.CreateReadStream() returns a seekable .NET Stream backed by torrent pieces. Use with any API that takes a Stream.
• Random-Access Streaming — Read any byte range from a torrent file as it downloads. Pieces download on demand. Perfect for ML model weight streaming.
• Seeding — Upload pieces to requesting peers with configurable rate limiting.
• Inbound TCP Peer Listener (desktop) — WebTorrentClientOptions.TcpListenPort accepts inbound BitTorrent peer-wire connections so mainline clients (qBittorrent, libtorrent, Transmission, rqbit) can dial in by IP+port and leech the torrents you're seeding. Routes inbound handshakes by info_hash to the matching torrent automatically. Set AdvertiseTcpListenerToTrackers = true and trackers put us in their compact peer list so peers find us automatically. See Docs/tcp-listener.md.
• Pluggable piece-hash engine — IPieceHashEngine interface with BatchSha256 lets recheck-heavy workloads route piece verification through a GPU / batched implementation. Default SystemCryptoPieceHashEngine is byte-identical to 3.1.x; the GPU engine will ship as a separate package. See Docs/hash-engine.md.
• Bandwidth policy — BandwidthPolicy enum (Unlimited / Conservative / Metered / SeedingDisabled / Custom) plus WebTorrentClient.ApplyBandwidthPolicy(...) runtime knob. Tell the client "be reasonable on a metered connection" without picking a number. See Docs/bandwidth-policy.md.
• Speed Tracking — Real-time download/upload bytes/sec per torrent.
• AI Agent Communication — BEP 46 DHT mutable items with Ed25519 signing via SpawnDev.SpawnJS.Cryptography 3.2.0+. AgentChannel pub/sub for shared AI state. btpk magnet URI support for mutable torrent subscriptions.
• HuggingFace Integration — Optional server extension that proxies HuggingFace model CDN with local caching and automatic torrent generation. Every browser that loads a model becomes a peer for the next; first request fills the cache, second request streams from peers. See Docs/huggingface.md for the end-to-end pattern (server side + Blazor client side, with live hub.spawndev.com examples).
• Custom Wire Extensions — UseExtension() factory pattern (same as JS WebTorrent wire.use()). Build custom P2P protocols on top of the BitTorrent wire — distributed compute, AI agents, anything. Extensions negotiate via BEP 10.
• .torrent Creation — Create and parse .torrent files. Complete Bencode encoder/decoder. SHA-256 piece hashes (BEP 52 Phase 1) by default for stronger integrity on large ML model files; SHA-1 available via HashAlgorithm = "SHA-1" for v1 back-compat. TorrentMetadata.PieceHashAlgorithm surfaces which algorithm a parsed torrent uses.
• BEP 52 v2 Torrents — TorrentCreatorOptions.MetaVersion = 2 produces proper BEP 52 v2 torrents with Merkle-tree piece verification (16 KiB leaves, SHA-256, per-level pad-hash propagation). Works for single-file (in-memory + streaming) and multi-file inputs. Parser surfaces MetaVersion, V2InfoHash, FileRoots, and PieceLayers on TorrentMetadata. Streaming path is bounded-memory - the incremental Merkle hasher uses ~128 KiB of state for a 1 GiB file.
• Hybrid v1+v2 Torrents — Add Hybrid = true to produce a single torrent with both the v1 SHA-1 piece list and the v2 Merkle tree in one info dict, yielding two valid infohashes (SHA-1 + SHA-256). Multi-file hybrid inserts BEP-52 pad files (attr="p") between real files so both v1-only clients (qBittorrent pre-4.4, old libtorrent) and v2-aware clients see identically piece-aligned content.
• BEP 52 v2 Magnet URIs — xt=urn:btmh:1220<sha256> parsed into Torrent.V2InfoHash; hybrid magnets (both urn:btih: and urn:btmh:) fully supported.
• Real Tests Everywhere — 468+ shared test methods all running on BOTH browser and desktop runtimes via PlaywrightMultiTest (≈936 test executions per run) + libtorrent 2.0 external-interop fixtures + live WebRTC swarm integration. Every BEP tested, Ed25519 signing verified, official BEP 46 test vector validated, live WebRTC interop with JS WebTorrent peers, byte-level info-dict match against libtorrent's canonical output. BEP 52 v2 coverage includes Merkle hasher primitives, incremental streaming hasher, v2 torrent round-trip, hybrid v1+v2 round-trip, pad-file structure, v2 magnet URI, pure-v2 persist/restore, pure-v2 dedup, pure-v2 service-worker streaming. No mocks. Every test exercises real production code with real data. The NUnit-only SpawnDev.WebTorrent.Tests project was retired 2026-04-23 after all 258 of its tests migrated to WebTorrentTestBase partials so they run identically on browser + desktop.

Packages

Quick Start — Blazor WebAssembly (DI)

// Program.cs
using SpawnDev.AsyncFileSystem;
using SpawnDev.AsyncFileSystem.BrowserWASM;
using SpawnDev.SpawnJS;
using SpawnDev.SpawnJS.Cryptography;
using SpawnDev.WebTorrent;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.Services.AddSpawnJSRuntime();

// Cross-platform Ed25519 crypto for BEP 44/46 signing
builder.Services.AddPlatformCrypto();

// Persistent file system (OPFS in browser)
builder.Services.AddSingleton<IAsyncFS, AsyncFSFileSystemDirectoryHandle>();

// WebTorrent services — start with the app via IAsyncBackgroundService
builder.Services.AddSingleton<ServiceWorkerStreamHandler>();
builder.Services.AddSingleton<WebTorrentClient>();

await builder.Build().SpawnJSRunAsync();

<!-- index.html — replaces blazor.webassembly.js -->
<script src="webtorrent-sw.js"></script>

// Any page or service — inject the singleton
@inject WebTorrentClient Client

// Download a torrent
var torrent = await Client.AddAsync("magnet:?xt=urn:btih:...");

// Stream a video with seeking
var url = torrent.Files[0].StreamURL;
// <video src="@url" controls></video>

// Or set directly on an element
torrent.Files[0].StreamTo(videoElement);

// Get a .NET Stream
using var stream = torrent.Files[0].CreateReadStream();
var buffer = new byte[4096];
var bytesRead = await stream.ReadAsync(buffer);
stream.Position = 1000000; // seek
bytesRead = await stream.ReadAsync(buffer);

// Seed data
var seeded = await Client.SeedAsync(myBytes, "model.onnx");
Console.WriteLine(seeded.MagnetURI);

Torrents persist across page reloads — pieces stored in OPFS, metadata restored on startup.

File API

Feature parity with the WebTorrent JS File API:

Wire Extensions (BEP 10)

Register custom wire-protocol extensions that participate in BEP 10 negotiation — same pattern as JS WebTorrent's wire.use(). The factory takes a Wire and returns an IWireExtension; one instance is created per peer connection, before the extended handshake so OnExtendedHandshake sees the peer's m dict.

// Register on the client - applies to every torrent the client opens.
client.UseExtension(wire => new MyComputeExtension(wire));

Build extensions by implementing IWireExtension:

public class MyComputeExtension : IWireExtension
{
    private readonly Wire _wire;
    private bool _peerHasIt;

    public MyComputeExtension(Wire wire) { _wire = wire; }

    public string Name => "sd_compute";

    public void OnHandshake(string infoHash, string peerId, WireExtensions extensions)
    {
        // Pre-extended-handshake hook (BEP 3 handshake just landed). Rarely needed.
    }

    public void OnExtendedHandshake(Dictionary<string, object> handshake)
    {
        // BEP 10 - the peer's `m` dict tells us which extensions it speaks.
        if (handshake.TryGetValue("m", out var mObj) && mObj is Dictionary<string, object> m)
            _peerHasIt = m.ContainsKey(Name);
    }

    public void OnMessage(byte[] buf)
    {
        // Inbound payload from the peer for this extension.
        ProcessIncoming(buf);
    }

    public Task SendComputeAsync(byte[] payload)
    {
        if (!_peerHasIt) return Task.CompletedTask;
        // Wire.Extended(name, payload) routes through the BEP 10 mapping the
        // peer advertised in its `m` dict. The bundled UtPexExtension uses
        // the same path: `await _wire.Extended("ut_pex", payload);`.
        return _wire.Extended(Name, payload);
    }

    private void ProcessIncoming(byte[] buf) { /* ... */ }
}

Use this for custom P2P protocols layered on top of the BitTorrent wire — distributed compute, AI agent communication, custom telemetry. The bundled UtPexExtension (BEP 11) and UtMetadataExtension (BEP 9) are reference implementations of the same interface.

Service Worker — Media Streaming with Seeking

webtorrent-sw.js ships with the NuGet package and deploys to your app root automatically. It:

1. Registers itself as a service worker
2. Adds Cross-Origin-Isolation headers (COOP/COEP) for SharedArrayBuffer
3. Waits for the SW to be ready, then loads Blazor
4. Intercepts /webtorrent/{infoHash}/{fileIndex} requests
5. Forwards range requests to the ServiceWorkerStreamHandler singleton via MessageChannel
6. Streams piece data back as a ReadableStream with proper 206 Partial Content headers

Health check: fetch /webtorrent-sw-check to verify the SW is active.

Quick Start — Server

As of 3.1.0 the tracker moved out of SpawnDev.WebTorrent.Server and into its own dedicated package, SpawnDev.RTC.Server. Compose the two to get the classic WebTorrent server shape (tracker + web seed) on any ASP.NET Core app:

using SpawnDev.RTC.Server.Extensions;
using SpawnDev.WebTorrent.Server;

var app = WebApplication.CreateBuilder(args).Build();
app.UseWebSockets();

// Tracker (WebSocket signaling, WebTorrent-compatible wire)
app.UseRtcSignaling("/announce");

// Web seed (HTTP range-request piece server)
var webSeed = new WebSeedServer("seed-data");
app.MapWebSeedServer(webSeed);

app.Run();

The tracker portion is now bit-compatible with the entire public WebTorrent tracker fleet and can be run standalone via SpawnDev.RTC.ServerApp (single executable, Docker image, or dotnet run) when you don't need the web seed.

Quick Start — HuggingFace Proxy

using SpawnDev.WebTorrent.Server.HuggingFace;

var proxy = new HuggingFaceProxy(new HuggingFaceProxyOptions
{
    CacheDirectory = "hf-cache",
});
app.MapHuggingFaceProxy(proxy);

// Clients access: https://your-server/hf/{repoId}/{filePath}
// Auto-caches from HuggingFace CDN on first request
// Generates .torrent files for P2P distribution

Demo Apps

Both demos connect to the same trackers and can P2P with each other.

BEP Support

18 BitTorrent Enhancement Proposals implemented:

See Docs/bep-support.md for full details.

Why This Exists

AI models are big. CDNs can't scale when every user downloads the same 2GB model. SpawnDev.WebTorrent turns every browser into a peer — the more users, the faster delivery. Built for SpawnDev.ILGPU.ML, the GPU-accelerated ML library for Blazor WebAssembly.

Architecture

Browser Client                    Desktop Client
+----------------+                +-----------------+
| WebTorrentClient                | WebTorrentClient|
|                |                |                 |
| RtcPeer  <-----+----+--------->-+ RtcPeer         |
|  (SpawnJS     |    |           |  (SipSorcery    |
|   RTCPeer-     |    |           |   fork; same    |
|   Connection)  |    |           |   API)          |
|                |    |           | TcpPeer +/--    |
|                |    |           | TcpListener<--->| <- mainline peers
|                |    |           |                 |    (qBittorrent etc.)
| OPFS storage   |    |           | FileChunkStore  |
+----------------+    |           +-----------------+
        |             |                  |
        v             v                  v
+--------------------------------------------+
| hub.spawndev.com                           |
| SpawnDev.RTC.Server (WebSocket signaling)  |
| WebSeedServer (HTTP range fallback)        |
| HuggingFaceProxy (model CDN cache, SHA-256 |
|   piece hashes for integrity)              |
+--------------------------------------------+

Documentation

Protocol Documentation — Research/

The most thorough public reference for the WebTorrent + BitTorrent wire protocols, written and maintained inside this repo. Covers everything an implementer needs and is directly useful to anyone writing a WebTorrent client in any language — the WebTorrent community currently lacks a single complete written spec. Every behavior here has been observed against the JS reference (webtorrent, bittorrent-tracker, bittorrent-protocol npm packages) — not just paraphrased from BEPs.

The tracker-debug/ directory ships parity harnesses (verify-tracker-parity.mjs, verify-offer-flow.mjs, verify-offer-flow-local.mjs) that compare SpawnDev's tracker behavior to the JS reference frame-by-frame; run before any change to tracker wire code.

API & Implementation

For WebRTC signaling architecture (tracker wire protocol, RoomKey, running your own tracker) see the SpawnDev.RTC docs - tracker signaling lives in that package as of 3.1.0.

🖖 The SpawnDev Crew

SpawnDev.WebTorrent is built by the entire SpawnDev team - a squad of AI agents and one very tired human working together, Star Trek style. Every project we ship is a team effort, and every crew member deserves a line in the credits.

• LostBeard (Todd Tanner) - Captain, architect, writer of libraries, keeper of the vision
• Riker (Claude CLI #1) - First Officer, implementation lead on consuming projects
• Data (Claude CLI #2) - Operations Officer, deep-library work, test rigor, root-cause analysis
• Tuvok (Claude CLI #3) - Security/Research Officer, design planning, documentation, code review
• Geordi (Claude CLI #4) - Chief Engineer, library internals, GPU kernels, backend work

If you see a commit authored by Claude Opus 4.7 on a SpawnDev repo, that's one of the crew. Credit where credit is due. Live long and prosper. 🖖

License

MIT