Main Page | Recent changes | Edit this page | Page history

Printable version | Disclaimers

 Not logged in
Log in | Help

Newzbin:NZB Specs

From NBDocs

[edit]

Where's the simple stuff?

In our Guide to NZB Files.

[edit]

NZB (Message-ID List) File Specification

Here follows a sample NZB for a single small file:

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE nzb PUBLIC "-//newzBin//DTD NZB 1.2//EN" "https://www.uzantoreto.com/DTD/nzb/nzb-1.2.dtd">
<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
  <head>
    <meta type="title">Your File!</meta>
    <meta type="tag">HD</meta>
    <meta type="category">TV</meta>
    <meta type="password">secret</meta>
    <meta type="X-Private-Example">Private data per NZB</meta>
  </head>
  <file poster="Joe Bloggs &lt;bloggs@nowhere.example&gt;" date="1071674882" subject="Here's your file!  abc-mr2a.r01 (1/2)">
    <meta type="password">secret</meta>
    <meta type="X-Private-Example">Private data per file</meta>
    <groups>
      <group>alt.binaries.newzbin</group>
      <group>alt.binaries.mojo</group>
    </groups>
    <segments>
      <segment bytes="102394" number="1">123456789abcdef@news.newzbin.com</segment>
      <segment bytes="4501" number="2">987654321fedbca@news.newzbin.com</segment>
    </segments>
  </file>
</nzb>
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE nzb PUBLIC "-//newzBin//DTD NZB 1.3//EN" "https://www.uzantoreto.com/DTD/nzb/nzb-1.3.dtd">
<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
  <head>
    <meta type="title">14124672752693960065</meta>
    <meta type="tag">HD</meta>
    <meta type="category">TV</meta>
    <meta type="password">secret</meta>
    <meta type="hashed">uzantoreto 1.0</meta>
    <meta type="X-Private-Example">Private data per NZB</meta>
  </head>
  <file poster="2515481512" date="1071674882" subject="4328237365363214872">
    <meta type="password">secret</meta>
    <meta type="X-Private-Example">Private data per file</meta>
    <groups>
      <group>8982966009590815828</group>
      <group>11399887813073764197</group>
    </groups>
    <segments>
      <segment number="1">5743979438396022225,14328839320489978059</segment>
      <segment number="2">11477715945714727111,12923161343744830588</segment>
    </segments>
  </file>
</nzb>

This example is for one file, consisting of two segments, which are 102,394 bytes and 4,501 bytes. The file is posted into two groups, alt.binaries.newzbin and alt.binaries.mojo; it was posted by Joe Bloggs, at unixtime 1071674882. The subject is slightly munged; the segment counter always starts at 1; but you can see it has 2 segments; confirmed by the segments tags below.

This is a fully populated nzb file, all the tags and attributes you can expect to see are there, but clients are expected to cope should more be added.

Since this is an XML format, clients are encouraged to use an XML parser to process it; minor changes to the nzb files we generate such as with attribute ordering, indentation, and even new tags and attributes must be taken into account. XML PI's and CDATA sections are not expected to be used, so clients should be free to cut some corners using lightweight parsers.

We will, where possible, avoid changes which may break clients; even those which use simple pattern matchers. Significant changes to the format are unlikely at this point, but users of the format should try not to get too complacent.

[edit]

XML Document Type Definitions

[edit]

XML Tag Breakdown

<nzb> .. </nzb> Description Root element for the file.
Attributes None
Body None (placeholder)
Children <head>, <file>
<head> .. </head> Description Contains all metadata relating to contents of NZB. (since v1.1)
Attributes None
Body None (placeholder)
Children <meta>
<meta> .. </meta> Description Creator-definable metadata for the contents of the NZB, e.g., title.
Attributes type string – Identifier for the metadata content.
Body string – The metadata content corresponding to the given type.
Children None
<file> .. </file> Description Represents a list of Message-IDs that make up a file.
Attributes
  1. poster string – Copy of the From: field from the article header.
  2. date int – Unixtime representation of the date the server saw this article. This is not completely reliable; timezones can break this value, and incorrectly configured news servers will make it almost useless. (since v1.0)
  3. subject string – A slightly munged copy of the article's subject. The segment counter (xx/yy) usually found at the end, is replaced with (1/yy). You can use the yy to confirm all segments are present.
Body None (placeholder)
Children <meta> (since v1.2), <groups>, <segments>
<groups> .. </groups> Description Placeholder element for a list of groups that reference the file.
Attributes None
Body None (placeholder)
Children <group>
<group> .. </group> Description One <group> element represents a group, multiple may be used.
Attributes None
Body string – The name of the group, e.g., alt.binaries.newzbin.
Children None
<segments> .. </segments> Description Placeholder element for a list of segments that make up a file.
Attributes None
Body None (placeholder)
Children <segment>
<segment> .. </segment> Description One part segment of a file.
Attributes
  1. bytes int – Size of the article, in bytes, as a number, with no comma separation.
  2. number int – Segment number of the article, gleaned by parsing (yy/zz).
Body string – The Message-ID of this article, without the surrounding < and >, e.g., 123456789abcdef@news.newzbin.com.
Children None
[edit]

Metadata Defined Types

The <meta> tag (as a child of the <head> tag), added in NZB 1.1, is designed to allow posters to include arbitrary data in any NZB file, which decoders might find useful. It's a very simple key-value system, where the key is the <type> attribute.

In order to create some consistency, we define the following types; if you'd like one added, let us know so others will know of it's existence and may choose to use it. As per usual XML, these types are case sensitive so take care.

  • title – A human-readable identifiable title for the contents of the NZB, i.e., the body of a metadata tag with the <title> attribute could be "Ubuntu Linux 9.10 64bit Desktop CD".
  • tag – An attribute, like h246 or SD (multiple tags allowed).
  • category – A category as used by your indexing service (preferably one).
  • password – If any password is required for the contents of the NZB, it can be specified in a password <meta> tag. If there are multiple passwords, this tag could simply be specified more than once and they can all be tried. If it becomes a common requirement we may develop a way to associate a password <meta> tag (or indeed any <meta> tag) with a specific <file> block.
  • hashed – Identifier of the NZB hashing scheme. (since v1.3)

The <meta> tag (as a child of the <file> tag), added in NZB 1.2, is designed to allow posters to include arbitrary data in any NZB file, which decoders might find useful. It's a very simple key-value system, where the key is the type attribute.

  • password – If any password is required for the specific file, it can be specified in a password <meta> tag. If supplied, it supersedes the password (or passwords) supplied in the <head> metadata. If there are multiple passwords, this tag could simply be specified more than once and they can all be tried.

If you'd like to create your own private type which will never clash with any that we define, prefix it with X- as per HTTP, i.e., X-Some-Private-Type.

[edit]

Who can use them?

Anyone. If you write a newsreader, feel free to add support for it. If you run a site, feel free to offer them for any file you want to point people at. This is an open standard, which anyone can use.

Retrieved from "http://docs.newzbin.com/Newzbin:NZB_Specs"

This page has been accessed 571463 times. This page was last modified 02:55, 6 Oct 2022.