Torrent files
editTorrentFile is the content of a .torrent file (its metainfo). Read one with ParseAsync from a stream or Parse from bytes, and write it with WriteToAsync or ToUtf8ByteArray:
var content = "d8:announce14:https://t.test4:infod6:lengthi123e4:name8:file.txt12:piece lengthi16384e6:pieces20:01234567890123456789ee"u8.ToArray();
// Parse from a stream, such as File.OpenRead("file.torrent")
await using var input = new MemoryStream(content);
var torrent = await TorrentFile.ParseAsync(input);
Assert.Equal("https://t.test", torrent.Announce);
Assert.Equal("file.txt", torrent.Info.Name);
Assert.Equal("5A47092756A964C26715F69510A7B35B63B3B01C", Convert.ToHexString(torrent.GetInfoHashSha1()));
// Write to a stream, such as File.Create("copy.torrent")
await using var output = new MemoryStream();
await torrent.WriteToAsync(output, canonical: true);ParseAsync parses the stream as it reads it, and keeps a copy of the bytes of the info dictionary only, to compute the info-hash from the original bytes. It leaves the stream open. An overload reads from a PipeReader, which you complete yourself.
The model
TorrentFile holds the keys of the root dictionary:
| Property | Key | Content |
|---|---|---|
| Announce | announce | The URL of the tracker. |
| AnnounceList | announce-list | Tiers of tracker URLs. |
| Comment, CreatedBy, Publisher, PublisherUrl | comment, created by, publisher, publisher-url | Free text. |
| CreationDate | creation date | A DateTimeOffset, stored as Unix seconds. |
| UrlList | url-list | Web seed URLs. A single string in the file is read as a list of one URL. |
| HttpSeeds | httpseeds | HTTP seed URLs. |
| Nodes | nodes | DHT nodes, each with a Host and a Port. |
| Encoding | encoding | The name of the code page of the text fields. See Text encoding. |
| PieceLayers | piece layers | BitTorrent v2: the piece hashes of each file larger than a piece. |
| Info | info | The TorrentInfo that describes the content. |
| AdditionalKeys | any other | The keys the model does not represent, as bencode values. |
TorrentInfo holds the keys of the info dictionary:
| Property | Key | Content |
|---|---|---|
| Name | name | The name of the file, or of the folder for a multi-file torrent. |
| PieceLength | piece length | The size of a piece, in bytes. |
| Pieces | pieces | The SHA-1 hashes of the pieces, 20 bytes each, concatenated. Empty for a BitTorrent v2 only torrent. |
| Length | length | The size of the file, for a single-file torrent. |
| Files | files | The files of a multi-file torrent, each with a Path (its segments), a Length, an optional Md5Sum, and AdditionalKeys. |
| IsPrivate | private | Whether clients must only use the trackers of the torrent. |
| Source | source | The tag some private trackers add to make the info-hash unique to them. |
Md5Sum | md5sum | The MD5 of the content of a single-file torrent. |
| MetaVersion | meta version | 2 for a BitTorrent v2 or hybrid torrent. |
| FileTree | file tree | BitTorrent v2: the files, each a TorrentFileTreeEntry with a Path, a Length, a PiecesRoot and AdditionalKeys. |
| AdditionalKeys | any other | The keys the model does not represent, as bencode values. |
Single-file and multi-file torrents
A torrent has either a Length, for one file, or Files, for a folder named after Info.Name:
var data = "d4:infod5:filesld6:lengthi100e4:pathl6:images5:a.pngeed6:lengthi50e4:pathl9:readme.mdeee4:name7:project12:piece lengthi16384e6:pieces20:01234567890123456789ee"u8;
var torrent = TorrentFile.Parse(data);
// A torrent has either a Length (one file) or Files (a folder named Info.Name)
Assert.Null(torrent.Info.Length);
Assert.NotNull(torrent.Info.Files);
var files = torrent.Info.Files.Select(file => $"{torrent.Info.Name}/{string.Join('/', file.Path)} ({file.Length} bytes)");
Assert.Equal(["project/images/a.png (100 bytes)", "project/readme.md (50 bytes)"], files);The parser rejects a name or a path segment that is empty, . or .., or that contains / or \, so the segments can be combined into a path inside the download folder without leaving it.
BitTorrent v2 and hybrid torrents
A BitTorrent v2 torrent (BEP 52) describes its files with a FileTree and hashes them with SHA-256. A hybrid torrent has both the v1 keys and the v2 keys, so v1 and v2 clients can share it:
// A hybrid torrent, created by libtorrent, holds both the BitTorrent v1 and v2 keys
// Such as File.OpenRead("file.torrent")
await using var stream = typeof(TorrentFileTests).Assembly.GetManifestResourceStream("files/hybrid.torrent")!;
var torrent = await TorrentFile.ParseAsync(stream);
Assert.Equal(2, torrent.Info.MetaVersion);
Assert.NotNull(torrent.Info.FileTree);
var files = torrent.Info.FileTree.Select(file => $"{string.Join('/', file.Path)} ({file.Length} bytes)");
Assert.Equal(["data.bin (40000 bytes)", "docs/readme.txt (14 bytes)", "empty.bin (0 bytes)"], files);
// The SHA-256 merkle root of each file, and the piece hashes of the files larger than a piece
Assert.Equal(32, torrent.Info.FileTree[0].PiecesRoot.Length);
Assert.NotNull(torrent.PieceLayers);
Assert.Equal(torrent.Info.FileTree[0].PiecesRoot.ToArray(), torrent.PieceLayers[0].PiecesRoot.ToArray());
// The v1 info-hash is the SHA-1 of the 'info' dictionary, and the v2 info-hash its SHA-256
Assert.Equal("9AAF1926E4A8E378CC2D2BD2F71008D0C819ABF7", Convert.ToHexString(torrent.GetInfoHashSha1()));
Assert.Equal("EB59F42E745CCF50245148E82AEE5F7817D572D5F274A27F323C5286EA7691C3", Convert.ToHexString(torrent.GetInfoHashSha256()));- FileTree is a flat list of the files of the tree. Each Path is relative to the folder named after
Info.Namefor a multi-file torrent; a single-file torrent has one file, named like the torrent. - PiecesRoot is 32 bytes for a file that is not empty, and empty for an empty file.
- The padding files of a hybrid torrent are entries of Files whose
attrkey, inAdditionalKeys, containsp. - A v2 only torrent has no Pieces, Length or Files.
To create one, set MetaVersion to 2 and fill FileTree, and PieceLayers for the files larger than a piece. The writer builds the tree from the paths, and throws a FormatException when two paths are the same or a file is also a folder. The library does not compute the merkle trees for you.
The info-hash
GetInfoHashSha1 returns the BitTorrent v1 info-hash: the SHA-1 of the info dictionary. GetInfoHashSha256 returns the SHA-256 of the same bytes, which is the BitTorrent v2 info-hash. Format them with Convert.ToHexString.
- For a parsed torrent, they hash the exact bytes the
infodictionary was read from, so keys the model does not represent still count and the hash matches what other clients compute. - For a torrent you create, or after you assign a new TorrentInfo to Info, they hash the canonical encoding of the model.
- Changing the properties of the Info of a parsed torrent does not change the hash, which still uses the parsed bytes. Assign a new TorrentInfo to Info to change the content of a torrent.
Text encoding
The text fields of a torrent are UTF-8, unless its Encoding names another encoding. Old torrents use code pages such as GBK, Shift_JIS or windows-1251: their text is read and written with that encoding:
// A torrent whose 'encoding' key says its text is in GBK, a Chinese code page
var gbk = CodePagesEncodingProvider.Instance.GetEncoding("GBK")!;
byte[] data = [.. "d7:comment4:"u8, .. gbk.GetBytes("中文"), .. "8:encoding3:GBK4:infod6:lengthi1e4:name8:"u8, .. gbk.GetBytes("文件.txt"), .. "12:piece lengthi16384e6:pieces20:01234567890123456789ee"u8];
var torrent = TorrentFile.Parse(data);
Assert.Equal("GBK", torrent.Encoding);
Assert.Equal("文件.txt", torrent.Info.Name);
Assert.Equal("中文", torrent.Comment);
// Writing uses the same encoding
Assert.Equal(data, torrent.ToUtf8ByteArray());- The names are the ones of
Encoding.GetEncoding, including the code pages ofCodePagesEncodingProvider. The library uses the provider without registering it, so it does not change the encodings of your application. - An unknown name is ignored: the text is read and written as UTF-8.
- Bytes that are not valid in the encoding are an error when parsing, and characters it cannot represent are an error when writing: both throw a
FormatException. - Setting Encoding on a torrent you create writes its text with that encoding. The info-hash of a torrent you create depends on it, since the name is part of the
infodictionary.
Untrusted torrents
Parse and ParseAsync throw a FormatException when the data is not bencode, or is not a valid torrent: a missing info, name, piece length or pieces, pieces whose length is not a multiple of 20, both length and files or neither, a negative length, an unsafe path segment, a key of the wrong type, an integer out of the range of its property, or text that is not valid in its encoding. For BitTorrent v2, they also reject a file tree without a meta version of 2 or the reverse, a piece length that is not a power of two of at least 16 KiB, a file that is also a folder, a pieces root that is not 32 bytes, and piece layers whose hashes are not a multiple of 32 bytes. TryParse returns false instead:
// Not bencode
Assert.False(TorrentFile.TryParse("not a torrent"u8, out _));
// The 'info' dictionary has no 'piece length' and no 'pieces'
Assert.False(TorrentFile.TryParse("d4:infod6:lengthi1e4:name1:xee"u8, out _));
// A path segment that would leave the download folder
Assert.False(TorrentFile.TryParse("d4:infod5:filesld6:lengthi1e4:pathl2:..6:passwdeee4:name4:test12:piece lengthi16384e6:pieces20:01234567890123456789ee"u8, out _));Create a torrent
Hash each piece of the content with SHA-1, then fill the model:
var content = new byte[40_000]; // The file to share, such as File.ReadAllBytes("video.mp4")
var pieceLength = 16 * 1024;
// Each piece of the content is identified by its SHA-1 hash
var pieces = new List<byte>();
for (var offset = 0; offset < content.Length; offset += pieceLength)
{
var piece = content.AsSpan(offset, Math.Min(pieceLength, content.Length - offset));
pieces.AddRange(SHA1.HashData(piece));
}
var torrent = new TorrentFile
{
Announce = "https://tracker.example.com/announce",
CreatedBy = "MyApp",
CreationDate = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero),
Info = new TorrentInfo
{
Name = "video.mp4",
PieceLength = pieceLength,
Pieces = pieces.ToArray(),
Length = content.Length,
},
};
// Or WriteToAsync to save it, such as to File.Create("video.torrent")
var data = torrent.ToUtf8ByteArray();
var parsed = TorrentFile.Parse(data);
Assert.Equal("video.mp4", parsed.Info.Name);
Assert.Equal(torrent.GetInfoHashSha1(), parsed.GetInfoHashSha1());The last piece can be shorter than PieceLength. Writing checks the model and throws a FormatException when it is not a valid torrent, with the same rules as parsing.
Writing a parsed torrent
The keys the model does not represent are kept in AdditionalKeys: of the root dictionary, of the info dictionary, and of each file. Writing the torrent writes them back:
// 'x-custom' and 'x-tag' are not part of the model
var data = "d4:infod6:lengthi123e4:name8:file.txt12:piece lengthi16384e6:pieces20:012345678901234567895:x-tag3:abce8:x-custom5:valuee"u8.ToArray();
var torrent = TorrentFile.Parse(data);
var custom = (BencodeString)torrent.AdditionalKeys[new BencodeString("x-custom"u8.ToArray())];
Assert.Equal("value", custom.ToUtf8String());
Assert.True(torrent.Info.AdditionalKeys.ContainsKey(new BencodeString("x-tag"u8.ToArray())));
// They are written back, so the 'info' dictionary and the info-hash do not change
var written = torrent.ToUtf8ByteArray();
Assert.Equal(torrent.GetInfoHashSha1(), TorrentFile.Parse(written).GetInfoHashSha1());
// Add or remove keys like in any dictionary
torrent.AdditionalKeys.Add(new BencodeString("x-other"u8.ToArray()), new BencodeInteger(1));- A key of
AdditionalKeysthat the model represents, such asprivate, throws aFormatExceptionwhen writing: set the property instead. - The writer encodes the model. Writing a parsed torrent canonically gives the
infodictionary it was read from, so the same info-hash, when that dictionary was canonical and its values are written the way they were read. Two cases change it: an explicitprivate 0, which is not written, and text that a code page decodes and encodes differently. - Writing with
canonical: falsewrites the keys in the order of the model, not in the order of the data.