How to Use the PPTX Import Pipeline in @openmaic/importer

The PPTX import pipeline in @openmaic/importer converts PowerPoint files into structured JSON by unzipping the archive, extracting metadata and slide relationships, and generating element hierarchies through the parse function in src1/pptxtojson.js.

The @openmaic/importer package is part of the OpenMAIC project (THU-MAIC/OpenMAIC) and provides a robust pipeline for transforming .pptx files into a JSON representation suitable for rendering. Whether you are building a presentation viewer or manipulating slide data programmatically, understanding how to leverage this pipeline is essential for integrating PowerPoint support into your application.

How the PPTX Import Pipeline Works

The pipeline processes PowerPoint files in three distinct stages, as implemented in src1/pptxtojson.js.

Stage 1: Load and Unzip

The parse function accepts an ArrayBuffer and uses JSZip to decompress the PPTX archive. This occurs at lines 33-38 of src1/pptxtojson.js, where the binary data is loaded asynchronously to expose the underlying OpenXML parts.

Stage 2: Extract Core Metadata

Once unzipped, the pipeline gathers slide dimensions, theme colors, and content-type mappings through helper functions like getContentTypes, getSlideInfo, and getTheme (lines 58-71, 90-99, and 101-130 in src1/pptxtojson.js). These values establish the canvas size and color palette for subsequent rendering.

Stage 3: Process Slides and Elements

For each slide, processSingleSlide (lines 33-57) resolves relationships to layouts, masters, notes, and media. The processNodesInSlide walker then traverses the XML tree, delegating to specialized generators like genShape, genChart, genTable, and genDiagram to create plain JavaScript objects representing shapes, text, images, videos, audio, tables, charts, and groups.

Configuration Options

The parse function accepts an options object to control media handling.

Media Mode Selection

The mediaMode parameter determines how embedded media are returned. Set to 'base64' by default, it can be changed to 'blob' for large files:

parse(arrayBuffer, { mediaMode: 'blob' })

This option is defined at lines 33-35 of pptxtojson.js and affects how processPicNode (lines 81-86) handles video and audio elements.

Programmatic Usage in Node.js

To use the pipeline programmatically, import the parse function and pass a file buffer:

import { parse } from '@openmaic/importer/src1/pptxtojson.js';
import { readFileSync } from 'fs';

const buffer = readFileSync('example.pptx');
const arrayBuffer = Uint8Array.from(buffer).buffer;

// Default parsing with base64 media
parse(arrayBuffer).then((result) => {
  console.log(`Parsed ${result.slides.length} slides`);
  console.log(JSON.stringify(result.slides[0], null, 2));
});

// Parse with Blob URLs for large media files
parse(arrayBuffer, { mediaMode: 'blob' }).then((result) => {
  // Access result.slides[0].elements for blob references
});

Command-Line Interface

The package includes CLI scripts for quick conversion and debugging.

Convert PPTX to JSON

Use scripts/transvert.js to convert files directly:

node packages/@openmaic/importer/scripts/transvert.js path/to/presentation.pptx > output.json

Or with pnpm:

pnpm run transvert path/to/presentation.pptx output.json

Extract Raw Structure

For debugging, unpack the PPTX archive without parsing:

node packages/@openmaic/importer/scripts/extract-pptx-structure.js \
  path/to/presentation.pptx ./extracted

This script exposes the raw XML files from the OpenXML package.

Understanding the JSON Output Structure

The parse function returns a JSON object with the following structure:

{
  "slides": [
    {
      "fill": "#FFFFFF",
      "elements": [],
      "layoutElements": [],
      "note": "HTML string of speaker notes",
      "transition": {}
    }
  ],
  "themeColors": ["#RRGGBB", "..."],
  "size": { "width": 960, "height": 540 }
}

• slides: Array of slide objects containing background fills, drawable elements, and layout references.
• elements: Array of generated objects from genShape, genChart, etc., ready for rendering.
• themeColors: Hex color values extracted from the presentation theme.
• size: Canvas dimensions in pixels.

Core Source Files

Understanding the source organization helps with debugging and extension:

• src1/pptxtojson.js: Entry point containing parse, processSingleSlide, and orchestration logic.
• src1/utils.js: Base64 conversion, MIME type detection, and geometry helpers.
• src1/shapePath.js and src1/customShapePath.js: SVG path generation for preset and custom shapes.
• src1/table.js, src1/chart.js, src1/diagram.js: Specialized handlers for complex elements.
• src1/animation.js: Transition and animation parsing.
• scripts/transvert.js: CLI wrapper for the parser (lines 3-8 and 20-23).
• scripts/extract-pptx-structure.js: Archive extraction utility.

Summary

• The PPTX import pipeline processes PowerPoint files through three stages: unzip, metadata extraction, and slide processing.
• Call the parse function in src1/pptxtojson.js with an ArrayBuffer to generate JSON.
• Use the mediaMode option to choose between base64 strings and Blob URLs for embedded media.
• The output JSON contains slides, theme colors, dimensions, and hierarchical element arrays ready for rendering.
• CLI tools transvert.js and extract-pptx-structure.js provide command-line access to the pipeline.

Frequently Asked Questions

What is the default media mode in @openmaic/importer?

The default mediaMode is 'base64', which embeds media files as base64-encoded strings within the JSON output. For large presentations, specify { mediaMode: 'blob' } to receive Blob URLs instead, reducing memory overhead.

Can I use the PPTX import pipeline in a browser environment?

Yes, the parse function accepts an ArrayBuffer, which can be obtained from a FileReader API in browsers. Ensure you handle the Promise-based workflow, as the pipeline uses JSZip.loadAsync for unzipping according to the source code.

How do I debug a PPTX file that fails to parse?

Use the extract-pptx-structure.js script to unpack the PPTX archive into a directory. This exposes the raw OpenXML parts (slides, layouts, media) for inspection without executing the full parsing logic in pptxtojson.js.

What element types does the pipeline support?

The pipeline generates objects for shapes, text, images, video, audio, tables, charts, diagrams (SmartArt), and groups. Each element type is processed by dedicated generators like genShape (lines 56-78), genTable (lines 61-65), and genChart (lines 57-60) in pptxtojson.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}