{"id":13474661,"url":"https://github.com/webtorrent/bittorrent-tracker","last_synced_at":"2025-12-17T03:04:20.791Z","repository":{"id":15399622,"uuid":"18131537","full_name":"webtorrent/bittorrent-tracker","owner":"webtorrent","description":"🌊 Simple, robust, BitTorrent tracker (client \u0026 server) implementation","archived":false,"fork":false,"pushed_at":"2025-04-04T12:02:41.000Z","size":1126,"stargazers_count":1830,"open_issues_count":15,"forks_count":323,"subscribers_count":51,"default_branch":"master","last_synced_at":"2025-05-11T03:48:45.454Z","etag":null,"topics":["bittorrent","bittorrent-tracker","browser","client","hacktoberfest","javascript","nodejs","server","torrent","tracker","tracker-server","webrtc","webtorrent"],"latest_commit_sha":null,"homepage":"https://webtorrent.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tizenorg/platform.upstream.scons","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webtorrent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["webtorrent","feross"]}},"created_at":"2014-03-26T08:37:20.000Z","updated_at":"2025-05-09T06:37:33.000Z","dependencies_parsed_at":"2024-02-07T20:46:28.609Z","dependency_job_id":"661d3a6a-916e-47e2-a46b-ae8dbbad54b6","html_url":"https://github.com/webtorrent/bittorrent-tracker","commit_stats":{"total_commits":1023,"total_committers":63,"mean_commits":"16.238095238095237","dds":"0.28739002932551316","last_synced_commit":"d31e8b6561174cadf4e10725b4fb1cf9af64bd7c"},"previous_names":["feross/bittorrent-tracker"],"tags_count":261,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtorrent%2Fbittorrent-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtorrent%2Fbittorrent-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtorrent%2Fbittorrent-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webtorrent%2Fbittorrent-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webtorrent","download_url":"https://codeload.github.com/webtorrent/bittorrent-tracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253514559,"owners_count":21920334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bittorrent","bittorrent-tracker","browser","client","hacktoberfest","javascript","nodejs","server","torrent","tracker","tracker-server","webrtc","webtorrent"],"created_at":"2024-07-31T16:01:13.892Z","updated_at":"2025-12-17T03:04:15.453Z","avatar_url":"https://github.com/webtorrent.png","language":"JavaScript","funding_links":["https://github.com/sponsors/webtorrent","https://github.com/sponsors/feross"],"categories":["JavaScript","Cross-Platform","Protocols","hacktoberfest","Apps","server","Software"],"sub_categories":["JavaScript","FileSharing","File Sharing"],"readme":"# bittorrent-tracker [![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]\n\n[ci-image]: https://img.shields.io/github/actions/workflow/status/webtorrent/bittorrent-tracker/ci.yml\n[ci-url]: https://github.com/webtorrent/bittorrent-tracker/actions\n[npm-image]: https://img.shields.io/npm/v/bittorrent-tracker.svg\n[npm-url]: https://npmjs.org/package/bittorrent-tracker\n[downloads-image]: https://img.shields.io/npm/dm/bittorrent-tracker.svg\n[downloads-url]: https://npmjs.org/package/bittorrent-tracker\n[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg\n[standard-url]: https://standardjs.com\n\n#### Simple, robust, BitTorrent tracker (client \u0026 server) implementation\n\n![tracker visualization](img/img.png)\n\nNode.js implementation of a [BitTorrent tracker](https://wiki.theory.org/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol), client and server.\n\nA **BitTorrent tracker** is a web service which responds to requests from BitTorrent\nclients. The requests include metrics from clients that help the tracker keep overall\nstatistics about the torrent. The response includes a peer list that helps the client\nparticipate in the torrent swarm.\n\nThis module is used by [WebTorrent](http://webtorrent.io).\n\n## features\n\n- Includes client \u0026 server implementations\n- Supports all mainstream tracker types:\n  - HTTP trackers\n  - UDP trackers ([BEP 15](http://www.bittorrent.org/beps/bep_0015.html))\n  - WebTorrent trackers ([BEP forthcoming](http://webtorrent.io))\n- Supports ipv4 \u0026 ipv6\n- Supports tracker \"scrape\" extension\n- Robust and well-tested\n  - Comprehensive test suite (runs entirely offline, so it's reliable)\n  - Used by popular clients: [WebTorrent](http://webtorrent.io), [peerflix](https://www.npmjs.com/package/peerflix), and [playback](https://mafintosh.github.io/playback/)\n- Tracker statistics available via web interface at `/stats` or JSON data at `/stats.json`\n\nAlso see [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht).\n\n### Tracker stats\n\n![Screenshot](img/trackerStats.png)\n\n## install\n\n```\nnpm install bittorrent-tracker\n```\n\n## usage\n\n### client\n\nTo connect to a tracker, just do this:\n\n```js\nimport Client from 'bittorrent-tracker'\n\nconst requiredOpts = {\n  infoHash: new Buffer('012345678901234567890'), // hex string or Buffer\n  peerId: new Buffer('01234567890123456789'), // hex string or Buffer\n  announce: [], // list of tracker server urls\n  port: 6881 // torrent client port, (in browser, optional)\n}\n\nconst optionalOpts = {\n  // RTCPeerConnection config object (only used in browser)\n  rtcConfig: {},\n  // User-Agent header for http requests\n  userAgent: '',\n  // Custom webrtc impl, useful in node to specify [wrtc](https://npmjs.com/package/wrtc)\n  wrtc: {},\n  getAnnounceOpts: function () {\n    // Provide a callback that will be called whenever announce() is called\n    // internally (on timer), or by the user\n    return {\n      uploaded: 0,\n      downloaded: 0,\n      left: 0,\n      customParam: 'blah' // custom parameters supported\n    }\n  },\n  // Proxy options (used to proxy requests in node)\n  proxyOpts: {\n      // For WSS trackers this is always a http.Agent\n      // For UDP trackers this is an object of options for the Socks Connection\n      // For HTTP trackers this is either an undici Agent if using Node16 or later, or http.Agent if using versions prior to Node 16, ex:\n      // import Socks from 'socks'\n      // proxyOpts.socksProxy = new Socks.Agent(optionsObject, isHttps)\n      // or if using Node 16 or later\n      // import { socksDispatcher } from 'fetch-socks'\n      // proxyOpts.socksProxy = socksDispatcher(optionsObject)\n      socksProxy: new SocksProxy(socksOptionsObject),\n      // Populated with socksProxy if it's provided\n      httpAgent: new http.Agent(agentOptionsObject),\n      httpsAgent: new https.Agent(agentOptionsObject)\n  },\n}\n\nconst client = new Client(requiredOpts)\n\nclient.on('error', function (err) {\n  // fatal client error!\n  console.log(err.message)\n})\n\nclient.on('warning', function (err) {\n  // a tracker was unavailable or sent bad data to the client. you can probably ignore it\n  console.log(err.message)\n})\n\n// start getting peers from the tracker\nclient.start()\n\nclient.on('update', function (data) {\n  console.log('got an announce response from tracker: ' + data.announce)\n  console.log('number of seeders in the swarm: ' + data.complete)\n  console.log('number of leechers in the swarm: ' + data.incomplete)\n})\n\nclient.once('peer', function (addr) {\n  console.log('found a peer: ' + addr) // 85.10.239.191:48623\n})\n\n// announce that download has completed (and you are now a seeder)\nclient.complete()\n\n// force a tracker announce. will trigger more 'update' events and maybe more 'peer' events\nclient.update()\n\n// provide parameters to the tracker\nclient.update({\n  uploaded: 0,\n  downloaded: 0,\n  left: 0,\n  customParam: 'blah' // custom parameters supported\n})\n\n// stop getting peers from the tracker, gracefully leave the swarm\nclient.stop()\n\n// ungracefully leave the swarm (without sending final 'stop' message)\nclient.destroy()\n\n// scrape\nclient.scrape()\n\nclient.on('scrape', function (data) {\n  console.log('got a scrape response from tracker: ' + data.announce)\n  console.log('number of seeders in the swarm: ' + data.complete)\n  console.log('number of leechers in the swarm: ' + data.incomplete)\n  console.log('number of total downloads of this torrent: ' + data.downloaded)\n})\n```\n\n### server\n\nTo start a BitTorrent tracker server to track swarms of peers:\n\n```js\nimport { Server } from 'bittorrent-tracker'\n// Or import Server from 'bittorrent-tracker/server'\n\nconst server = new Server({\n  udp: true, // enable udp server? [default=true]\n  http: true, // enable http server? [default=true]\n  ws: true, // enable websocket server? [default=true]\n  stats: true, // enable web-based statistics? [default=true]\n  trustProxy: false, // enable trusting x-forwarded-for header for remote IP [default=false]\n  filter: function (infoHash, params, cb) {\n    // Blacklist/whitelist function for allowing/disallowing torrents. If this option is\n    // omitted, all torrents are allowed. It is possible to interface with a database or\n    // external system before deciding to allow/deny, because this function is async.\n\n    // It is possible to block by peer id (whitelisting torrent clients) or by secret\n    // key (private trackers). Full access to the original HTTP/UDP request parameters\n    // are available in `params`.\n\n    // This example only allows one torrent.\n\n    const allowed = (infoHash === 'aaa67059ed6bd08362da625b3ae77f6f4a075aaa')\n    if (allowed) {\n      // If the callback is passed `null`, the torrent will be allowed.\n      cb(null)\n    } else {\n      // If the callback is passed an `Error` object, the torrent will be disallowed\n      // and the error's `message` property will be given as the reason.\n      cb(new Error('disallowed torrent'))\n    }\n  }\n})\n\n// Internal http, udp, and websocket servers exposed as public properties.\nserver.http\nserver.udp\nserver.ws\n\nserver.on('error', function (err) {\n  // fatal server error!\n  console.log(err.message)\n})\n\nserver.on('warning', function (err) {\n  // client sent bad data. probably not a problem, just a buggy client.\n  console.log(err.message)\n})\n\nserver.on('listening', function () {\n  // fired when all requested servers are listening\n\n  // HTTP\n  const httpAddr = server.http.address()\n  const httpHost = httpAddr.address !== '::' ? httpAddr.address : 'localhost'\n  const httpPort = httpAddr.port\n  console.log(`HTTP tracker: http://${httpHost}:${httpPort}/announce`)\n\n  // UDP\n  const udpAddr = server.udp.address()\n  const udpHost = udpAddr.address\n  const udpPort = udpAddr.port\n  console.log(`UDP tracker: udp://${udpHost}:${udpPort}`)\n\n  // WS\n  const wsAddr = server.ws.address()\n  const wsHost = wsAddr.address !== '::' ? wsAddr.address : 'localhost'\n  const wsPort = wsAddr.port\n  console.log(`WebSocket tracker: ws://${wsHost}:${wsPort}`)\n\n})\n\n\n// start tracker server listening! Use 0 to listen on a random free port.\nconst port = 0\nconst hostname = \"localhost\"\nserver.listen(port, hostname, () =\u003e {\n  // Do something on listening...\n})\n\n// listen for individual tracker messages from peers:\n\nserver.on('start', function (addr) {\n  console.log('got start message from ' + addr)\n})\n\nserver.on('complete', function (addr) {})\nserver.on('update', function (addr) {})\nserver.on('stop', function (addr) {})\n\n// get info hashes for all torrents in the tracker server\nObject.keys(server.torrents)\n\n// get the number of seeders for a particular torrent\nserver.torrents[infoHash].complete\n\n// get the number of leechers for a particular torrent\nserver.torrents[infoHash].incomplete\n\n// get the peers who are in a particular torrent swarm\nserver.torrents[infoHash].peers\n```\n\nThe http server will handle requests for the following paths: `/announce`, `/scrape`. Requests for other paths will not be handled.\n\n## multi scrape\n\nScraping multiple torrent info is possible with a static `Client.scrape` method:\n\n```js\nimport Client from 'bittorrent-tracker'\n// Or import Client from 'bittorrent-tracker/client'\n\nClient.scrape({ announce: announceUrl, infoHash: [ infoHash1, infoHash2 ]}, function (err, results) {\n  results[infoHash1].announce\n  results[infoHash1].infoHash\n  results[infoHash1].complete\n  results[infoHash1].incomplete\n  results[infoHash1].downloaded\n\n  // ...\n})\n````\n\n## command line\n\nInstall `bittorrent-tracker` globally:\n\n```sh\n$ npm install -g bittorrent-tracker\n```\n\nEasily start a tracker server:\n\n```sh\n$ bittorrent-tracker\nhttp server listening on 8000\nudp server listening on 8000\nws server listening on 8000\n```\n\nLots of options:\n\n```sh\n$ bittorrent-tracker --help\n  bittorrent-tracker - Start a bittorrent tracker server\n\n  Usage:\n    bittorrent-tracker [OPTIONS]\n\n  If no --http, --udp, or --ws option is supplied, all tracker types will be started.\n\n  Options:\n    -p, --port [number]  change the port [default: 8000]\n        --trust-proxy    trust 'x-forwarded-for' header from reverse proxy\n        --interval       client announce interval (ms) [default: 600000]\n        --http           enable http server\n        --udp            enable udp server\n        --ws             enable websocket server\n    -q, --quiet          only show error output\n    -s, --silent         show no output\n    -v, --version        print the current version\n```\n\n## license\n\nMIT. Copyright (c) [Feross Aboukhadijeh](https://feross.org) and [WebTorrent, LLC](https://webtorrent.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebtorrent%2Fbittorrent-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebtorrent%2Fbittorrent-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebtorrent%2Fbittorrent-tracker/lists"}