# Where Is the Playback Engine Code Located in OpenMAIC?

> Find the Playback Engine code in OpenMAIC at lib/playback/engine.ts. Discover how the PlaybackEngine class manages lecture playback and audio synchronization.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: internals
- Published: 2026-09-03

---

**The Playback Engine in OpenMAIC is implemented in [`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/engine.ts).

## Core Implementation in [`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts)

According to the OpenMAIC source code, the file [`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
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:

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/action-navigation.ts) file contains helper functions for validating and executing action jumps within a playback session. Additionally, [`lib/playback/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/derived-state.ts)), UI integration ([`PlaybackChromeRoot.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/PlaybackChromeRoot.tsx)), and navigation logic ([`action-navigation.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.