Skip to content
Xberg

Format Support

Xberg supports 101 file formats across 120 file extensions across major categories through native Rust extractors.

Overview

Section titled “Overview”

Xberg uses a high-performance Rust core with one registry-backed extraction path:

  • Native Rust Extractors: Fast, memory-efficient extractors for all supported formats

PDF extraction uses the pdf_oxide provider. Legacy .doc and .ppt extraction no longer requires LibreOffice; those formats are parsed through native OLE/CFB extractors.

Call list_supported_formats() in SDKs or the REST/API layer to inspect the runtime registry, including extensions and MIME types.

All formats support async/await and batch processing. Image formats and PDFs support optional OCR when configured.

Format Support Matrix

Section titled “Format Support Matrix”

Office Documents

Section titled “Office Documents”
Format Extensions MIME Type Extraction Method OCR Support Special Features
PDF .pdf application/pdf Native Rust (pdf_oxide) Yes Metadata extraction, image extraction, text layer detection
Excel .xlsx, .xlsm, .xlsb, .xls, .xlam, .xla, .xltx, .xlt, .ods Various Excel MIME types Native Rust (calamine) No Multi-sheet support, formula preservation
PowerPoint .pptx, .pptm, .ppsx application/vnd.openxmlformats-officedocument.presentationml.presentation Native Rust (roxmltree) Yes (for embedded images) Slide extraction, image OCR, table detection
PowerPoint Template .potx, .potm, .pot Various PowerPoint template MIME types Native Rust (roxmltree) Yes (for embedded images) Template slide extraction
Word (Modern) .docx application/vnd.openxmlformats-officedocument.wordprocessingml.document Native Rust No Preserves formatting, extracts metadata
Word (Macro/Template) .docm, .dotx, .dotm, .dot Various Word MIME types Native Rust No Macro-enabled and template variants
Word (Legacy) .doc application/msword Native OLE/CFB Yes Direct binary parsing
PowerPoint (Legacy) .ppt application/vnd.ms-powerpoint Native OLE/CFB Yes Direct binary parsing
OpenDocument Text .odt application/vnd.oasis.opendocument.text Native Rust No Full OpenDocument support
OpenDocument Spreadsheet .ods application/vnd.oasis.opendocument.spreadsheet Native Rust (calamine) No Multi-sheet support
OpenDocument Presentation .odp application/vnd.oasis.opendocument.presentation Native Rust (roxmltree) Yes (for embedded images) Slide extraction, tables, images, metadata
dBASE .dbf application/x-dbf Native Rust (dbase) No Table data extraction, field type support
Hangul Word Processor .hwp, .hwpx application/x-hwp Native Rust (hwpers) No Korean document format, text extraction
Apple Pages .pages application/x-iwork-pages-sffpages Native Rust No Modern iWork format support
Apple Numbers .numbers application/x-iwork-numbers-sffnumbers Native Rust No Spreadsheet extraction
Apple Keynote .key application/x-iwork-keynote-sffkey Native Rust No Slide and speaker notes extraction
WordPerfect .wpd, .wp, .wp5, .wp6 application/vnd.wordperfect Native libwpd binding No WP 4.2–X-series document extraction

Text & Markup

Section titled “Text & Markup”
Format Extensions MIME Type Extraction Method OCR Support Special Features
Plain Text .txt text/plain Native Rust (streaming) No Line/word/character counting, memory-efficient streaming
Markdown .md, .markdown text/markdown, text/x-markdown Native Rust (streaming) No Header extraction, link detection, code block detection
HTML .html, .htm text/html, application/xhtml+xml Native Rust (html-to-markdown-rs) No Converts to Markdown, metadata extraction
XML .xml application/xml, text/xml Native Rust (quick-xml streaming) No Element counting, unique element tracking
SVG .svg image/svg+xml Native Rust (XML parser) No Treated as XML document
reStructuredText .rst text/x-rst Native (rst-parser) No Full reST syntax support
Org Mode .org text/x-org Native (org) No Emacs Org mode support
Rich Text Format .rtf application/rtf, text/rtf Native (rtf-parser) No RTF 1.x support
Djot .djot text/x-djot Native Rust (jotdown) No Smart punctuation, tables, code blocks, YAML frontmatter, footnotes, math blocks
MDX .mdx text/mdx Native Rust (pulldown-cmark) No JSX-in-Markdown, component-based documents
AsciiDoc .adoc, .asciidoc text/asciidoc Native (asciidoc parser) No Titles, section levels, lists, tables, admonitions, source blocks, attribute substitution
WebVTT .vtt text/vtt Native (vtt parser) No Cue text extraction, voice spans, timing metadata

