WebTorrent

Frequently Asked Questions

What is WebTorrent?

WebTorrent is the first torrent client that works in the browser. YEP, THAT'S RIGHT. THE BROWSER.

It's written completely in JavaScript – the language of the web – and uses WebRTC for true peer-to-peer transport. No browser plugin, extension, or installation is required.

Using open web standards, WebTorrent connects website users together to form a distributed, decentralized browser-to-browser network for efficient file transfer.

Why is this cool?

Imagine a video site like YouTube, where visitors help to host the site's content. The more people that use a WebTorrent-powered website, the faster and more resilient it becomes.

Browser-to-browser communication cuts out the middle-man and lets people communicate on their own terms. No more client/server – just a network of peers, all equal. WebTorrent is the first step in the journey to redecentralize the Web.

The way we code the Web will determine the way we live online. So we need to bake our values into our code. Freedom of expression needs to be baked into our code. Privacy should be baked into our code. Universal access to all knowledge. But right now, those values are not embedded in the Web.

— Brewster Kahle, Founder of the Internet Archive (from Locking the Web Open)

What are some use cases for WebTorrent?

One of the most exciting uses for WebTorrent is peer-assisted delivery. Non-profit projects like Wikipedia and the Internet Archive could reduce bandwidth and hosting costs by letting visitors chip in. Popular content is served browser-to-browser, quickly and cheaply. Rarely-accessed content is served reliably over HTTP from the origin server.

There are also exciting business use cases, from CDNs to app delivery.

WebTorrent has significant business potential to radically change the traditional notion of client-server, with applications for internal infrastructure and external closed user communications. WebTorrent has moved from an “idea” to a science experiment to now on the edge of being viable. This is like really, seriously cool.

— Chris Kranky (from "WebTorrent: Rethinking Delivery")

Who is using WebTorrent today?

WebTorrent is still pretty new, but it's already being used in cool ways:

How does WebTorrent work?

The WebTorrent protocol works just like BitTorrent protocol, except it uses WebRTC instead of TCP/uTP as the transport protocol.

In order to support WebRTC's connection model, we made a few changes to the tracker protocol. Therefore, a browser-based WebTorrent client or "web peer" can only connect to other clients that support WebTorrent/WebRTC.

The protocol changes we made will be published as a BEP. Until a spec is written, you can view the source code of the bittorrent-tracker package.

Once peers are connected, the wire protocol used to communicate is exactly the same as in normal BitTorrent. This should make it easy for existing popular torrent clients like Transmission, and uTorrent to add support for WebTorrent. Vuze already has support for WebTorrent!

WebTorrent network diagram

How do I get started?

To start using WebTorrent, simply include the webtorrent.min.js script on your page. If you use browserify, you can npm install webtorrent and require('webtorrent').

It's easy to download a torrent and add it to the page.

var client = new WebTorrent()

var torrentId = 'magnet:?xt=urn:btih:6a9759bffd5c0af65319979fb7832189f4f3c35d&dn=sintel.mp4&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&tr=wss%3A%2F%2Ftracker.webtorrent.io&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel-1024-surround.mp4'

client.add(torrentId, function (torrent) {
  var file = torrent.files[0]
  file.appendTo('body') // append the file to the DOM
})

This supports video, audio, images, PDFs, Markdown, and more, right out of the box. There are additional ways to access file content directly, including as a node-style stream, Buffer, or Blob URL.

Video and audio content can be streamed, i.e. playback will start before the full file is downloaded. Seeking works too – WebTorrent dynamically fetches the needed torrent pieces from the network on-demand.

What is WebRTC?

WebRTC (Web Real-Time Communication) is an API defined by the World Wide Web Consortium (W3C) to support browser-to-browser applications like voice calling, video chat, and P2P file sharing without the need for browser plugins.

WebRTC's RTCDataChannel API allows the transfer of data directly from one browser to another. This is distinct from WebSocket and XMLHttpRequest because these are designed for communication to/from a server, i.e. a client-server model. Data Channels allow for direct browser-to-browser connections.

This is revolutionary. Never before could websites connect their users directly to each other with super low-latency, encrypted, peer-to-peer connections. This will enable next-generation applications in healthcare, education, science, and more. WebTorrent is just one example.

