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

> Learn how to use the PPTX import pipeline in @openmaic/importer. Convert PowerPoint files to structured JSON by following our step by step guide and unlock powerful data extraction.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

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

```

This option is defined at lines 33-35 of [`pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```javascript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/transvert.js) to convert files directly:

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

```

Or with pnpm:

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

```

### Extract Raw Structure

For debugging, unpack the PPTX archive without parsing:

```bash
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:

```json
{
  "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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js)**: Entry point containing `parse`, `processSingleSlide`, and orchestration logic.
- **[`src1/utils.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/utils.js)**: Base64 conversion, MIME type detection, and geometry helpers.
- **[`src1/shapePath.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/shapePath.js)** and **[`src1/customShapePath.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/customShapePath.js)**: SVG path generation for preset and custom shapes.
- **[`src1/table.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/table.js)**, **[`src1/chart.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/chart.js)**, **[`src1/diagram.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/diagram.js)**: Specialized handlers for complex elements.
- **[`src1/animation.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/animation.js)**: Transition and animation parsing.
- **[`scripts/transvert.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/transvert.js)**: CLI wrapper for the parser (lines 3-8 and 20-23).
- **[`scripts/extract-pptx-structure.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/transvert.js) and [`extract-pptx-structure.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pptxtojson.js).