Structured Data

Section titled “Structured Data”
Format Extensions MIME Type Extraction Method OCR Support Special Features
JSON .json application/json, text/json Native Rust (serde_json) No Field counting, nested structure extraction
JSON Lines .jsonl, .ndjson application/x-ndjson Native Rust (serde_json) No Newline-delimited JSON records
YAML .yaml, .yml application/x-yaml, text/yaml, text/x-yaml Native Rust (serde_yaml) No Multi-document support, field counting
TOML .toml application/toml, text/toml Native Rust (toml crate) No Configuration file support
CSV .csv text/csv Native Rust No Tabular data extraction
TSV .tsv text/tab-separated-values Native Rust No Tab-separated data extraction

Email

Section titled “Email”
Format Extensions MIME Type Extraction Method OCR Support Special Features
EML .eml message/rfc822 Native Rust (mail-parser) No Header extraction, attachment listing, body text, UTF-16 support
MSG .msg application/vnd.ms-outlook Native Rust (mail-parser) No Outlook message support, metadata extraction
PST .pst application/vnd.ms-outlook-pst Native Rust No Outlook message store metadata extraction

Images

Section titled “Images”

All image formats support OCR when configured with ocr parameter in ExtractionConfig.

Format Extensions MIME Type Extraction Method OCR Support Special Features
PNG .png image/png Native Rust (image-rs) Yes EXIF metadata extraction
JPEG .jpg, .jpeg image/jpeg, image/jpg Native Rust (image-rs) Yes EXIF metadata extraction
WebP .webp image/webp Native Rust (image-rs) Yes Modern format support
BMP .bmp image/bmp, image/x-bmp, image/x-ms-bmp Native Rust (image-rs) Yes Uncompressed format
TIFF .tiff, .tif image/tiff, image/x-tiff Native Rust (image-rs) Yes Multi-page support
GIF .gif image/gif Native Rust (image-rs) Yes Animation frame extraction
JPEG 2000 .jp2, .j2k, .j2c, .jpx, .jpm, .mj2 image/jp2, image/jpx, image/jpm, image/mj2 Native Rust (hayro-jpeg2000) Yes OCR: Pure Rust, memory-safe decoder for JP2 container and J2K codestream formats, table detection, format-specific metadata
JBIG2 .jbig2, .jb2 image/x-jbig2 Native Rust (hayro-jbig2) Yes OCR: Pure Rust bi-level decoder, commonly found in scanned PDFs
PNM Family .pnm, .pbm, .pgm, .ppm image/x-portable-anymap, and so on. Native Rust (image-rs) Yes NetPBM formats
HEIC / HEIF .heic, .heics, .heif image/heic, image/heif, image/heic-sequence Native libheif binding Yes Pixel decoding requires heic and libheif; EXIF metadata is pure Rust
AVIF / AVCS .avif, .avcs image/avif, image/avcs Native libheif binding Yes Available through the HEIC-family aggregate

Audio and Video

Section titled “Audio and Video”

Audio/video formats use Whisper ONNX transcription when the transcription Cargo feature is enabled and a transcription config block is present. Video containers extract the audio track only.

Format Extensions MIME Type Extraction Method OCR Support Special Features
MP3 .mp3, .mpga audio/mpeg Whisper ONNX No Speech-to-text transcript
M4A / AAC .m4a audio/mp4 Whisper ONNX No Speech-to-text transcript
WAV .wav audio/wav Whisper ONNX No Speech-to-text transcript
WebM Audio .webm audio/webm Whisper ONNX No Speech-to-text transcript
MP4 Video Audio .mp4, .mpeg video/mp4 Whisper ONNX No Audio-track transcription only
WebM Video Audio .webm video/webm Whisper ONNX No Audio-track transcription only

Archives

Section titled “Archives”
Format Extensions MIME Type Extraction Method OCR Support Special Features
ZIP .zip application/zip, application/x-zip-compressed Native Rust (zip crate) No File listing, text content extraction
TAR .tar, .tgz application/x-tar, application/tar, application/x-gtar, application/x-ustar Native Rust (tar crate) No Unix archive support, gzip compression detection
7-Zip .7z application/x-7z-compressed Native Rust (sevenz-rust) No High compression format support
Gzip .gz application/gzip, application/x-gzip Native Rust (flate2) No Gzip decompression with text extraction

