Name

lijn-formats — format support matrix and metadata extraction

Synopsis

Lijn imports CBZ, CBR, PDF, EPUB, MOBI, and AZW3 files. Each format has specific extraction and metadata behavior.

Formats

CBZ Comic Book Archive, ZIP

Extraction: native ZIP decompression (zlib), memory-mapped archives. Pages: all image files in the archive, sorted by filename. Cover: first image by sort order. Metadata source: ComicInfo.xml.

CBR Comic Book Archive, RAR

Extraction: via the Unrar.swift package. Password-protected archives are rejected with an explicit error. Pages: all image files, sorted (localized standard order). Cover: first image by sort order. Metadata source: ComicInfo.xml (same as CBZ).

PDF Portable Document Format

Extraction: PDFKit; pages rendered as bitmaps at up to 3× scale, capped at 2048 px. Cover: embedded thumbnail stream when present, otherwise the first page. Metadata source: PDF document attributes (title, author, keywords). PDFs can also be read reflowed through the text engine (embedded text, with Vision OCR fallback for scans).

EPUB Electronic Publication

Two rendering paths, chosen by content analysis: an EPUB whose content is at least 70% images is treated as a comic.

• Image-heavy EPUBs: pages resolved from the OPF spine (container.xml → OPF → spine XHTML → images) and rendered in the comic reader.
• Text EPUBs: rendered by the native book engine — paginated attributed text, no web view.

Cover: from OPF container metadata. Metadata source: OPF / Dublin Core (title, creator, publisher, language, description, identifier, date).

MOBI / AZW3 Mobipocket / Kindle

Extraction: native parser (PDB header → PalmDOC → MOBI header → EXTH metadata → LZ77-compressed HTML records). Full MOBI7 support; AZW3/KF8 falls back to the MOBI7-compatible records. DRM-encrypted books are rejected. Rendering: always the native book engine (text). Metadata source: EXTH records (title, author, publisher, description, language, cover). Accepted extensions: mobi, prc, azw3, azw.

Metadata Extraction

Embedded metadata always wins over filename parsing. Every field is provenance-stamped with its source.

ComicInfo.xml CBZ, CBR

Extracted fields: Title, Series, Number, Volume, Summary, Publisher, LanguageISO, GTIN (ISBN), Writer, Penciller, Artist, Colorist, Inker, Genre (tags), Year/Month/Day.

PDF document attributes

titleAttribute → title (empty or “untitled” values are skipped); authorAttribute → author; keywordsAttribute → tags.

Filename parsing

All formats fall back to filename parsing for series, title, volume number, year, and author. Recognized volume markers: “tome”/“vol”/“volume” N, T N, #N. Junk candidates (“pdf_1”, bare format names) are rejected.

Online Lookup

Online lookup is explicit and reviewable: the user picks a provider and query, then accepts or rejects the suggestion. Providers:

Cover Enrichment

Vision OCR reads text on covers (8 recognition languages) and an on-device image classifier generates cover descriptions. Both feed library search and Spotlight. Runs in the background after import; a batch action is available in Settings.

Fallback Behavior

If no metadata is found (no ComicInfo.xml, no PDF attributes, filename parsing fails), the album is created with:

Content Identifier

Each imported file receives a filename-independent fingerprint:

c:<fileSize>:<crc32 first 64KB>:<crc32 middle 64KB>:<crc32 last 64KB>

Used to skip duplicates at import and by the background deduplication pass, which merges reading progress, bookmarks, and annotations into the kept copy before removing the duplicate.

Known Limitations

• CBR requires the Unrar.swift package; password-protected RAR archives are rejected
• DRM-encrypted MOBI/AZW3 (and any DRM content) cannot be opened
• AZW3/KF8-specific formatting falls back to MOBI7 rendering
• MOBI/AZW3 report no page count at import; text ebooks are paginated at render time
• Large PDFs may use significant memory during page rendering

See Also

lijn(1), lijn-opds(1), lijn-gestures(1)

Author

Aymane Bengrina — Studio Alticcio
alticc.io