# OpenMAIC Course DSL Scene Types: The 6 Core Variants Explained

> Explore the 6 core Scene types in OpenMAIC's Course DSL: text, image, audio, video, quiz, and slide. Learn how OpenMAIC structures course content with these essential variants.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-04

---

**OpenMAIC defines six distinct Scene types in its Course DSL—`text`, `image`, `audio`, `video`, `quiz`, and `slide`—each declared in [`src/lib/types/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/types/stage.ts) to structure course content as JSON-compatible objects.**

The THU-MAIC/OpenMAIC repository provides a specialized **Course DSL** (Domain Specific Language) that represents educational content as structured data. At the heart of this system, the **Scene** serves as the fundamental unit of a course page, with each scene requiring a mandatory `type` field that instructs the front-end renderer how to display the content. Understanding the available OpenMAIC Course DSL Scene types is essential for authoring courses that leverage the platform's full interactive capabilities.

## The Scene Type Union in [`src/lib/types/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/types/stage.ts)

The core type definitions for all Scene variants reside in **[`src/lib/types/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/types/stage.ts)**, where the `Scene` union type consolidates the six possible shapes. According to the OpenMAIC source code, this union is exported at lines 12-22 as:

```typescript
export type Scene =
  | TextScene
  | ImageScene
  | AudioScene
  | VideoScene
  | QuizScene
  | SlideScene;

```

Each member of this union represents a distinct content modality, from static text to interactive assessments. The runtime uses this discriminated union pattern—keyed on the `type` property—to render the appropriate UI components based on the scene's declared category.

## Detailed Breakdown of the Six Scene Types

The OpenMAIC Course DSL specifies six concrete Scene implementations, each with mandatory and optional payload fields tailored to its media format.

### TextScene: Markdown and Plain Content

The **`text`** scene type handles static textual content, supporting headings, paragraphs, and markdown formatting. Defined at **`src/lib/types/stage.ts#L24-L28`**, this type requires a `content` field containing the text string to render.

### ImageScene: Static Visual Assets

For displaying pictures within lessons, the **`image`** scene type accepts a `src` URL and an `alt` text description. The type definition at **`src/lib/types/stage.ts#L30-L34`** ensures image assets include accessibility metadata through the mandatory alternative text field.

### AudioScene: Audio Playback

The **`audio`** scene type, located at **`src/lib/types/stage.ts#L36-L40`**, manages audio clips that learners can play back. It requires a `src` URL pointing to the audio file and optionally accepts a `caption` field for supplementary text.

### VideoScene: Video Content with Controls

Video content utilizes the **`video`** scene type defined at **`src/lib/types/stage.ts#L42-L47`**. This type supports MP4 files, YouTube embeds, and other video sources through the `src` field, alongside an optional `poster` image for the thumbnail preview and an optional `caption`.

### QuizScene: Interactive Assessments

The **`quiz`** scene type creates interactive assessments including multiple-choice and true/false questions. Defined at **`src/lib/types/stage.ts#L49-L55`**, it requires a `questions` array containing the assessment items and a `layout` field controlling the presentation format.

### SlideScene: Composite Containers

The **`slide`** scene type acts as a container that aggregates other scenes into a slide-style presentation. Located at **`src/lib/types/stage.ts#L57-L63`**, this type accepts an `elements` array containing sub-scenes (such as text, image, or video scenes) and a `transition` field specifying the animation style between slides.

## Practical Code Examples for Each Scene Type

When authoring courses in the OpenMAIC DSL, you define scenes as JSON-compatible objects that conform to the TypeScript interfaces. Below are concrete implementations for each of the six OpenMAIC Course DSL Scene types.

### Declaring a Text Scene

```typescript
const intro: Scene = {
  id: 'scene-1',
  type: 'text',
  title: 'Welcome',
  content: '## Introduction\nWelcome to the OpenMAIC course!'

};

```

### Declaring an Image Scene

```typescript
const diagram: Scene = {
  id: 'scene-2',
  type: 'image',
  title: 'System Architecture',
  src: 'https://example.com/arch.png',
  alt: 'Diagram showing MAIC system components'
};

```

### Declaring an Audio Scene

```typescript
const pronunciation: Scene = {
  id: 'scene-3',
  type: 'audio',
  title: 'Pronunciation Guide',
  src: 'https://example.com/audio.mp3',
  caption: 'Listen carefully and repeat.'
};

```

### Declaring a Video Scene

```typescript
const demo: Scene = {
  id: 'scene-4',
  type: 'video',
  title: 'Platform Demo',
  src: 'https://example.com/demo.mp4',
  poster: 'https://example.com/preview.png'
};

```

### Declaring a Quiz Scene

```typescript
const assessment: Scene = {
  id: 'scene-5',
  type: 'quiz',
  title: 'Knowledge Check',
  questions: [
    {
      prompt: 'What is the primary unit of a Course DSL page?',
      choices: ['Stage', 'Scene', 'Lesson'],
      answer: 1
    }
  ],
  layout: 'single-column'
};

```

### Declaring a Slide Scene with Nested Elements

```typescript
const summarySlide: Scene = {
  id: 'scene-6',
  type: 'slide',
  title: 'Chapter Summary',
  elements: [
    {
      id: 'sub-1',
      type: 'text',
      title: 'Key Points',
      content: 'Scenes provide modular content blocks.'
    },
    {
      id: 'sub-2',
      type: 'image',
      title: 'Summary Diagram',
      src: 'https://example.com/summary.png',
      alt: 'Scene type hierarchy'
    }
  ],
  transition: 'fade'
};

```

## Testing and Rendering Context

The OpenMAIC codebase includes test suites that demonstrate practical usage of these Scene types in production contexts. The file **[`tests/video-export/timeline-deps.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/video-export/timeline-deps.test.ts)** contains concrete scene objects used for testing audio, video, and text rendering pipelines. Similarly, **[`tests/workbench/tts-stage-sync.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/tts-stage-sync.test.ts)** illustrates how Scene objects integrate with text-to-speech generation workflows.

At runtime, the rendering engine—typically implemented in files like [`src/lib/workbench/scene-render.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/workbench/scene-render.ts)—consumes these typed objects and switches on the `scene.type` property to mount the appropriate React or web components for each media format.

## Summary

- **Six Core Types**: OpenMAIC defines `text`, `image`, `audio`, `video`, `quiz`, and `slide` Scene types in its Course DSL.
- **Central Definition**: All type definitions reside in **[`src/lib/types/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/types/stage.ts)**, with the `Scene` union exported at lines 12-22.
- **Discriminated Unions**: Each scene uses a `type` field to determine its specific interface and rendering behavior.
- **Composite Support**: The `slide` type uniquely supports nesting other Scene types via its `elements` array.
- **Type Safety**: The DSL provides full TypeScript support, ensuring mandatory fields like `src` for media or `questions` for quizzes are present at compile time.

## Frequently Asked Questions

### What is the primary source file for OpenMAIC Scene type definitions?

The primary source file is **[`src/lib/types/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/lib/types/stage.ts)**, which exports the `Scene` union type and defines the interfaces for `TextScene`, `ImageScene`, `AudioScene`, `VideoScene`, `QuizScene`, and `SlideScene` between lines 12 and 63.

### Can Slide scenes contain other Slide scenes?

According to the type definitions in **`src/lib/types/stage.ts#L57-L63`**, a `SlideScene` accepts an `elements` array of Scene objects. While technically possible depending on runtime implementation, the intended use case involves nesting atomic types like `text`, `image`, `audio`, or `video` rather than recursive slide nesting.

### What fields are required when creating a Quiz scene?

A `QuizScene` requires a `questions` array containing the assessment items and a `layout` string specifying the presentation format, as defined at **`src/lib/types/stage.ts#L49-L55`**. The `questions` array typically includes objects with `prompt`, `choices`, and `answer` indices.

### How does OpenMAIC differentiate between Scene types at runtime?

The system uses TypeScript discriminated unions keyed on the mandatory `type` property. The runtime checks the `scene.type` value—such as `'video'` or `'quiz'`—to determine which rendering component to mount, as demonstrated in test files like **[`tests/video-export/timeline-deps.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/video-export/timeline-deps.test.ts)**.