Academic & Publishing (Native)

Section titled “Academic & Publishing (Native)”
Format Extensions MIME Type Extraction Method OCR Support Special Features
LaTeX .tex, .latex application/x-latex, text/x-tex Native (manual parser) No Full LaTeX document support
EPUB .epub application/epub+zip Native (zip + roxmltree + html-to-markdown-rs) No E-book format, metadata extraction
BibTeX .bib application/x-bibtex, application/x-biblatex Native (biblatex) No Bibliography database support
Typst .typst, .typ application/x-typst Native (typst-syntax) No Modern typesetting format
Jupyter Notebook .ipynb application/x-ipynb+json Native (JSON parsing) No Code cells, markdown cells, output extraction
FictionBook .fb2 application/x-fictionbook+xml Native (fb2) No XML-based e-book format
DocBook .docbook, .dbk application/docbook+xml Native (roxmltree) No Technical documentation format
JATS .jats application/x-jats+xml Native (roxmltree) No Journal article XML format
OPML .opml application/xml+opml Native (roxmltree) No Outline format
RIS .ris application/x-research-info-systems Native (biblib) No Structured citation parsing with title, authors, DOI, and abstract extraction
EndNote XML .enw application/x-endnote+xml Native (biblib) No Structured citation parsing with title, authors, DOI, and keywords extraction
PubMed/MEDLINE .nbib application/x-pubmed Native (biblib) No Structured citation parsing with author affiliations, MeSH terms, and abstract
CSL JSON MIME-only application/csl+json Native (JSON parser) No Citation Style Language JSON

Markdown Variants (Native)

Section titled “Markdown Variants (Native)”
Format MIME Type Extraction Method Special Features
CommonMark text/x-commonmark Native (pulldown-cmark) Standard Markdown spec
GitHub Flavored Markdown text/x-gfm Native (pulldown-cmark) GFM extensions (tables, strikethrough, etc.)
MultiMarkdown text/x-multimarkdown Native (pulldown-cmark) MMD extensions
Markdown Extra text/x-markdown-extra Native (pulldown-cmark) PHP Markdown Extra extensions
MDX text/mdx Native (pulldown-cmark) JSX-in-Markdown format
Djot text/x-djot Native (jotdown) Djot markup format with extended features

Wire Formats vs Content Formats

Section titled “Wire Formats vs Content Formats”

Xberg distinguishes between two kinds of format:

Wire Formats (--format)

Section titled “Wire Formats (--format)”

Wire formats control how the extraction result is serialized for output. They determine the structure of the data you receive.

Format Flag Description
Text --format text Plain text output of the content field only. Default for extract.
JSON --format json Standard JSON serialization of the full result object. Default for batch.
TOON --format toon Token-Oriented Object Notation. Losslessly convertible to/from JSON, but optimized for LLM prompts. Produces ~30-50% fewer tokens than equivalent JSON.

TOON is designed for RAG and LLM pipelines where every token counts against context window limits and API costs. It encodes the same information as JSON but uses a more compact notation that language models parse equally well.

Content Formats (--content-format)

Section titled “Content Formats (--content-format)”

Content formats control how extracted text is rendered inside the content field of the result. This determines the markup used for the document’s textual content.

Format Flag Description
Plain --content-format plain Raw text with no markup. Default.
Markdown --content-format markdown GitHub Flavored Markdown (GFM) via comrak. Tables, headings, lists preserved.
HTML --content-format html HTML5 rendering via comrak.
Djot --content-format djot Djot markup format.

Wire format and content format are orthogonal. You can combine them freely, for example --content-format markdown --format toon produces a TOON-serialized result where the content field contains Markdown-formatted text.

Architecture Diagram

Section titled “Architecture Diagram”
graph TD
    A[File Input] --> B{MIME Detection}
    B --> C{Extraction Method}


    C -->|Native Format| D[Rust Core Extractors]


    D --> G[PDF Extractor]
    D --> H[Excel Extractor]
    D --> I[Image Extractor]
    D --> J[XML/Text/HTML Extractors]
    D --> K[Email Extractor]
    D --> L[Archive Extractor]
    D --> M[OLE/CFB Parser for .doc/.ppt]


    G --> P{OCR Needed?}
    I --> P
    P -->|Yes| Q[Tesseract OCR]
    P -->|No| R[Text Output]
    Q --> R


    H --> R
    J --> R
    K --> R
    L --> R
    M --> R


    R --> S[Post-Processing Pipeline]
    S --> T[Final Result]

