Where Is the Playback Engine Code Located in OpenMAIC?

The Playback Engine in OpenMAIC is implemented in lib/playback/engine.ts, which defines the PlaybackEngine class that manages lecture playback, live discussions, and audio synchronization through a unified state machine.

The OpenMAIC repository (THU-MAIC/OpenMAIC) provides a comprehensive framework for AI-powered classroom experiences. The Playback Engine serves as the core coordinator for rendering lecture scenes, handling user interactions, and managing media state transitions. All engine logic resides within the lib/playback/ directory, with the primary implementation located in engine.ts.

Core Implementation in lib/playback/engine.ts

According to the OpenMAIC source code, the file lib/playback/engine.ts contains the PlaybackEngine class implementation. This class implements a robust state machine that transitions between idle, playing, paused, and live modes.

The engine orchestrates multiple responsibilities:

• Managing discussion flow during interactive segments
• Coordinating audio playback synchronization with visual scenes
• Handling snapshot management for state preservation
• Processing scene transitions and action navigation

The class constructor accepts four parameters: an array of scenes, an ActionEngine instance, an audio player object, and an optional callbacks object for UI updates.

Initializing the PlaybackEngine

To instantiate the engine, you must prepare the required dependencies. The following example demonstrates proper initialization according to the OpenMAIC implementation:

import { PlaybackEngine } from '@/lib/playback/engine';
import { ActionEngine } from '@/lib/action/engine';
import { createAudioPlayer } from '@/lib/utils/audio-player';

// Prepare dependencies
const scenes = /* load Scene[] from your deck */;
const actionEngine = new ActionEngine(/* ... */);
const audioPlayer = createAudioPlayer();

// Optional callbacks for UI updates
const callbacks = {
  onPlayStart: () => console.log('Playback started'),
  onPlayPause: () => console.log('Playback paused'),
  onPlaybackEnd: () => console.log('Playback finished')
};

// Instantiate the engine
const playbackEngine = new PlaybackEngine(scenes, actionEngine, audioPlayer, callbacks);

Controlling Playback State

Once initialized, the PlaybackEngine exposes methods to control playback flow. The primary methods include start(), pause(), resume(), and jumpToAction().

Use these methods to manage the lecture timeline:

// Start playback from the beginning
playbackEngine.start();

// Pause current playback
playbackEngine.pause();

// Resume after pause
playbackEngine.resume();

// Jump to action #42 with autoplay
await playbackEngine.jumpToAction(42, { autoplay: true });

The jumpToAction() method accepts an action index and options object, enabling precise navigation within the lecture recording while maintaining state consistency.

Supporting Files in the Playback Subsystem

The Playback Engine relies on several adjacent modules within the lib/playback/ directory to handle specialized concerns.

State Derivation and UI State

The file lib/playback/derived-state.ts provides pure functions such as computePlaybackView() that derive UI-friendly playback state from raw engine data. This separation ensures the core engine remains focused on state management while the presentation layer receives optimized data structures.

React Integration Layer

For React-based applications, components/edit/PlaybackChromeRoot.tsx serves as the UI wrapper that instantiates and controls a PlaybackEngine instance within the classroom editor context. This component bridges the engine's imperative API with React's declarative component model.

Navigation Helpers and Type Definitions

The lib/playback/action-navigation.ts file contains helper functions for validating and executing action jumps within a playback session. Additionally, lib/playback/types.ts defines TypeScript interfaces for engine modes, snapshots, callbacks, and related structures, ensuring type safety across the subsystem.

Summary

• The Playback Engine resides in lib/playback/engine.ts within the THU-MAIC/OpenMAIC repository.
• The PlaybackEngine class manages a state machine supporting idle, playing, paused, and live modes.
• Required dependencies include ActionEngine, an audio player instance, and optional UI callbacks for event handling.
• Supporting modules handle state derivation (derived-state.ts), UI integration (PlaybackChromeRoot.tsx), and navigation logic (action-navigation.ts).

Frequently Asked Questions

Where is the main playback logic implemented in OpenMAIC?

The main playback logic is implemented in lib/playback/engine.ts. This file contains the PlaybackEngine class that coordinates scene rendering, audio synchronization, and discussion flow through a finite state machine handling four distinct modes: idle, playing, paused, and live.

What playback modes does the PlaybackEngine support?

According to the source code in lib/playback/engine.ts, the engine supports idle, playing, paused, and live modes. These states control how the engine processes scenes, handles user input, and manages audio playback during both recorded lectures and live classroom sessions.

How do I integrate the PlaybackEngine into a React component?

Import the PlaybackEngine from @/lib/playback/engine and instantiate it with the required dependencies including scenes, ActionEngine, and an audio player. Reference components/edit/PlaybackChromeRoot.tsx in the OpenMAIC repository for a complete implementation pattern showing how to wrap the engine in a React component and connect callback handlers for UI updates.

What handles action navigation and jump validation in the playback system?

The file lib/playback/action-navigation.ts contains helper functions for navigating actions within a playback session. These utilities work alongside the jumpToAction() method in the main engine to validate jumps and ensure proper state transitions when skipping to specific lecture segments.

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