- 1 Document Status
- 2 Abstract
- 3 Introduction
- 4 URI Construction
- 5 Implementation
- 6 Other Implementations
Magnet Specification originally created 2002-06-12
Previous Revisions include 2002-06-17.
This specification is still draft as of this writing.
Due to the modular design of magnets, portions of this document may change without notice.
Original document by Gordon Mohr firstname.lastname@example.org
This version by Harold Feit email@example.com / firstname.lastname@example.org
This document describes the primary syntax and usage of magnet links and their general uses in computer programs.
The Magnet URI was originally designed to be an application nonspecific version of the Freenet's freenet: and eDonkey/eMule's ed2k: peer to peer file identifier links.
The decision to use the word Magnet was not based on any acronym, but rather the concept of bringing multiple dissimilar applications and groups together on common concepts.
Magnets are processed client-side and not server side. The typical intention is to have a preprocessor loaded on a system that gives users a list of supporting programs and the option to load the magnet into one of them. This document only handles what common values are used, not what individual applications do once they have them.
The Magnet URI starts with "magnet:?" as its prefix. No "//" is present at this point because the URI's namespace is not hierarchial.
Application-specific paramaters should be prefixed with x. so their implementations do not interfere with official paramaters.
Application-specific values of official paramaters that are not recognized by an application should be ignored.
This section describes the official paramaters present in a magnet link.
When an application is passed a paramater, it is up to that application to either support it or ignore it.
x.* paramaters are used for application-specific extensions.
Numbered suffixes on paramater names are used to reference multiple different topics in the same URI. Each number is a different topic.
The xt, dn, xl, xs and as paramaters group by numbered suffix.
xt - eXact Topic
This paramater specifies the exact topic to be displayed. Multiple xt= paramaters are permitted. When a numbered siffix is not present, most applications typically assume that all the xt= paramaters reference the same topic. This is generally accepted behavior.
Currently in-use xt= paramater value prefixes (not sorted):
* urn:sha1:<SHA1 Base32> * urn:ed2k:<ED2K Hexadecimal> * urn:ed2khash:<ED2K Hexadecimal> * urn:bitprint:<SHA1 Base32>.<TigerTree Root Base32> * urn:md5:<MD5 Hexadecimal> * urn:tree:tiger:<TigerTree Root Base32> * urn:tree:tiger/:<TigerTree Root Base32> * urn:tree:tiger/1024:<TigerTree Root Base32> * urn:kzhash:<KaZaA Hexadecimal> * urn:btih:<Torrent SHA1 InfoHash Base32>
The xt= paramater may, in some cases, be another URI such as a http:// or ftp:// link.
kt - Keyword Topic
This paramater specifies keywords to locate the sought after topic. The typical use of this paramater is to pre-populate a search box in a given application.
dn - Display Name
This paramater is typically used in conjunction with the xt= paramater to give a friendly name for a user.
xs/as - eXact Source/Acceptable Source
These paramaters are used to give known locations for obtaining files referenced using the xt= paramater. In general use, these paramaters are interchangable, although some applications only recognize xs, and others preference xs sources.
When both xs= and as= sources are used in the same magnet, xs= sources are typically used to reference a file by a hash (usually one referenced in an xt= paramater), and as= sources are used for traditional links such as a sourceforge mirror.
The value for these paramaters can be any URI that directly references a file, including http:// ftp:// ed2kftp://
mt - Manifest Topic
This paramater is used to reference a metafile that has definitions for multiple topics in it.
xl - eXact Length
(Pending approval for official status)
This paramater is used to specify the length in bytes of the file referenced by a given xt= paramater.
Current specifications permit for both.
Pre-Parsers on the client side populate a list of magnet supporting applications, and when passed a magnet, they prompt the user if more than one supporting application is present.
Specifically, each local app that wants to be given the chance to offer up options for MAGNET URIs should open a mini-HTTP-listener on the lowest available port, in the range 45100-45199. If not in the first 5 positions (45100-45104), they should also periodically check to see if higher positions open up, and if so, move downward with their MAGNET-listening service.
Such MAGNET-listening services should only accept inbound connections from the local machine.
http://127.0.0.1:451XX/magnet10/badge.img http://127.0.0.1:451XX/magnet10/canHandle.img(?params) http://127.0.0.1:451XX/magnet10/options.js(?params) http://127.0.0.1:451XX/magnet10/default.js(?params) http://127.0.0.1:451XX/magnet10/closeNotify(?port) http://127.0.0.1:451XX/magnet10/pause
Return a gif/jpeg/png image, 90x30, representing your program. Any server not returning such a valid logo will be considered to be something other than a MAGNET-compliant server. Web pages can poll for these images to see if services are available, and peer MAGNET services can poll for these images to find their port-neighbors (or see when they go away).
Given the params -- which are the same as the contents of a "magnet:" URI, after the '?' -- if your program can offer any operations for those parameters, return a 90x30 image. If you cannot offer any useful options for those paramters, return a NOT-FOUND or other error. The test of whether or not the program can handle the params should not take excessively long or trigger signficant CPU/network traffic.
The variable 'magnetCurrentSlot' will be set to the relative port (eg 0-99) this code came from, before it is run. The variables 'magnetOptionsPreamble' and 'magnetOptionsPostamble' will contain strings the options code should emit before and after its custom HTML. If successful in rendering any information at all, the variable 'magnetOptionsPollSuccesses' should be incremented by 1.
Parameter port will be a port number lower than the port this request is delivered to. It indicates that the server on that port is going through an orderly shutdown. Server may report any success (2xx) code to indicate that it plans to relocate up to the given port, or any failure code (4xx/5xx) if it plans to stay put.
Magnet Service Shutdowns
A MAGNET service going through an orderly shutdown should generate closeNotify requests to each port number higher than itself, one at a time in sequence, until it either gets back a success code or receives 5 "unable to connects" (eg no listener).
Other implementations of magnet link handling include client-side C++ and an in-progress VB.Net/C# implementation.
The priorities when developing such an implementation should be to intelligently parse known supporting programs, provide accurate lists of programs that support a given magnet, and pass the magnet to that application cleanly.
Pre-processing of the magnet (Such as xs/as sub-URI replacement) is permitted so long as specifications are followed.