Magnetizer

A powerful TypeScript library for decoding and encoding magnet links.

Features

• Zero dependencies - Lightweight and self-contained
• TypeScript-first - Full type definitions included
• Dual module support - Works with both ESM and CommonJS
• BitTorrent v1 & v2 - Supports both btih and btmh hash types
• Multiple hash types - SHA-1, MD5, eDonkey 2000, and more
• Base32 & hex support - Automatic format detection and conversion
• URL encoding/decoding - Handles special characters automatically
• 100% test coverage - Thoroughly tested and reliable

Table of Contents

• Installation
• Quick Start
• API Reference
  • decode()
  • encode()
  • IMagnetURI Interface
  • IInfoHashData Interface
• Supported Hash Types
• Advanced Usage
• Compatibility
• Development
• License

Installation

npm install magnetizer

yarn add magnetizer

pnpm add magnetizer

Quick Start

import { decode, encode } from 'magnetizer';

// Decode a magnet link
const result = decode('magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&dn=example');
console.log(result.displayName);  // 'example'

// Access structured info hash data
console.log(result.infoHashData[0].type);   // 'btih'
console.log(result.infoHashData[0].value);  // 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a'
console.log(result.infoHashData[0].urn);    // 'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

// Encode a magnet link
const magnetLink = encode({
  displayName: 'example',
  infoHashData: [{
    type: 'btih',
    value: 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a',
    urn: 'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'
  }],
  trackers: ['udp://tracker.example.com:80']
});
console.log(magnetLink);
// 'magnet:?dn=example&xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&tr=udp%3A%2F%2Ftracker.example.com%3A80'

API Reference

decode(magnetURI: string): IMagnetURI

Parses a magnet link string into a structured object.

Examples

Basic decoding:

import { decode } from 'magnetizer';

const result = decode('magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a');

console.log(result);
// {
//   displayName: null,
//   length: null,
//   infoHashes: ['urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'],
//   infoHashData: [{
//     type: 'btih',
//     value: 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a',
//     urn: 'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'
//   }],
//   webSeeds: [],
//   acceptableSources: [],
//   sources: [],
//   keywords: [],
//   manifest: null,
//   trackers: []
// }

// Access the raw hash value directly (no string parsing needed)
console.log(result.infoHashData[0].value);  // 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

Decoding with display name and trackers:

const magnetLink = 'magnet:?dn=Ubuntu%2024.04%20LTS&xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&tr=udp%3A%2F%2Ftracker.example.com%3A80&tr=wss%3A%2F%2Ftracker.webtorrent.io';

const result = decode(magnetLink);

console.log(result.displayName);  // 'Ubuntu 24.04 LTS'
console.log(result.trackers);
// [
//   'udp://tracker.example.com:80',
//   'wss://tracker.webtorrent.io'
// ]

Base32 hashes (auto-converted to hex):

// Base32 encoded hash (32 characters)
const result = decode('magnet:?xt=urn:btih:QHQXPYWMACKDWKP47RRVIV7VOURXFE5Q');

console.log(result.infoHashes);
// ['urn:btih:81e177e2cc00943b29fcfc635457f575237293b0']
// Note: Base32 is automatically converted to lowercase hex

Multiple hash types:

const magnetLink = 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&xt=urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709';

const result = decode(magnetLink);

console.log(result.infoHashes);
// [
//   'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a',
//   'urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709'
// ]

Handling invalid input:

// Empty or invalid strings return default empty object
const result = decode('');
console.log(result.infoHashes);  // []

// Invalid hashes are silently ignored
const result2 = decode('magnet:?xt=urn:btih:invalid');
console.log(result2.infoHashes);  // []

// Non-URN format is ignored
const result3 = decode('magnet:?xt=btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a');
console.log(result3.infoHashes);  // [] (missing 'urn:' prefix)

encode(data: Partial<IMagnetURI>): string

Builds a magnet link string from a structured object.

Examples

Basic encoding with hash only:

import { encode } from 'magnetizer';

const magnetLink = encode({
  infoHashes: ['c12fe1c06bba254a9dc9f519b335aa7c1367a88a']
});

console.log(magnetLink);
// 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

