DjVu file and chunks

A DjVu file is a tree of IFF chunks, the layout Electronic Arts defined in 1985 (EA IFF 85), preceded by four magic bytes. The format is described in the DjVu Reference, version 3, published by LizardTech in November 2005; DjVuLibre, the free reference implementation, fills in what the document leaves out. All multi-byte numbers are big-endian unless a field says otherwise.

Magic bytes

Every DjVu file starts with 41 54 26 54, the characters AT&T, which are not part of IFF. Directly after them comes a single FORM chunk holding everything else. A file whose first 8 bytes are AT&TFORM is DjVu; bytes 12 to 15 give the form type.

Chunks

Offset	Size	Type	Field	Description
`0`	4	char[4]	`id`	The chunk ID, four ASCII characters, such as `INFO`.
`4`	4	UInt32	`length`	The length of the data, not counting these 8 bytes or the pad byte.
`8`	`length`	bytes	`data`	The chunk’s content.
…	0 or 1	byte	pad	A zero byte when `length` is odd, so the next chunk starts on an even offset. Offsets are counted from the start of the file, so the 4 magic bytes keep that alignment.

A FORM chunk’s data starts with a four-character form type, followed by more chunks. A decoder skips any chunk it does not recognise.

Form types

Form	Holds	Where
`FORM:DJVU`	One page: `INFO` first, then the page’s other chunks.	A single-page file, or a page inside a `DJVM`.
`FORM:DJVM`	A multi-page document: `DIRM` first, an optional `NAVM`, then one `FORM` per component file.	The top level only.
`FORM:DJVI`	A shared component that pages include: a shape dictionary (`Djbz`) or shared annotations (`ANTa`/`ANTz`).	Inside a `DJVM`, or a separate file of an indirect document.
`FORM:THUM`	Thumbnails: one `TH44` chunk per page, in page order.	Inside a `DJVM`, or a separate file.

Chunk IDs

ID	In	Content
`DIRM`	DJVM	The document directory: every component file, its ID, type and offset.
`NAVM`	DJVM	The outline (bookmarks), BZZ-compressed.
`INFO`	DJVU	Page information: size, version, resolution, gamma, rotation. Must be first.
`INCL`	DJVU, DJVI	The ID of a `DJVI` component to include, as text.
`ANTa`, `ANTz`	DJVU, DJVI	Annotations: plain, or BZZ-compressed.
`TXTa`, `TXTz`	DJVU	Hidden text: plain, or BZZ-compressed.
`Djbz`	DJVI, DJVU	A JB2 shape dictionary shared by several pages.
`Sjbz`	DJVU	The page’s bi-level mask (text and line art), JB2-coded.
`Smmr`	DJVU	The mask coded with fax G4 (MMR) instead of JB2.
`FG44`	DJVU	The foreground colours, IW44-coded at low resolution.
`FGbz`	DJVU	The foreground as a palette, one colour per mask shape.
`BG44`	DJVU	The background, IW44-coded; usually several chunks, each refining the image.
`FGjp`, `BGjp`	DJVU	Foreground or background as a plain JPEG.
`FG2k`, `BG2k`	DJVU	Foreground or background as JPEG 2000. Named in the specification; DjVuLibre does not decode them.
`TH44`	THUM	One page’s thumbnail, IW44-coded.
`WMRM`	DJVU	JB2 data used to remove a watermark.
`CIDa`	DJVU	Found in some files; not described in the specification, and its contents are not publicly documented. Decoders skip it.

What a page holds

A page is built from up to three layers, drawn in this order:

The background (BG44 or BGjp), a colour image, usually at a third of the page resolution.
The mask (Sjbz or Smmr), a black and white image at full resolution: which pixels belong to the foreground.
The foreground colours (FG44, FGbz or FGjp), painted through the mask. Without a foreground chunk, the mask is drawn black.

A page may have only a mask (a black and white scan), only a background (a photo, called a “photo DjVu”), or all three (a “compound DjVu”). The usual chunk order in a compound page is INFO, INCL, Sjbz, FG44 or FGbz, BG44 chunks, ANTz, TXTz.

Multi-page documents

Bundled: one file, AT&TFORM:DJVM, holding the directory and all components; DIRM gives each component’s offset in the file.
Indirect: an index file, also FORM:DJVM with a DIRM but no components, and each page and shared component in its own file named by its ID. Made for serving books over the web one page at a time.
An older multi-page layout of DjVu 2, with a DIR0 directory chunk, is obsolete; DjVuLibre still reads it.

Example

The start of a single-page file, a black and white scan of 2,550 × 3,300 pixels at 300 dpi:

00000000  41 54 26 54 46 4F 52 4D  00 00 5A 3E 44 4A 56 55   AT&TFORM..Z>DJVU
00000010  49 4E 46 4F 00 00 00 0A  09 F6 0C E4 18 00 2C 01   INFO..........,.
00000020  16 01 53 6A 62 7A 00 00  59 F4 …                   ..Sjbz..Y.

Bytes	Meaning
`41 54 26 54`	`AT&T` magic
`46 4F 52 4D` `00 00 5A 3E`	`FORM`, 23,102 bytes of data
`44 4A 56 55`	form type `DJVU`: one page
`49 4E 46 4F` `00 00 00 0A`	`INFO`, 10 bytes
`09 F6`, `0C E4`	width 2,550, height 3,300
`18 00`	version 24 (minor byte first)
`2C 01`	300 dpi, little-endian
`16`, `01`	gamma 2.2, no rotation
`53 6A 62 7A` `00 00 59 F4`	`Sjbz`, 23,028 bytes of JB2 data

4 (form type) + 18 (INFO with header) + 8 + 23,028 (Sjbz) = 23,058; the remaining 44 bytes of the form would hold further chunks. The example is built to show the layout.

.DJVU File Format – File and chunks