Client Events
client.on('ready', callback)
Emitted when the client is ready to accept torrents.
client.on('ready', () => {
console.log('Client is ready')
})
client.on('listening', callback)
Emitted when the client starts listening on a port.
client.on('listening', () => {
const address = client.address()
console.log(`Listening on port ${address.port}`)
})
client.on('add', callback)
Emitted when a torrent is added to client.torrents. This fires before the torrent has metadata.
The torrent that was added
client.on('add', torrent => {
console.log('Torrent added:', torrent.infoHash)
})
client.on('torrent', callback)
Emitted when a torrent is ready to be used (metadata is available and store is ready).
The torrent that is ready
client.on('torrent', torrent => {
console.log('Torrent ready:', torrent.name)
console.log('Files:', torrent.files.length)
})
client.on('remove', callback)
Emitted when a torrent is removed from client.torrents.
The torrent that was removed
client.on('remove', torrent => {
console.log('Torrent removed:', torrent.infoHash)
})
client.on('seed', callback)
Emitted when a seeded torrent is ready.
The torrent that is seeding
client.on('seed', torrent => {
console.log('Now seeding:', torrent.magnetURI)
})
client.on('error', callback)
Emitted when the client encounters a fatal error. The client is automatically destroyed when this occurs.
Always listen for the ‘error’ event to prevent uncaught exceptions.
client.on('error', err => {
console.error('Client error:', err.message)
})
client.on('download', callback)
Emitted whenever data is downloaded by any torrent.
Number of bytes downloaded
client.on('download', bytes => {
console.log(`Downloaded ${bytes} bytes`)
console.log(`Total speed: ${client.downloadSpeed} bytes/sec`)
})
client.on('upload', callback)
Emitted whenever data is uploaded by any torrent.
client.on('upload', bytes => {
console.log(`Uploaded ${bytes} bytes`)
console.log(`Total speed: ${client.uploadSpeed} bytes/sec`)
})
Torrent Events
torrent.on('infoHash', callback)
Emitted when the info hash of the torrent has been determined.
torrent.on('infoHash', () => {
console.log('Info hash:', torrent.infoHash)
})
torrent.on('metadata', () => {
console.log('Metadata received')
console.log('Name:', torrent.name)
console.log('Files:', torrent.files.length)
console.log('Length:', torrent.length)
})
torrent.on('ready', callback)
Emitted when the torrent is ready to be used (metadata is available and store is ready).
torrent.on('ready', () => {
console.log('Torrent ready!')
torrent.files.forEach(file => {
console.log('File:', file.name, file.length)
})
})
torrent.on('done', callback)
Emitted when all torrent files have been downloaded.
torrent.on('done', () => {
console.log('Torrent download complete!')
console.log(`Downloaded: ${torrent.downloaded} bytes`)
console.log(`Uploaded: ${torrent.uploaded} bytes`)
console.log(`Ratio: ${torrent.ratio}`)
})
torrent.on('download', callback)
Emitted whenever data is downloaded.
Number of bytes downloaded
torrent.on('download', bytes => {
console.log(`Downloaded: ${bytes} bytes`)
console.log(`Total: ${torrent.downloaded} bytes`)
console.log(`Speed: ${torrent.downloadSpeed} bytes/sec`)
console.log(`Progress: ${(torrent.progress * 100).toFixed(1)}%`)
})
torrent.on('upload', callback)
Emitted whenever data is uploaded.
torrent.on('upload', bytes => {
console.log(`Uploaded: ${bytes} bytes`)
console.log(`Total: ${torrent.uploaded} bytes`)
console.log(`Speed: ${torrent.uploadSpeed} bytes/sec`)
})
torrent.on('wire', callback)
Emitted whenever a new peer is connected.
The wire (peer connection) instance
The peer’s address (optional)
torrent.on('wire', (wire, addr) => {
console.log('Connected to peer:', addr)
console.log('Peer type:', wire.type)
})
import MyExtension from './my-extension.js'
torrent.on('wire', (wire, addr) => {
console.log('Connected to peer:', addr)
wire.use(MyExtension)
})
torrent.on('noPeers', callback)
Emitted when no peers have been found. Emitted separately for each announce type.
One of: 'tracker', 'dht', 'lsd', or 'ut_pex'
torrent.on('noPeers', announceType => {
console.log(`No peers found via ${announceType}`)
})
torrent.on('peer', callback)
Emitted when a peer is added to the torrent swarm.
Peer address or identifier
torrent.on('peer', peer => {
console.log('Peer added:', peer)
})
torrent.on('verified', callback)
Emitted every time a piece is verified.
Index of the verified piece
let verifiedPieces = 0
torrent.on('verified', index => {
verifiedPieces++
console.log(`Piece ${index} verified (${verifiedPieces}/${torrent.pieces.length})`)
})
torrent.on('idle', callback)
Emitted when the torrent has no more active selections and starts idling or seeding.
torrent.on('idle', () => {
console.log('Torrent is now idle')
})
torrent.on('interested', callback)
Emitted when the client becomes interested in downloading from peers.
torrent.on('interested', () => {
console.log('Now interested in downloading')
})
torrent.on('uninterested', callback)
Emitted when the client is no longer interested in downloading from peers.
torrent.on('uninterested', () => {
console.log('No longer interested in downloading')
})
torrent.on('trackerAnnounce', callback)
Emitted when the torrent announces to a tracker.
torrent.on('trackerAnnounce', () => {
console.log('Announced to tracker')
})
torrent.on('dhtAnnounce', callback)
Emitted when the torrent announces to the DHT.
torrent.on('dhtAnnounce', () => {
console.log('Announced to DHT')
})
torrent.on('warning', callback)
Emitted when there is a warning (non-fatal error).
torrent.on('warning', err => {
console.warn('Torrent warning:', err.message)
})
torrent.on('error', callback)
Emitted when the torrent encounters a fatal error. The torrent is automatically destroyed when this occurs.
If there are no ‘error’ handlers on the torrent, the error will be emitted at client.on('error'). Always listen for errors in both places.
torrent.on('error', err => {
console.error('Torrent error:', err.message)
})
torrent.on('close', callback)
Emitted when the torrent has been destroyed.
torrent.on('close', () => {
console.log('Torrent closed')
})
File Events
file.on('done', callback)
Emitted when the file has been downloaded.
file.on('done', () => {
console.log(`File complete: ${file.name}`)
})
file.on('stream', callback)
Emitted when the HTTP server creates a new read stream for this file.
This is advanced functionality for manipulating streaming data.
file.on('stream', ({ stream, file, req }, pipeCallback) => {
console.log('Stream created for:', file.name)
console.log('Request headers:', req.headers)
})
file.on('iterator', callback)
Emitted when the HTTP server creates an async iterator for this file.
This is advanced functionality for low-level data manipulation.
file.on('iterator', ({ iterator, file, req }, transformCallback) => {
console.log('Iterator created for:', file.name)
})
Complete Example
import WebTorrent from 'webtorrent'
const client = new WebTorrent()
client.on('error', err => {
console.error('Client error:', err)
})
client.on('ready', () => {
console.log('Client ready')
const torrent = client.add(magnetURI)
torrent.on('infoHash', () => {
console.log('Got info hash:', torrent.infoHash)
})
torrent.on('metadata', () => {
console.log('Got metadata:', torrent.name)
})
torrent.on('ready', () => {
console.log('Torrent ready with', torrent.files.length, 'files')
})
torrent.on('download', bytes => {
console.log(`Progress: ${(torrent.progress * 100).toFixed(1)}%`)
})
torrent.on('done', () => {
console.log('Download complete!')
})
torrent.on('error', err => {
console.error('Torrent error:', err)
})
})
