File API

Complete API reference for the File class

Methods

file.select([priority])

Selects the file to be downloaded.

priority · number

Priority level for downloading this file

file.select(1) // Higher priority

file.deselect()

Deselects the file, which means it won’t be downloaded unless a stream is created for it.

file.deselect()

file.createReadStream([opts])

Create a Node.js readable stream to the file.

opts · object

Show properties

start · number

Start byte offset (inclusive)

end · number

End byte offset (inclusive)

return · Readable

Node.js readable stream

const stream = file.createReadStream({
  start: 0,
  end: 1000
})

stream.pipe(fs.createWriteStream('/path/to/output'))

file.stream([opts])

Create a W3C ReadableStream to the file.

opts · object

Show properties

start · number

Start byte offset (inclusive)

end · number

End byte offset (inclusive)

return · ReadableStream

W3C ReadableStream

const stream = file.stream()
const reader = stream.getReader()

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log('Received chunk:', value)
}

file[Symbol.asyncIterator]([opts])

Create an async iterator to iterate over file chunks.

opts · object

Show properties

start · number

Start byte offset (inclusive)

end · number

End byte offset (inclusive)

return · AsyncIterator

Async iterator yielding Uint8Array chunks

for await (const chunk of file) {
  console.log('Chunk:', chunk)
}

file.arrayBuffer([opts])

Get the file contents as an ArrayBuffer.

opts · object

Show properties

start · number

Start byte offset (inclusive)

end · number

End byte offset (inclusive)

return · Promise<ArrayBuffer>

Promise resolving to ArrayBuffer

const data = await file.arrayBuffer()
console.log('File data:', new Uint8Array(data))

file.blob([opts])

Get a W3C Blob object which contains the file data.

opts · object

Show properties

start · number

Start byte offset (inclusive)

end · number

End byte offset (inclusive)

return · Promise<Blob>

Promise resolving to Blob

const blob = await file.blob()
const url = URL.createObjectURL(blob)
window.open(url)

file.streamTo(elem) (browser only)

Sets the element source to the file’s streaming URL. Requires client.createServer() to be called first.

elem · HTMLMediaElement · required

Video or audio element

return · HTMLMediaElement

The same element passed in

const video = document.querySelector('video')
file.streamTo(video)

Supports:

• All major video containers (MP4, WebM, MKV, etc.)
• All major audio containers (MP3, AAC, Opus, etc.)
• Streaming and seeking
• Browser native codecs only

file.includes(piece)

Check if the piece number contains this file’s data.

piece · number · required

Piece index

return · boolean

True if file includes this piece

if (file.includes(10)) {
  console.log('Piece 10 is part of this file')
}

Properties

file.name

name · string

File name as specified by the torrent

console.log(file.name) // 'video.mp4'

file.path

path · string

File path as specified by the torrent

console.log(file.path) // 'some-folder/video.mp4'

file.length / file.size

length · number

File length in bytes

console.log(file.length) // 12345678

file.type

type · string

MIME type of the file. Defaults to 'application/octet-stream' if unknown.

console.log(file.type) // 'video/mp4'

file.downloaded

downloaded · number

Total verified bytes received for this file

console.log(file.downloaded) // 5000000

file.progress

progress · number

File download progress, from 0 to 1

console.log(`${(file.progress * 100).toFixed(1)}% complete`)

file.done

done · boolean

True when the file has been downloaded

if (file.done) {
  console.log('File download complete!')
}

file.streamURL

streamURL · string

URL of the file recognized by the HTTP server. Requires client.createServer() to be called first.

const url = file.streamURL
// 'http://localhost:8080/webtorrent/abc123.../video.mp4'

// Create download link
const a = document.createElement('a')
a.href = url
a.download = file.name
a.textContent = 'Download'
document.body.appendChild(a)

Events

file.on('done', callback)

Emitted when the file has been downloaded.

file.on('done', () => {
  console.log('File download complete')
})

file.on('stream', callback)

Emitted every time the HTTP server creates a new read stream (e.g., when the user seeks a video).

This is advanced functionality for manipulating streamed data.

file.on('stream', ({ stream, file, req }, pipeCallback) => {
  console.log('New stream created')
  
  // Optionally transform the stream
  if (needsTranscoding) {
    const transcoder = new SomeTranscoder()
    pipeCallback(stream.pipe(transcoder))
  }
})

file.on('iterator', callback)

Emitted when the HTTP server creates an async iterator.

This is advanced functionality for low-level data manipulation.

file.on('iterator', ({ iterator, file, req }, transformCallback) => {
  // Optionally transform the iterator
  const transformed = customTransform(iterator)
  transformCallback(transformed)
})