About

Bencode is the binary encoding format used by the BitTorrent protocol for .torrent files and tracker communication. It encodes four data types: byte strings (length-prefixed as 4:spam), integers (i42e), lists, and dictionaries with lexicographically sorted keys. Malformed Bencode causes silent failures in torrent clients, corrupted metadata, or rejected tracker announces. This tool implements a strict recursive descent parser that validates structure, reports exact error byte offsets, and handles edge cases like leading zeros in integers (forbidden by BEP-0003) and nested dictionary key ordering.

Binary byte strings that are not valid UTF-8 (common in pieces fields containing SHA-1 hashes) are represented as Base64-encoded values in the JSON output, prefixed with base64: to distinguish them from regular strings. The reverse mode encodes JSON back to Bencode with proper key sorting. This tool approximates real-world torrent file parsing but does not validate semantic correctness of torrent metadata fields like piece length alignment.

Formulas

Bencode uses a length-prefixed and delimiter-based encoding scheme. The grammar can be expressed as a production rule set:

bencode → integer | string | list | dict

integer → i ⋅ digits ⋅ e

string → len : data_{len bytes}

list → l ⋅ bencode^* ⋅ e

dict → d ⋅ (string ⋅ bencode)^* ⋅ e

Where len is a non-negative decimal ASCII integer with no leading zeros, digits is an optional − followed by one or more decimal digits (no leading zeros except for 0 itself), and dictionary keys string must appear in lexicographic (raw byte) order: k_i < k_i+1 ∀ i. The parser operates at byte offset pos and advances through the input buffer. For binary detection, each decoded byte string is tested against UTF-8 validity. If decoding fails, the raw bytes are Base64-encoded and prefixed with the sentinel base64:.

Reference Data

Bencode Type	Syntax	Example (Bencode)	JSON Equivalent	Notes
Integer	i<digits>e	`i42e`	42	No leading zeros. `i-0e` is invalid.
Positive Integer	i<digits>e	`i0e`	0	Zero is valid as `i0e` only.
Negative Integer	i−<digits>e	`i-3e`	−3	Negative sign before digits.
Byte String	<length>:<data>	`4:spam`	`"spam"`	Length is decimal ASCII integer.
Empty String	0:	`0:`	`""`	Zero-length byte string.
Binary String	<length>:<bytes>	`20:\x01\x02...`	`"base64:AQID..."`	Non-UTF-8 data encoded as Base64.
List	l...items...e	`l4:spam4:eggse`	`["spam","eggs"]`	Ordered sequence of any types.
Empty List	le	`le`	`[]`	No elements.
Dictionary	d...pairs...e	`d3:cow3:moo4:spam4:eggse`	`{"cow":"moo","spam":"eggs"}`	Keys must be byte strings, sorted.
Nested Dict	d...d...e...e	`d1:ad1:bi1eee`	`{"a":{"b":1}}`	Arbitrary nesting depth allowed.
Nested List	l...l...e...e	`lli1ei2eeli3ei4eee`	`[[1,2],[3,4]]`	Lists within lists.
Mixed Nesting	Any combination	`d1:ali1e3:fooe1:bi42ee`	`{"a":[1,"foo"],"b":42}`	Dicts can contain lists and vice versa.
Large Integer	i<big>e	`i999999999999999999e`	999999999999999999	Arbitrary precision in spec.
Torrent Info Hash	SHA-1 of bencoded info dict	20-byte binary	Base64 or hex string	Used for magnet links.
Announce URL	Byte string in dict	`41:http://tracker.example.com/announce`	`"http://..."`	Tracker URL in torrent files.
Piece Hashes	Concatenated 20-byte SHA-1	Binary blob	Base64 encoded	Length must be multiple of 20.
Creation Date	Unix timestamp integer	`i1703980800e`	1703980800	Seconds since epoch.

Frequently Asked Questions

Binary data that cannot be decoded as valid UTF-8 is automatically Base64-encoded and prefixed with base64: in the JSON output. For example, a 20-byte SHA-1 hash becomes "base64:QUJDREVGR0hJSktMTU5PUFFSU1Q=". This preserves data integrity while keeping the JSON valid. When converting back from JSON to Bencode, strings with the base64: prefix are decoded back to raw bytes.

The BitTorrent Enhancement Proposal BEP-0003 explicitly forbids leading zeros in bencoded integers. The only valid representation of zero is i0e. Similarly, i-0e (negative zero) is invalid. This strictness ensures canonical encoding, which is critical because the info hash of a torrent file is computed over the exact bencoded bytes. Non-canonical encoding would produce different hashes for semantically identical data.

The parser operates in two modes. In strict mode (default), unsorted dictionary keys produce an error with the exact byte offset where the violation occurs. In lenient mode, keys are accepted in any order but the output JSON preserves the original ordering. When encoding JSON back to Bencode, keys are always sorted lexicographically by raw byte value regardless of input order, producing canonical Bencode output.

Yes. Use the file upload button to load a .torrent file directly. The parser reads the raw binary content and decodes all fields including the info dictionary, announce URLs, file lists, and piece hashes. The pieces field (concatenated 20-byte SHA-1 hashes) will appear as a Base64-encoded string since it contains raw binary data.

Bencode supports arbitrary-precision integers. This parser uses BigInt internally for all integer values. In the JSON output, integers within the safe range (−2⁵³ + 1 to 2⁵³ − 1) are rendered as JSON numbers. Integers outside this range are rendered as strings suffixed with n to indicate BigInt, preventing silent precision loss.

JSON has fewer types than Bencode. The reverse converter interprets JSON numbers without decimal points as Bencode integers, strings as byte strings (with base64: prefix detection for binary), arrays as lists, and objects as dictionaries. JSON null, true, and false have no Bencode equivalent and will produce an error. Floating-point numbers are also rejected since Bencode has no float type.