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

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.

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 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	Core parser implementing the parse() function and ZIP extraction logic
src1/utils.js	Helper utilities for MIME type detection and base64 conversion
scripts/transvert.js	CLI script for command-line PPTX-to-JSON conversion
dist/index.umd.js	Compiled UMD bundle for production use

Installation and Setup

Install the importer package via npm:

npm install @openmaic/importer

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

// 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:

<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

// 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.

Convert a PPTX file to JSON from the command line:

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:

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, 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 (source) or 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

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 (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.

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.

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