Feature Flags

Section titled “Feature Flags”

Xberg uses Cargo feature flags to enable optional format and processing support. The default feature set is tokio-runtime plus simd-utf8; format support is opt-in for Rust consumers.

Feature Flag Enables
pdf PDF extraction through pdf_oxide, PDF images, PDF rendering helpers
excel / excel-wasm Excel spreadsheets through calamine
office DOCX/PPTX, legacy .doc/.ppt, OpenDocument, dBASE, academic citation formats
hwp / hwpx Hangul Word Processor formats
iwork Apple Pages, Numbers, and Keynote
email EML, MSG, and PST-backed Outlook metadata
html HTML/XHTML conversion with metadata extraction
xml XML and XML-derived document parsing
archives ZIP, TAR, Gzip, and 7-Zip archives
mdx MDX documents
svg SVG parse/sanitize/rasterize and normalized image output
heic HEIC/HEIF/AVIF/AVCS pixel decoding through libheif
wordperfect WordPerfect (.wpd) extraction via vendored libwpd/librevenge (desktop only: Linux, macOS, Windows)
transcription-types Audio/video transcription config and DTOs without ONNX Runtime
transcription Whisper ONNX audio/video transcription extractor
formats Aggregate for document/image/archive format extractors
wasm-target / android-target / windows-target Platform-specific pure-Rust or reduced-native feature sets

To enable specific features:

Cargo.toml
[dependencies]
# Enable only PDF and Excel format support
xberg = { version = "5", features = ["pdf", "excel"] }

To enable all features with --all-features:

Terminal
# Build with all format extraction features enabled
cargo build --all-features

Or use the convenience bundles:

All format extraction features (no server components):

Cargo.toml
[dependencies]
xberg = { version = "5", features = ["full"] }

Server features (API, MCP) with common format support:

Cargo.toml
[dependencies]
xberg = { version = "5", features = ["server"] }

CLI features with commonly used formats:

Cargo.toml
[dependencies]
xberg = { version = "5", features = ["cli"] }

System Dependencies

Section titled “System Dependencies”

Some optional capabilities require external system libraries:

Tesseract OCR (Optional)

Section titled “Tesseract OCR (Optional)”

Required for OCR on images and PDFs:

Terminal
# Install Tesseract OCR on macOS
brew install tesseract


# Install Tesseract OCR on Ubuntu/Debian
sudo apt-get install tesseract-ocr


# Install Tesseract OCR on RHEL/CentOS/Fedora
sudo dnf install tesseract


# Install Tesseract OCR on Windows (using Scoop)
scoop install tesseract

Docker Note: All system dependencies are pre-installed in official Xberg Docker images.

HEIC / HEIF / AVIF (Optional)

Section titled “HEIC / HEIF / AVIF (Optional)”

Pixel decoding for HEIC-family formats requires the heic feature and libheif at build and runtime. The Windows target aggregate omits heic because the standard Windows runner image does not provide libheif. Metadata extraction from HEIC-family files still works through the pure-Rust EXIF path.

Format Detection

Section titled “Format Detection”

Xberg automatically detects file formats using:

  1. File Extension Mapping: the supported-format registry maps extensions to MIME types
  2. mime_guess Crate: Fallback for unknown extensions
  3. Manual Override: Explicit MIME type can be provided

Use list_supported_formats() when you need the exact runtime registry for the current build.

Example with manual override:

format_detection.cs
using System.IO;
using Xberg;


var config = ExtractionConfig.Default();


// Automatic format detection from file extension
var output = await XbergConverter.ExtractAsync(
    ExtractInput.FromUri("document.pdf"),
    config
);
var result = output.Results[0];


// Manual MIME type override for files without extensions
var rawBytes = File.ReadAllBytes("document.dat");
var output2 = await XbergConverter.ExtractAsync(
    ExtractInput.FromBytes(rawBytes, "application/pdf", "document.dat"),
    config
);
var result2 = output2.Results[0];

OCR Support

Section titled “OCR Support”

OCR is available for:

  • All image formats (PNG, JPEG, WebP, BMP, TIFF, GIF, etc.)
  • PDF documents (with automatic fallback for scanned PDFs)
  • Embedded images in PowerPoint presentations

Configuration

Section titled “Configuration”
ocr_configuration.py
from xberg import ExtractInput, extract, ExtractionConfig, OcrConfig, TesseractConfig


