@arcsin1/pptx2json

A resilient TypeScript PPTX parser that converts PowerPoint Open XML decks into structured JSON.

This package is the PPTX parsing core used by arcsin1/oh-my-ppt. It is also published as a standalone npm package for import pipelines that need to survive real-world PPTX files from PowerPoint, WPS, Keynote, Google Slides, LibreOffice, and conversion tools.

It favors null-safe OOXML traversal, slide-level isolation, and element-level isolation over assuming every deck uses the same "standard" XML shape.

Installation

npm install @arcsin1/pptx2json

Usage

import { parse } from '@arcsin1/pptx2json'

const result = await parse(arrayBufferOrBuffer, {
  imageMode: 'base64',
  videoMode: 'none',
  audioMode: 'none'
})

console.log(result.size)
console.log(result.slides)
console.log(result.diagnostics)

CommonJS is also supported:

const { parse } = require('@arcsin1/pptx2json')

Node and Web streams are supported through parseStream:

import { createReadStream } from 'node:fs'
import { parseStream } from '@arcsin1/pptx2json'

const result = await parseStream(createReadStream('deck.pptx'))

API

parse(file, options?)

file can be an ArrayBuffer, Buffer, or Uint8Array.

parseStream(stream, options?)

stream can be a Node readable stream, an async iterable, a sync iterable, or a Web ReadableStream-like object.

PPTX files are ZIP archives, so the parser still buffers the full stream internally before reading package parts. parseStream exists to make call sites simpler; it is not a streaming renderer.

Options:

type Options = {
  imageMode?: 'base64' | 'blob' | 'both' | 'none'
  videoMode?: 'blob' | 'none'
  audioMode?: 'blob' | 'none'
}

Returns:

type ParseResult = {
  slides: Slide[]
  usedFonts: string[]
  themeColors: string[]
  size: { width: number; height: number }
  diagnostics: ParseIssue[]
}

diagnostics contains recoverable warnings and errors. A malformed or unusual element should not abort the whole deck.

Each slide includes meta with its OOXML provenance: slide file, layout file, master file, theme file, slide index/number, and the effective per-slide theme colors.

Elements also include optional rendering metadata:

• zIndex and layer describe source layering (slide, layout, master, or nested group), source file, group depth, and a stable path inside that layer.
• Shape/text elements may include ooxml metadata such as preset geometry, adjustment values, text anchor/insets, and connector line ends.

What It Parses

• PPTX ZIP parts, relationships, content types, slide order, slide size, notes, and transitions.
• Slide, layout, and master backgrounds.
• Per-slide theme resolution through slide layout and slide master relationships, plus layout/master placeholder text style inheritance, theme colors, and text run styling.
• Shapes, preset geometry, preset adjustment values, custom geometry, connectors, fills, gradients, patterns, shadows, borders, flips, rotation, text anchor/insets, line ends, hyperlinks, and layer metadata.
• Text bodies with paragraphs, runs, bullets, line breaks, alignment, line spacing, size, color, bold, italic, underline, strike, and autofit hints. Imported font families are intentionally not emitted so consuming apps can apply their own font stack.
• Pictures and image fills with optional base64/blob extraction, crop rectangles, borders, brightness, contrast, saturation, and opacity.
• Tables, missing a:tblGrid fallback widths, merged cells, borders, fills, vertical alignment, and tableStyles.xml region inheritance.
• Groups with child transform normalization.
• Common charts, combo charts, scatter/bubble charts, series colors, chart formulas, external workbook references, and simple embedded .xlsx range extraction when cached values are missing.
• SmartArt text placeholders as diagram fallback data.
• Office Math as a limited math/text fallback.
• mc:AlternateContent fallback elements.
• Optional p14:media audio/video relationships.

Fault Tolerance

The parser is intentionally defensive:

• Missing XML parts return null instead of throwing through the whole import.
• Deep OOXML traversal uses safe access helpers.
• Slide parsing is isolated, so one broken slide does not discard the deck.
• Element parsing is isolated, so one broken shape/table/chart does not discard the slide.
• Recoverable problems are reported in result.diagnostics.

Notes

This is a PPTX-to-JSON parser, not a full PowerPoint renderer. Some advanced visual features are represented as best-effort structured data so the consuming app can decide how to render them.

License

Apache-2.0