OpenMAIC Course DSL Scene Types: The 6 Core Variants Explained

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

The core type definitions for all Scene variants reside in 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:

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

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

};

Declaring an Image Scene

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

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

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

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

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 contains concrete scene objects used for testing audio, video, and text rendering pipelines. Similarly, 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—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, 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, 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.

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