# How to Enable PPTX Import in OpenMAIC: A Complete Implementation Guide

> Unlock PPTX import in OpenMAIC with our guide. Learn how the importer package and JSZip convert PowerPoint to JSON for seamless integration.

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

---

**OpenMAIC enables PPTX import through the `@openmaic/importer` package, which uses JSZip to parse PowerPoint archives and converts slides, shapes, and media into JSON via the `parse()` function defined in [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js).**

OpenMAIC (THU-MAIC/OpenMAIC) provides a modular framework for visual presentation manipulation. Enabling PPTX import allows your application to load Microsoft PowerPoint files directly by transforming them into a standardized JSON representation that the OpenMAIC renderer consumes.

## Architecture of the PPTX Importer

The PPTX importer is implemented in pure JavaScript with no native dependencies. It treats `.pptx` files as ZIP archives and walks the internal OpenXML structure to extract content.

### Core Parsing Pipeline

The import workflow in [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js) follows a five-stage pipeline:

- **Archive Loading** – Uses `JSZip.loadAsync` (line 37) to read the PPTX file as an `ArrayBuffer` or `Blob`
- **Content Type Resolution** – Parses `[Content_Types].xml` (lines 58–88) to identify slide XML locations
- **Relationship Walking** – Traverses `_rels/*.rels` files (lines 33–55, 131–150) to collect linked images, charts, and themes
- **Element Conversion** – Delegates to specialized handlers (text, shape, chart, table, diagram) to build the JSON model (lines 365–630)
- **JSON Assembly** – Returns an object containing `slides`, `themeColors`, and presentation `size` (lines 48–56)

### Source File Structure

According to the OpenMAIC source code, the importer package contains these key files:

| File | Purpose |
|------|---------|
| [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js) | Core parser implementing the `parse()` function and ZIP extraction logic |
| [`src1/utils.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/utils.js) | Helper utilities for MIME type detection and base64 conversion |
| [`scripts/transvert.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/transvert.js) | CLI script for command-line PPTX-to-JSON conversion |
| [`dist/index.umd.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/dist/index.umd.js) | Compiled UMD bundle for production use |

## Installation and Setup

Install the importer package via npm:

```bash
npm install @openmaic/importer

```

You can import the parser directly from source for development or use the compiled bundle:

```javascript
// Development: import from source
import { parse } from '@openmaic/importer/src1/pptxtojson.js';

// Production: use UMD build
// import { parse } from '@openmaic/importer/dist/index.umd.js';

```

## Implementing Browser-Based PPTX Import

To enable PPTX import in a web application, read the file as an `ArrayBuffer` and pass it to the `parse()` function.

### Basic File Input Example

The following example handles file uploads from an HTML input element:

```html
<input id="pptxFile" type="file" accept=".pptx" />
<script type="module">
  import { parse } from '@openmaic/importer/src1/pptxtojson.js';

  document.getElementById('pptxFile').addEventListener('change', async (e) => {
    const file = e.target.files[0];
    const arrayBuffer = await file.arrayBuffer();
    const presentation = await parse(arrayBuffer, { mediaMode: 'base64' });
    
    console.log(presentation);
    // Output: { slides: [...], themeColors: [...], size: { width, height } }
  });
</script>

```

### Media Handling Configuration

The `parse()` function accepts an options object to control media output:

- **`mediaMode: 'base64'`** (default) – Embeds images and media as base64 data URIs
- **`mediaMode: 'blob'`** – Returns Blob URLs for large media files to improve memory efficiency

```javascript
// Use Blob URLs for presentations with large images
const presentation = await parse(arrayBuffer, { mediaMode: 'blob' });
// Image sources become blob:https://example.com/...

```

## Server-Side and CLI Usage

OpenMAIC supports headless PPTX conversion via Node.js. The repository includes a CLI demonstration script at [`scripts/transvert.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/transvert.js).

Convert a PPTX file to JSON from the command line:

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

```

You can also invoke the parser programmatically in Node.js by reading files into `ArrayBuffer` using the `fs` module and passing them to `parse()`.

## Integrating with the OpenMAIC Renderer

Once parsed, pass the JSON output to `@openmaic/renderer` to display slides in the browser:

```javascript
import { parse } from '@openmaic/importer/src1/pptxtojson.js';
import { render } from '@openmaic/renderer';

const presentation = await parse(arrayBuffer, { mediaMode: 'base64' });

// Render all slides
render(presentation.slides);

// Or render a specific slide
render([presentation.slides[0]]);

```

The renderer consumes the standardized JSON structure produced by [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js), translating each slide element into DOM representations.

## Summary

- **Install** the `@openmaic/importer` package to access PPTX parsing capabilities
- **Import** the `parse` function from [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js) (source) or [`dist/index.umd.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/dist/index.umd.js) (bundle)
- **Process** PPTX files by passing an `ArrayBuffer` to `parse()`, optionally specifying `mediaMode: 'blob'` for large files
- **Consume** the returned JSON containing `slides`, `themeColors`, and `size` properties
- **Render** the output using `@openmaic/renderer` or manipulate the JSON programmatically
- **Automate** conversions using the CLI script at [`scripts/transvert.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/scripts/transvert.js)

## Frequently Asked Questions

### What PowerPoint elements can OpenMAIC import?

The importer extracts slides, text shapes, images, charts, tables, diagrams, and theme colors from PPTX files. According to the source code in [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js) (lines 365–630), specialized handlers convert each OpenXML element type into a unified JSON representation that preserves layout and styling information.

### How do I handle memory constraints with large presentations?

Set the `mediaMode` option to `'blob'` when calling `parse()`. This stores media files as Blob URLs rather than base64 strings, significantly reducing memory overhead for presentations containing high-resolution images. Blob URLs can be assigned directly to `<img>` elements or other media tags.

### Can I use the importer without the OpenMAIC renderer?

Yes. The `@openmaic/importer` package functions independently and returns a plain JSON object. You can use this JSON with custom rendering engines, store it in databases, or transform it for other presentation frameworks. The output format is documented in the type definitions within [`src1/pptxtojson.js`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src1/pptxtojson.js).

### Where is the PPTX parsing logic implemented?

All core parsing logic resides in `packages/@openmaic/importer/src1/pptxtojson.js` in the THU-MAIC/OpenMAIC repository. This file implements the `parse()` function, orchestrates JSZip extraction, and coordinates the conversion of OpenXML structures to JSON through approximately 630 lines of parsing logic.