README.md

   1 # torrent
   2
   3 [![PkgGoDev](https://pkg.go.dev/badge/github.com/anacrolix/torrent)](https://pkg.go.dev/github.com/anacrolix/torrent)
   4
   5 This repository implements BitTorrent-related packages and command-line utilities in Go. The emphasis is on use as a library from other projects. It's been used 24/7 in production by downstream services since late 2014. The implementation was specifically created to explore Go's concurrency capabilities, and to include the ability to stream data directly from the BitTorrent network. To this end it [supports seeking, readaheads and other features](https://godoc.org/github.com/anacrolix/torrent#Reader) exposing torrents and their files with the various Go idiomatic `io` package interfaces. This is also demonstrated through [torrentfs](#torrentfs).
   6
   7 There is [support for protocol encryption, DHT, PEX, uTP, and various extensions](https://godoc.org/github.com/anacrolix/torrent). There are [several data storage backends provided](https://godoc.org/github.com/anacrolix/torrent/storage): blob, file, bolt, mmap, and sqlite, to name a few. You can [write your own](https://godoc.org/github.com/anacrolix/torrent/storage#ClientImpl) to store data for example on S3, or in a database.
   8
   9 Some noteworthy package dependencies that can be used for other purposes include:
  10
  11  * [go-libutp](https://github.com/anacrolix/go-libutp)
  12  * [dht](https://github.com/anacrolix/dht)
  13  * [bencode](https://godoc.org/github.com/anacrolix/torrent/bencode)
  14  * [tracker](https://godoc.org/github.com/anacrolix/torrent/tracker)
  15
  16 ## Installation
  17
  18 Install the library package with `go get github.com/anacrolix/torrent`, or the provided cmds with `go install github.com/anacrolix/torrent/cmd/...@latest`.
  19
  20 ## Library examples
  21
  22 There are some small [examples](https://godoc.org/github.com/anacrolix/torrent#pkg-examples) in the package documentation.
  23
  24 ## Mentions
  25
  26  * [@anacrolix](https://github.com/anacrolix) is interviewed about this repo in [Console 32](https://console.substack.com/p/console-32).
  27
  28 ### Downstream projects
  29
  30 There are several web-frontends, sites, Android clients and supporting services among the known public projects:
  31
  32  * [cove](https://coveapp.info): Torrent browser with streaming, DHT search, video transcoding and casting.
  33  * [confluence](https://github.com/anacrolix/confluence): torrent client as a HTTP service <!-- Well of course I know him... He's me -->
  34  * [exatorrent](https://github.com/varbhat/exatorrent): Elegant self-hostable torrent client <!-- 1.5k stars -->
  35  * [Simple Torrent](https://github.com/boypt/simple-torrent): self-hosted HTTP remote torrent client <!-- 876 stars -->
  36  * [TorrServ](https://github.com/YouROK/TorrServer): Torrent streaming server over http <!-- 543 stars -->
  37  * [mabel](https://github.com/smmr-software/mabel): Fancy BitTorrent client for the terminal <!-- 237 stars -->
  38  * [webtor.io](https://webtor.io/): free cloud BitTorrent-client <!-- not exclusively anacrolix/torrent maybe? 40-200 stars? -->
  39  * [Android Torrent Client](https://gitlab.com/axet/android-torrent-client): Android torrent client <!-- 29 stars -->
  40  * [libtorrent](https://gitlab.com/axet/libtorrent): gomobile wrapper <!-- 15 stars -->
  41  * [Go-PeersToHTTP](https://github.com/WinPooh32/peerstohttp): Simple torrent proxy to http stream controlled over REST-like api <!-- 28 stars -->
  42  * [CortexFoundation/torrentfs](https://github.com/CortexFoundation/torrentfs): Independent HTTP service for file seeding and P2P file system of cortex full node <!-- 21 stars -->
  43  * [goTorrent](https://github.com/deranjer/goTorrent): torrenting server with a React web frontend <!-- 156 stars, inactive since 2020 -->
  44  * [Go Peerflix](https://github.com/Sioro-Neoku/go-peerflix): Start watching the movie while your torrent is still downloading! <!-- 449 stars, inactive since 2019 -->
  45  * [Remote-Torrent](https://github.com/BruceWangNo1/remote-torrent): Download Remotely and Retrieve Files Over HTTP <!-- 57 stars, inactive since 2019 -->
  46  * [Trickl](https://github.com/arranlomas/Trickl): torrent client for android <!-- 48 stars, inactive since 2018 -->
  47  * [ANT-Downloader](https://github.com/anatasluo/ant): ANT Downloader is a BitTorrent Client developed by golang, angular 7, and electron <!-- archived -->
  48  * [Elementum](http://elementum.surge.sh/) (up to version 0.0.71)
  49
  50 ## Help
  51
  52 Communication about the project is primarily through [Discussions](https://github.com/anacrolix/torrent/discussions) and the [issue tracker](https://github.com/anacrolix/torrent/issues).
  53
  54 ## Command packages
  55
  56 Here I'll describe what some of the packages in `./cmd` do. See [installation](#installation) to make them available.
  57
  58 ### torrent
  59
  60 #### torrent download
  61
  62 Downloads torrents from the command-line.
  63
  64     $ torrent download 'magnet:?xt=urn:btih:KRWPCX3SJUM4IMM4YF5RPHL6ANPYTQPU'
  65     ... lots of jibba jabber ...
  66     downloading "ubuntu-14.04.2-desktop-amd64.iso": 1.0 GB/1.0 GB, 1989/1992 pieces completed (1 partial)
  67     2015/04/01 02:08:20 main.go:137: downloaded ALL the torrents
  68     $ md5sum ubuntu-14.04.2-desktop-amd64.iso
  69     1b305d585b1918f297164add46784116  ubuntu-14.04.2-desktop-amd64.iso
  70     $ echo such amaze
  71     wow
  72
  73 #### torrent metainfo magnet
  74
  75 Creates a magnet link from a torrent file. Note the extracted trackers, display name, and info hash.
  76
  77     $ torrent metainfo testdata/debian-10.8.0-amd64-netinst.iso.torrent magnet
  78     magnet:?xt=urn:btih:4090c3c2a394a49974dfbbf2ce7ad0db3cdeddd7&dn=debian-10.8.0-amd64-netinst.iso&tr=http%3A%2F%2Fbttracker.debian.org%3A6969%2Fannounce
  79
  80 See `torrent metainfo --help` for other metainfo related commands.
  81
  82 ### torrentfs
  83
  84 torrentfs mounts a FUSE filesystem at `-mountDir`. The contents are the torrents described by the torrent files and magnet links at `-metainfoDir`. Data for read requests is fetched only as required from the torrent network, and stored at `-downloadDir`.
  85
  86     $ mkdir mnt torrents
  87     $ torrentfs -mountDir=mnt -metainfoDir=torrents &
  88     $ cd torrents
  89     $ wget http://releases.ubuntu.com/14.04.2/ubuntu-14.04.2-desktop-amd64.iso.torrent
  90     $ cd ..
  91     $ ls mnt
  92     ubuntu-14.04.2-desktop-amd64.iso
  93     $ pv mnt/ubuntu-14.04.2-desktop-amd64.iso | md5sum
  94     996MB 0:04:40 [3.55MB/s] [========================================>] 100%
  95     1b305d585b1918f297164add46784116  -
  96