Full object with all fields:

const magnetLink = encode({
  displayName: 'example-file.tar.gz',
  length: 1048576,
  infoHashes: ['c12fe1c06bba254a9dc9f519b335aa7c1367a88a'],
  trackers: [
    'udp://tracker.example.com:80',
    'wss://tracker.webtorrent.io'
  ],
  webSeeds: ['https://example.com/files/example-file.tar.gz'],
  acceptableSources: ['https://mirror.example.com/example-file.tar.gz'],
  sources: ['http://cache.example.com/c12fe1c06bba254a9dc9f519b335aa7c1367a88a'],
  keywords: ['example', 'archive', 'tar'],
  manifest: 'https://example.com/manifest.rss'
});

console.log(magnetLink);
// 'magnet:?dn=example-file.tar.gz&xl=1048576&xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&tr=udp%3A%2F%2Ftracker.example.com%3A80&tr=wss%3A%2F%2Ftracker.webtorrent.io&kt=example+archive+tar&ws=https%3A%2F%2Fexample.com%2Ffiles%2Fexample-file.tar.gz&as=https%3A%2F%2Fmirror.example.com%2Fexample-file.tar.gz&xs=http%3A%2F%2Fcache.example.com%2Fc12fe1c06bba254a9dc9f519b335aa7c1367a88a&mt=https%3A%2F%2Fexample.com%2Fmanifest.rss'

Using Uint8Array/Buffer for hashes:

// From hex string to Uint8Array
const hashBytes = new Uint8Array([
  0xc1, 0x2f, 0xe1, 0xc0, 0x6b, 0xba, 0x25, 0x4a,
  0x9d, 0xc9, 0xf5, 0x19, 0xb3, 0x35, 0xaa, 0x7c,
  0x13, 0x67, 0xa8, 0x8a
]);

const magnetLink = encode({
  infoHashes: [hashBytes]
});

console.log(magnetLink);
// 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

Multiple info hashes:

const magnetLink = encode({
  infoHashes: [
    'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a',
    'urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709',
    'urn:md5:d41d8cd98f00b204e9800998ecf8427e'
  ]
});

console.log(magnetLink);
// 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&xt=urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709&xt=urn:md5:d41d8cd98f00b204e9800998ecf8427e'

Different hash type URNs:

// Plain hex defaults to btih
encode({ infoHashes: ['c12fe1c06bba254a9dc9f519b335aa7c1367a88a'] });
// Result: xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a

// Explicit URN prefix is preserved
encode({ infoHashes: ['urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709'] });
// Result: xt=urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709

encode({ infoHashes: ['urn:ed2k:31d6cfe0d16ae931b73c59d7e0c089c0'] });
// Result: xt=urn:ed2k:31d6cfe0d16ae931b73c59d7e0c089c0

IMagnetURI Interface

| Property | Type | Magnet Param | Description | |----------|------|--------------|-------------| | displayName | string \| null | dn | Human-readable filename | | length | number \| null | xl | Exact file size in bytes | | infoHashData | IInfoHashData[] | xt | Structured info hash data | | infoHashes | Array<string \| Uint8Array> | xt | URN containing file hash(es) (deprecated, use infoHashData) | | webSeeds | string[] | ws | HTTP/HTTPS download URLs | | acceptableSources | string[] | as | Alternative web download sources | | sources | string[] | xs | P2P source links (by content-hash) | | keywords | string[] | kt | Search keywords | | manifest | string \| null | mt | Link to metafile (e.g., RSS feed) | | trackers | string[] | tr | BitTorrent tracker URLs |

IInfoHashData Interface

| Property | Type | Description | |----------|------|-------------| | type | string | Hash type identifier (btih, btmh, sha1, md5, ed2k) | | value | string | Raw hexadecimal hash value (lowercase) | | urn | string | Complete URN string (e.g., urn:btih:c12fe1c0...) |

Supported Hash Types