# Configure OCR with multi-language support and custom Tesseract settings
config = ExtractionConfig(
    ocr=OcrConfig(
        tesseract_config=TesseractConfig(
            language=["eng", "deu"],  # English and German
            psm=3,                    # Page segmentation mode: Auto
            oem=1                     # OCR Engine mode: LSTM neural net
        )
    ),
    force_ocr=False  # Only use OCR when native text extraction is insufficient
)


output = await extract(
    ExtractInput(kind="uri", uri="scanned_document.pdf"),
    config=config,
)
result = output.results[0]

Automatic OCR Decision

Section titled “Automatic OCR Decision”

For PDFs, Xberg automatically decides whether OCR is needed by analyzing native text:

  • No OCR: Document has substantial, meaningful text (>64 non-whitespace chars, >32 chars/page average)
  • OCR Fallback: Document appears scanned (mostly punctuation, very low alphanumeric ratio)

Override with force_ocr=True to always use OCR regardless of native text quality.

Performance Characteristics

Section titled “Performance Characteristics”

Native Rust Extractors

Section titled “Native Rust Extractors”
  • PDF: Significantly faster than Python libraries due to native Rust implementation
  • Excel: Streaming parser, handles multi-GB files
  • XML: Streaming parser, memory-efficient for large documents
  • Text/Markdown: Streaming parser with lazy regex compilation
  • Archives: Efficient extraction without full decompression

OLE/CFB Extractors

Section titled “OLE/CFB Extractors”
  • Direct binary parsing of OLE2/CFB compound files
  • Used for legacy formats (.doc, .ppt)
  • No external tool dependencies, native Rust implementation

Batch Processing

Section titled “Batch Processing”

All formats support concurrent batch processing:

batch_processing.py
from xberg import ExtractInput, extract_batch, ExtractionConfig


# Process multiple files concurrently for better throughput
paths = ["file1.pdf", "file2.docx", "file3.xlsx"]
inputs = [ExtractInput(kind="uri", uri=path) for path in paths]
config = ExtractionConfig(max_concurrent_extractions=8)


output = await extract_batch(inputs, config=config)
for result in output.results:
    print(result.content[:200])

Format Limitations

Section titled “Format Limitations”

Known Limitations

Section titled “Known Limitations”
  • Password-Protected PDFs: Requires crypto extra (pip install xberg[crypto])
  • Legacy Excel (.xls): Formula evaluation not supported (values only)
  • Encrypted Office Documents: Password protection not supported
  • Multi-page TIFF: OCR processes first page only (configurable)
  • Animated GIF: Extracts first frame only
  • Video Transcription: Only the audio track is transcribed; frames are not decoded or captioned.

Unsupported Formats

Section titled “Unsupported Formats”
  • Video containers outside MP4/WebM transcription support (AVI, MOV, MKV, etc.)
  • Audio codecs/containers outside MP3, M4A/AAC-in-MP4, WAV, and WebM audio (FLAC, OGG, etc.)
  • CAD formats (DWG, DXF, etc.)
  • Database files (MDB, ACCDB, etc.)
  • Compressed Office formats without proper headers

Adding New Formats

Section titled “Adding New Formats”

Xberg’s plugin system can add custom format extractors. The public extractor bridge accepts the same ExtractInput shape as extract and returns one ExtractedDocument.

custom_extractor.rs
use async_trait::async_trait;
use std::sync::Arc;
use xberg::plugins::{register_document_extractor, DocumentExtractor, Plugin};
use xberg::{ExtractInput, ExtractedDocument, ExtractionConfig, Result};


pub struct CustomExtractor;


impl Plugin for CustomExtractor {
    fn name(&self) -> &str {
        "custom-format-extractor"
    }


    fn version(&self) -> String {
        "1.0.0".to_string()
    }
}


#[async_trait]
impl DocumentExtractor for CustomExtractor {
    async fn extract(
        &self,
        input: ExtractInput,
        _config: &ExtractionConfig,
    ) -> Result<ExtractedDocument> {
        let bytes = input.bytes.unwrap_or_default();
        let text = parse_custom_format(&bytes)?;


        Ok(ExtractedDocument {
            content: text,
            mime_type: "application/x-custom".into(),
            ..Default::default()
        })
    }


    fn supported_mime_types(&self) -> &[&str] {
        &["application/x-custom"]
    }
}


register_document_extractor(Arc::new(CustomExtractor))?;

See Also

Section titled “See Also”