WebRTC works everywhere, and browser support is excellent. Chrome, Firefox, and Opera for Desktop and Android, as well as Microsoft Edge have support.

You can learn more about WebRTC data channels at HTML5Rocks.

Can WebTorrent clients connect to normal BitTorrent clients?

In the browser, WebTorrent can only download torrents that are seeded by a WebRTC-capable torrent client.

Right now, we know of these WebRTC-capable torrent clients:

A bit more about webtorrent-hybrid

In node.js, webtorrent-hybrid can download torrents from WebRTC peers or TCP peers (i.e. normal peers). You can use WebTorrent as a command line program, or programmatically as a node.js package.

To install webtorrent-hybrid run the following command in your terminal (add the -g flag to install the command line program, omit it to install locally):

npm install webtorrent-hybrid -g

Note: If you just need to use WebTorrent in the browser (where WebRTC is available natively) then use webtorrent instead, which is faster to install because it won't need to install a WebRTC implementation.

Can WebTorrent clients on different websites connect to each other?

Yes! WebTorrent works across the entire web. WebTorrent clients running on one domain can connect to clients on any other domain. No silos!

The same-origin policy does not apply to WebRTC connections since they are not client-to-server. Browser-to-browser connections require the cooperation of both websites (i.e. the WebTorrent script must be present on both sites).

Who builds WebTorrent?

WebTorrent is built by Feross Aboukhadijeh and hundreds of open source contributors.

Feross's other projects include JavaScript Standard Style, PeerCDN (sold to Yahoo), Study Notes, and YouTube Instant.

In the past, Feross attended Stanford University, did research in the Stanford Human-Computer Interaction and Computer Security labs, and worked at Quora, Facebook, and Intel.

How is WebTorrent different from PeerCDN?

PeerCDN is a next-generation CDN powered by WebRTC for efficient peer-to-peer delivery of website content. PeerCDN was founded by Feross Aboukhadijeh, Abi Raja, and John Hiesey in March 2013 and was sold to Yahoo in December 2013.

WebTorrent is an independent project started by Feross Aboukhadijeh in October 2013. Unlike PeerCDN, WebTorrent is free software, licensed under the MIT License. You're free to use it however you like!

"Free software" is a matter of liberty, not price. To understand the concept, you should think of "free" as in "free speech," not as in "free beer."

— Richard Stallman, software freedom activist

On a technical level, PeerCDN and WebTorrent were built with different goals in mind. PeerCDN was optimized for low-latency downloads and fast peer discovery. This meant the client and site owner trusted centralized servers to map file URLs to content hashes.

WebTorrent, on the other hand, doesn't require clients to trust a centralized server. Given a .torrent file or magnet link, the WebTorrent client downloads the file without trusting servers or peers at any point.

How can I contribute?

WebTorrent is an OPEN Open Source Project. Individuals who make significant and valuable contributions are given commit access to the project to contribute as they see fit. (See the full contributor guidelines.)

There are many ways to help out!

If you're looking for help getting started, come join us in Gitter or on IRC at #webtorrent (freenode) and how you can get started.

Where can I learn more?

There are many talks online about WebTorrent. Here are a few:

Intro to BitTorrent and WebTorrent (JSConf)

WebRTC Everywhere: Beyond the Browser (slides only)

Troubleshooting

Why does browser downloading not work? I see no peers!

It does work! But you can't just use any random magnet uri or .torrent file. The torrent must be seeded by a WebRTC-capable client, i.e. WebTorrent Desktop, Vuze, webtorrent-hybrid, Playback, instant.io, or βTorrent.

In the browser, WebTorrent can only download torrents that are explicitly seeded to web peers via a WebRTC-capable client. Desktop torrent clients need to support WebRTC to connect to web browsers.

Why does video/audio streaming not work?

Streaming support depends on support for MediaSource API in the browser. All modern browsers have MediaSource support. In Firefox, support was added in Firefox 42 (i.e. Firefox Nightly).

Many file types are supported (again, depending on browser support), but only .mp4, .m4v, and .m4a have full support, including seeking.

To support video/audio streaming of arbitrary files, WebTorrent uses the videostream package, which in turn uses mp4box.js. If you think there may be a bug in one of these packages, please file an issue on the respective repository.

Got more questions?

Open an issue on the WebTorrent issue tracker, or join us in Gitter or on IRC at #webtorrent (freenode).