| Hash Type | URN Prefix | Hex Length | Base32 Support | Description | |-----------|------------|------------|----------------|-------------| | BitTorrent v1 | urn:btih: | 40 chars | Yes (32 chars) | SHA-1 hash of torrent info dictionary | | BitTorrent v2 | urn:btmh: | 68 chars | No | Multihash (1220 prefix + SHA-256) | | SHA-1 | urn:sha1: | 40 chars | Yes (32 chars) | Generic SHA-1 file hash | | MD5 | urn:md5: | 32 chars | No | MD5 file hash | | eDonkey 2000 | urn:ed2k: | 32 chars | No | eDonkey/eMule network hash |

Hash Format Examples

BitTorrent v1 (hex):    urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a
BitTorrent v1 (base32): urn:btih:QHQXPYWMACKDWKP47RRVIV7VOURXFE5Q
BitTorrent v2:          urn:btmh:1220caf1e1c30e81cb361b9ee167c4aa411dfc88b7eb23e726d4451376f351009414
SHA-1:                  urn:sha1:da39a3ee5e6b4b0d3255bfef95601890afd80709
MD5:                    urn:md5:d41d8cd98f00b204e9800998ecf8427e
eDonkey 2000:           urn:ed2k:31d6cfe0d16ae931b73c59d7e0c089c0

Advanced Usage

Multiple Info Hashes

Torrents can include multiple hash types for cross-network compatibility:

import { decode, encode } from 'magnetizer';

// Decode a magnet link with multiple hashes
const result = decode(
  'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a' +
  '&xt=urn:ed2k:31d6cfe0d16ae931b73c59d7e0c089c0'
);

// Access structured data for each hash
console.log(result.infoHashData);
// [
//   { type: 'btih', value: 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a', urn: 'urn:btih:...' },
//   { type: 'ed2k', value: '31d6cfe0d16ae931b73c59d7e0c089c0', urn: 'urn:ed2k:...' }
// ]

// Filter by hash type
const btihHash = result.infoHashData.find(h => h.type === 'btih');
console.log(btihHash?.value);  // 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

BitTorrent v2 Hybrid Torrents

BitTorrent v2 uses SHA-256 hashes with a multihash prefix. Hybrid torrents include both v1 and v2 hashes:

const hybridMagnet = encode({
  displayName: 'hybrid-torrent',
  infoHashData: [
    {
      type: 'btih',
      value: 'c12fe1c06bba254a9dc9f519b335aa7c1367a88a',
      urn: 'urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'
    },
    {
      type: 'btmh',
      value: '1220caf1e1c30e81cb361b9ee167c4aa411dfc88b7eb23e726d4451376f351009414',
      urn: 'urn:btmh:1220caf1e1c30e81cb361b9ee167c4aa411dfc88b7eb23e726d4451376f351009414'
    }
  ]
});

// Both old and new clients can use this magnet link

Using Uint8Array for Hashes

The encoder accepts binary hash data as Uint8Array:

// Convert hex string to bytes
function hexToBytes(hex: string): Uint8Array {
  const bytes = new Uint8Array(hex.length / 2);
  for (let i = 0; i < hex.length; i += 2) {
    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
  }
  return bytes;
}

const hashBytes = hexToBytes('c12fe1c06bba254a9dc9f519b335aa7c1367a88a');

const magnetLink = encode({
  infoHashes: [hashBytes]
});
// Result: 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'

Round-Trip Preservation

Data is preserved through decode/encode cycles:

const original = 'magnet:?dn=test&xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a&tr=udp%3A%2F%2Ftracker.example.com%3A80';

const decoded = decode(original);
const reencoded = encode(decoded);

// Note: Parameter order may differ, but data is equivalent
console.log(decode(reencoded));
// Same structured data as decode(original)

Compatibility

| Runtime | Support | |---------|---------| | Node.js | v14+ (ES2020) | | Deno | Full ESM support | | Bun | Native TypeScript support | | Browser | Modern browsers (ES2020) |

Module Formats

• ESM: import { decode, encode } from 'magnetizer'
• CommonJS: const { decode, encode } = require('magnetizer')

Development

# Clone the repository
git clone https://github.com/isolomak/magnetizer.git
cd magnetizer

# Install dependencies
npm install

# Build (compiles to lib/)
npm run build

# Run tests (100% coverage required)
npm test

# Run linting
npm run lint

License

This project is licensed under the MIT License - see the LICENSE file for details.