# Understanding the OpenMAIC Playback Engine State Machine: Four Core Modes Explained

> Explore the OpenMAIC playback engine state machine and its four core modes: idle, playing, paused, and live. Understand how these states manage lecture playback and live discussion.

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

---

**The OpenMAIC playback engine operates as a finite-state machine with four distinct `EngineMode` states—`idle`, `playing`, `paused`, and `live`—that manage transitions between recorded lecture playback and live discussion phases.**

The THU-MAIC/OpenMAIC repository provides a sophisticated playback system designed for educational content delivery. At its core, the **OpenMAIC playback engine state machine** orchestrates how recorded lectures transition into live discussions through well-defined state transitions enforced in [`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts).

## The Four EngineMode States

The current operational mode is represented by the `EngineMode` type defined in [`lib/playback/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/types.ts) (lines 17-19). The engine maintains exactly one of four mutually exclusive states at any time, visualized in the engine documentation comment (lines 9-24 of [`engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/engine.ts)).

### Idle State

The **`idle`** state represents complete inactivity with no playback activity occurring. When the engine initializes or completes a session, it rests here awaiting activation. According to the documentation in [`engine.ts#L9-L24`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts#L9-L24), the engine accepts `start()` or `continuePlayback()` commands only from this state to begin processing content.

### Playing State

The **`playing`** state indicates active processing of recorded educational content. In this mode, the engine sequentially handles actions including lecture speech synchronization and whiteboard stroke rendering. This represents the standard operational mode during recorded lecture playback, where the system processes stored action sequences.

### Paused State

When users interrupt playback or the system requires temporary halting, the engine enters the **`paused`** state. Unlike `idle`, this state preserves the current playback position and context, allowing immediate resumption back to `playing` via the `resume()` method. The engine enforces this state through checks such as `this.mode === 'playing'` before allowing pause operations.

### Live State

The **`live`** state handles post-lecture discussion phases that follow recorded content. Triggered by `handleEndDiscussion()`, this mode transitions the engine away from recorded sequences into real-time interaction. While in `live`, the engine supports `pause()` and `resume()` operations but no longer follows the recorded action sequence, as enforced by validation logic such as `this.mode !== 'live'` in playback control methods.

## State Transitions and Code Implementation

The state machine enforces strict transition rules throughout [[`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts). State changes occur through specific method invocations that validate the current mode before executing transitions.

```typescript
import { PlaybackEngine } from 'lib/playback/engine'

// Initialize engine with scenes, action engine, and audio player
const engine = new PlaybackEngine(scenes, actionEngine, audioPlayer)

// Transition: idle → playing
engine.start()

// Transition: playing → paused
engine.pause()

// Transition: paused → playing
engine.resume()

// Transition: playing → live (end of lecture, start discussion)
engine.handleEndDiscussion()

```

The implementation guards against invalid transitions by checking the current `this.mode` property. For example, certain playback controls are disabled when `this.mode === 'live'`, while others require `this.mode === 'playing'` to execute.

## Source Code Architecture

The playback engine state machine spans two critical files in the codebase:

- **[[`lib/playback/engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/engine.ts)** – Contains the core `PlaybackEngine` class implementation, state-transition logic, and mode validation checks.
- **[[`lib/playback/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/types.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/types.ts)** – Defines the `EngineMode` type contract and related TypeScript interfaces that constrain the state values to the four valid modes.

## Summary

- **`idle`** – Awaiting initialization via `start()` or `continuePlayback()`; no active processing occurs
- **`playing`** – Actively processing recorded lecture actions including audio and whiteboard strokes
- **`paused`** – Temporary halt preserving playback context; can resume to `playing` state
- **`live`** – Handling real-time discussion phases; supports pause/resume but ignores recorded sequences

## Frequently Asked Questions

### What triggers the transition from playing to live in OpenMAIC?

The transition occurs when `handleEndDiscussion()` is invoked on the playback engine, typically signaling the end of a recorded lecture segment and the beginning of a live discussion phase. This method moves the engine from processing recorded actions into a real-time interactive mode where the recorded timeline no longer governs behavior.

### How does the engine handle pausing during live mode?

While in `live` state, the engine supports both `pause()` and `resume()` operations similarly to the `playing` state. However, these actions control real-time discussion flow rather than recorded content playback. The engine maintains validation checks to ensure pause commands are valid regardless of whether the mode is `playing` or `live`.

### Where is the EngineMode type defined in the OpenMAIC repository?

The `EngineMode` type is defined as a TypeScript union type in [[`lib/playback/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/types.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/playback/types.ts) at lines 17-19. This definition constrains the engine's mode property to the four valid states: `'idle'`, `'playing'`, `'paused'`, or `'live'`.

### Can the OpenMAIC engine start playback directly from the paused state?

No, the engine cannot initialize directly into `paused` state. According to the state machine implementation in [`engine.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/engine.ts), entering `paused` requires an active transition from `playing` (or potentially `live`). To begin playback, the engine must first transition from `idle` to `playing` via `start()` or `continuePlayback()` before any pause operations become valid.