Ripple
Download and stream torrents in your browser. Ripple runs a real BitTorrent engine (libtorrent, compiled to WebAssembly) in the page, reaches peers through the FKN relay, and plays a video while it downloads. There is nothing to install and no Ripple server.
- Live at torrent.fkn.app, and inside FKN at fkn.app/app/npm:@banou/ripple
- Published on npm as
@banou/ripple
Features
- Add a magnet or a
.torrent. Paste it, drop it, or open it from your system once Ripple is installed as an app, which then opensmagnet:links and.torrentfiles. - Watch while it downloads, with subtitles, a choice of audio track and a Normalize volume switch.
- Pick the files you want before the download starts.
- Keep files in the browser or in a folder on your disk, and save one file, or a zip of several.
- Create a torrent from files or a folder (v1, v2 or hybrid, private with a source tag, web seeds) and seed it straight from those files.
- Your library on every device. Signed in to FKN, your list and its thumbnails sync, encrypted in your browser before they leave it.
- Share links that open the player or a download page, which other sites can embed.
- One engine for all your tabs. One tab runs it and the others use it.
- Speed limits for everything or per torrent, and the peers, trackers, files and all-time share ratio of each torrent.
- No Ripple account and no analytics.
How it is built
- UI: React 19, routed with React Router 7 and styled with Emotion, in
src/routerandsrc/components. - Engine:
libtorrent-wasmin a Web Worker (src/torrent/worker.ts), driven from the page bysrc/torrent/client.ts. One tab holds it under a Web Lock and the others reach it over a BroadcastChannel (engine-election.ts,engine-share.ts). - Network:
@fkn/lib/netand@fkn/lib/dgram, carried through the FKN relay (relayWorkerbridges the worker). Inbound peers reach a port the relay reserves. - Storage: OPFS, or a folder you grant (
src/torrent/hybrid-storage.ts). The list, resume data and thumbnails are in IndexedDB. - Player:
@banou/media-playerat/watch(src/router/embed.tsx), with libav-wasm and jassub. - Sync:
src/torrent/use-cloud-backup.tsandsrc/torrent/thumbnail-sync.ts, underripple/in the FKN account's storage.
Development
Use Node 24 (.node-version names 24.21.0).
npm ci
npm run dev # http://localhost:4560
npm run build # the site and the npm package, into build/
npm test # unit tests (vitest, node)
npm run test:browser # component tests in Chrome
npm run typecheck
npm run lint # vp lint
The Playwright suites build first, then drive the built site in Chrome:
| command | what it covers |
|---|---|
npm run test:e2e:local | the app, needing nothing but the browser (and ffmpeg) |
npm run test:e2e:machine | live figures keep their width, which depends on the machine's fonts |
npm run test:e2e:swarm | the engine against real public swarms |
npm run test:e2e:rig | the whole chain against a local swarm, see tests/swarm-rig |
The swarm and rig suites need a headful Chrome, because headless Chromium stalls the engine at
0 B/s. Run them under xvfb-run -a -s "-screen 0 1280x720x24" so no window opens.
A push to main deploys torrent.fkn.app (Cloudflare Pages). When Test
passes on that commit and package.json names a version the registry does not have yet, it is also
published to npm (.github/workflows/publish-lib.yml). Each published version is signed for FKN
with fkn-sign.
Embedding
/watch and /download are the pages another site puts in an iframe. Both take a magnet and the
same query; the path chooses which one renders. /watch plays a file, /download delivers files.
| param | value | meaning |
|---|---|---|
magnet | base64 of the magnet URI | the form to write; permanent |
m | the packed magnet, base64url | what Ripple's own share links write |
fileIndex | a file index | the file /watch plays (the largest video if absent); the fallback /download uses |
files | all, 3, 0-4, 0,2,5 | what /download delivers |
language | a BCP 47 tag, such as fr or es-MX | the language of the page and of the player's controls, ahead of the one picked in Ripple (if absent, unreadable, or one they have no text in: the one picked, else the first of the browser's languages they have text in) |
audio | a BCP 47 tag, or original | the audio language /watch starts in, ahead of the one last picked in it (original: the file's own) |
subtitles | a BCP 47 tag, or off | the subtitle language it starts in, the same way |
alwaysSubtitles | 1 or 0 | 0 starts subtitles off when the audio plays in their language |
Each audio or subtitle language picked in the player is posted to the framing window as
{ ripple: 'picked', audio }, { ripple: 'picked', subtitles } (null for off) or
{ ripple: 'picked', alwaysSubtitles: true }, for the page to start its next media in it.
One of magnet or m is required, and m is read first when both are present. magnet= is the
original form and every link written with it keeps working. m= is the same torrent packed into a
much shorter link.
/watch?magnet=<base64>&fileIndex=3 plays file 3
/download?magnet=<base64> the whole torrent
/download?magnet=<base64>&files=3 just file 3
/download?magnet=<base64>&files=0-4 files 0 to 4 inclusive, as a zip
/download?magnet=<base64>&files=0,2,5 those three, as a zip
/download?magnet=<base64>&fileIndex=3 same as files=3
One file is delivered as that file, and more than one as a single .zip. files outranks
fileIndex. Indices the torrent does not have are dropped, and a selection that resolves to
nothing says so instead of downloading the whole torrent.
A sandboxed frame needs allow-downloads, or the browser drops the download without an error.
Leaving out sandbox works too.
<iframe src="https://torrent.fkn.app/download?magnet=..."
sandbox="allow-scripts allow-same-origin allow-downloads"></iframe>
Why each part works the way it does is in docs/embedding.md.
Privacy
Ripple needs no account and runs no analytics. Your list and your files stay in your browser, or in
a folder you choose. Signed in to FKN, your list and its thumbnails sync to your FKN account,
encrypted in your browser first. Peers see the FKN relay's address, not yours. The
privacy page lists what Ripple keeps
(src/router/privacy.tsx).
License
MIT, see LICENSE.