# How the OpenMAIC Import Pipeline Processes PPTX Files and Legacy Whiteboard Formats

> Discover how the OpenMAIC import pipeline processes PPTX files with import_pptx and canonicalizes legacy whiteboard data for seamless integration into your projects.

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

---

**The OpenMAIC import pipeline handles PowerPoint files through a dedicated `import_pptx` tool that converts slides into internal stage objects, while legacy whiteboard data is automatically canonicalized from a flat `whiteboard` array to a modern `whiteboards` dictionary structure before merging into the runtime.**

OpenMAIC (THU-MAIC/OpenMAIC) provides a unified stage model that must accommodate both modern PPTX presentations and older whiteboard backup formats. Understanding how the **import pipeline** transforms these distinct inputs into compatible stage objects is essential for developers extending the platform's material support.

## PPTX Import Pipeline Architecture

The PPTX import flow follows a three-phase pattern: detection, conversion, and stage integration.

### Material Detection and Validation

When a user attaches a presentation, the pipeline first validates the file type. In [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts), the system checks for PPTX materials using the `isPptxMaterial` utility, which identifies files by MIME type or filename extension.

```typescript
// Conceptual detection pattern from test suite
if (isPptxMaterial(material)) {
  // Trigger the import_pptx workflow
  await processPptxImport(material.blob);
}

```

This validation ensures that only compatible PowerPoint files enter the conversion stage, preventing invalid data from reaching the core runtime.

### Slide Conversion via pptxgenjs

Upon validation, the pipeline dynamically imports the `pptxgenjs` library to parse the binary PPTX data. As implemented in [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts) (lines 706-721), the system reads the file buffer and extracts individual slides.

The conversion logic maps PPTX elements to OpenMAIC's internal slide format. The primary transformation occurs in [`lib/export/use-export-pptx.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/export/use-export-pptx.ts), where shapes, text boxes, and images are normalized into slide objects containing textual, image, and shape elements. This abstraction layer decouples the presentation source from the rendering engine.

### Stage Integration Without Content Loss

The `import_pptx` tool appends converted slides to the current stage using the `writePagesToStage` action. Critically, the implementation in [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts) (lines 447-465) demonstrates that this operation **never replaces existing content**—it only appends new pages. This non-destructive approach ensures that pre-existing whiteboard data and annotations remain intact during the import process.

## Legacy Whiteboard Format Migration

Older OpenMAIC backups store whiteboard data differently than the current architecture, requiring a canonicalization step during restoration.

### Detecting Legacy whiteboard Arrays

Legacy stages stored whiteboard elements in a single `whiteboard` array property, while the modern schema uses a `whiteboards` dictionary where each whiteboard maintains a unique identifier. During stage loading, the system detects the legacy field presence in [`tests/runtime/database-chat-cutover.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/runtime/database-chat-cutover.test.ts) (lines 1616-1648).

### Canonicalization to whiteboards Dictionary

The canonicalizer transforms legacy data by wrapping the flat array into the new dictionary structure and generating unique IDs. This logic appears in [`tests/runtime/database-chat-cutover.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/runtime/database-chat-cutover.test.ts) (lines 1941-1975) and is implemented within the stage-loading routine in [`lib/api/stage-api-whiteboard.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/api/stage-api-whiteboard.ts).

```typescript
// Legacy-to-modern conversion pattern
if (stage.whiteboard) {
  stage.whiteboards = [{ 
    id: generateId(), 
    elements: stage.whiteboard 
  }];
  delete stage.whiteboard;
}

```

This migration runs transparently during restoration, ensuring backward compatibility without requiring manual user intervention.

## Merging Imported Content with Existing Stages

After PPTX conversion, the pipeline must reconcile new slide content with existing whiteboard state. The system injects **whiteboard beats**—timeline markers that signal whiteboard open/close events—to preserve interactivity.

According to [`tests/video-export/timeline.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/video-export/timeline.test.ts) (line 142), the pipeline ensures that whiteboard actions existing before the import remain replayable by maintaining precise synchronization between slide transitions and whiteboard activation states. The final stage object contains both **slide objects** (from PPTX conversion) and **whiteboard objects** (either migrated from legacy data or newly created), providing a seamless, layout-preserving experience.

## Practical Implementation Examples

The following patterns demonstrate the complete import workflow:

```typescript
// PPTX detection and import
async function handleMaterialImport(material: Material) {
  if (isPptxMaterial(material)) {
    const pptx = await import('pptxgenjs');
    const buffer = await pptx.read(material.blob);
    const slides = convertPptxToSlides(buffer); // lib/export/use-export-pptx.ts
    await writePagesToStage(stageId, slides);
  }
}

// Legacy whiteboard handling during stage load
function canonicalizeStage(stage: StageData) {
  if (stage.whiteboard) {
    stage.whiteboards = [{ 
      id: crypto.randomUUID(), 
      elements: stage.whiteboard 
    }];
    delete stage.whiteboard;
  }
  return stage;
}

```

## Summary

- **PPTX processing** relies on the `import_pptx` tool defined in [`skills/agent-runtime/pptx-import/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/pptx-import/SKILL.md), which uses `pptxgenjs` for parsing and [`lib/export/use-export-pptx.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/export/use-export-pptx.ts) for element conversion.
- **Legacy whiteboard arrays** (single `whiteboard` property) are automatically detected and canonicalized to the modern `whiteboards` dictionary format during stage restoration.
- **Non-destructive appending** ensures existing stage content persists when importing PowerPoint slides.
- **Whiteboard beats** maintain timeline synchronization between imported slides and existing interactive elements.

## Frequently Asked Questions

### How does OpenMAIC detect PowerPoint files during import?

OpenMAIC uses the `isPptxMaterial` utility function, which validates MIME types and filename extensions within the import pipeline. This check occurs in [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts) before any conversion logic executes.

### What happens to existing whiteboard content when I import a PPTX?

The `import_pptx` tool appends new slides to the current stage without replacing existing content. As verified in [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts) (lines 447-465), the pipeline preserves all pre-existing whiteboard data and annotations during the import operation.

### Does OpenMAIC support old whiteboard backup formats?

Yes. The platform automatically canonicalizes legacy `whiteboard` arrays into the modern `whiteboards` dictionary structure. This migration occurs during stage loading in [`lib/api/stage-api-whiteboard.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/api/stage-api-whiteboard.ts) and is tested in [`tests/runtime/database-chat-cutover.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/runtime/database-chat-cutover.test.ts), requiring no manual intervention.

### Which library handles the actual PPTX parsing?

The pipeline dynamically imports `pptxgenjs` to read PowerPoint file buffers. This dependency is loaded at runtime in [`tests/agent-runtime/import-pptx.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/import-pptx.test.ts) (lines 706-721) and processes the binary PPTX data before the conversion layer transforms it into OpenMAIC's internal slide format.