# OpenMAIC VoiceDesign Interface: A Provider-Neutral Vocal Descriptor for Document Contracts

> Explore OpenMAIC VoiceDesign interface, a provider-neutral vocal descriptor embedding voice identity and delivery into document contracts for portable, cross-device voice configuration without vendor lock-in.

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

---

**The `VoiceDesign` interface is a provider-neutral descriptor that embeds vocal identity, texture, and delivery directly into OpenMAIC's document contract, enabling portable, cross-device voice configuration without vendor lock-in.**

OpenMAIC is an open-source framework for generating AI-driven classroom simulations. The `VoiceDesign` interface, defined in the core DSL module, ensures that vocal characteristics remain a **first-class citizen** within lesson documents, allowing seamless export, import, and synchronization across different devices and text-to-speech providers.

## What Is the VoiceDesign Interface?

`VoiceDesign` is a TypeScript interface that provides a structured, three-layer recipe for describing synthetic voices. According to the OpenMAIC source code in `packages/@openmaic/dsl/src/stage.ts` (lines 68-75), the interface defines three essential properties:

```typescript
export interface VoiceDesign {
  /** gender / age / role */
  identity: string;
  /** pitch / vocal quality */
  texture: string;
  /** emotion / pace */
  delivery: string;
}

```

This abstraction decouples voice descriptions from specific TTS implementations. Rather than hardcoding provider-specific voice IDs, OpenMAIC lessons store semantic descriptions—such as `"warm mentor"`, `"low and clear"`, or `"calm"`—that any compatible provider can interpret.

## Why VoiceDesign Belongs to the Document Contract

Embedding `VoiceDesign` directly into the persisted document structure (`GeneratedAgentConfig.voiceDesign`) provides four architectural advantages:

### Portability of Voice Across Devices

The document contract serves as the **single source of truth** for a lesson's structure. By serializing the `VoiceDesign` object within the `Stage` document, the vocal identity travels with the lesson file during export and import operations. This ensures that a lesson created on one device maintains its intended narration style when opened on another, without requiring external voice registries.

### Provider-Agnostic TTS Integration

The three-layer recipe (`identity`, `texture`, `delivery`) enables integration with multiple TTS engines such as **VoxCPM** and **Qwen**. Runtime implementations can consume these descriptors either as inline voice prompts or as seeds for registered voice cloning. This abstraction allows the runtime to switch TTS providers without rewriting lesson content, as demonstrated in [`lib/audio/voxcpm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/voxcpm.ts) where `buildAutoVoxCPMVoicePrompt` converts the interface into provider-specific prompt strings.

### Backward-Compatible Evolution

The `VoiceDesign` fields are **additive** by design. Older clients that do not recognize the `voiceDesign` property simply ignore it, while newer clients leverage it for richer narration. Because the DSL schema tolerates unknown fields, strict schema validators require updates, but the DSL version itself does not require a bump when adding new vocal descriptors.

### Consistent Generation Pipeline

When the AI generation pipeline creates classroom agents, it attaches a `VoiceDesign` instance to the `GeneratedAgentConfig.voiceDesign` property. This ensures that generated agents possess a coherent narration style immediately upon creation, eliminating the need for pre-registered voice assets or manual voice selection post-generation.

## Implementing VoiceDesign in OpenMAIC

### Defining a Voice Design

Create a `VoiceDesign` object to describe your agent's vocal characteristics:

```typescript
import { VoiceDesign } from '@openmaic/dsl/src/stage';

const teacherVoice: VoiceDesign = {
  identity: 'warm mentor',   // gender / age / role
  texture:  'low and clear', // pitch / vocal quality
  delivery: 'calm',          // emotion / pace
};

```

### Attaching to Generated Agents

Integrate the voice design into agent configurations using `GeneratedAgentConfig`:

```typescript
import { GeneratedAgentConfig } from '@openmaic/dsl/src/stage';

const genAgent: GeneratedAgentConfig = {
  id: 'agent-1',
  name: 'Ms. Lin',
  role: 'teacher',
  persona: '',
  avatar: '',
  color: '#ff8800',
  priority: 1,
  voiceDesign: teacherVoice, // Embedded in the contract
};

```

### Consuming in the TTS Layer

The runtime converts `VoiceDesign` into provider-specific prompts. In [`lib/audio/voxcpm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/voxcpm.ts) (lines 118-120), the system builds generation prompts:

```typescript
import { buildAutoVoxCPMVoicePrompt } from '@/lib/audio/voxcpm';

const prompt = buildAutoVoxCPMVoicePrompt({
  voiceDesign: teacherVoice,
});
// Generates: "voice: warm mentor, low and clear, calm"

```

## Summary

- **Location**: Defined in `packages/@openmaic/dsl/src/stage.ts` (lines 68-75) as part of the core DSL.
- **Structure**: Contains `identity`, `texture`, and `delivery` fields for semantic voice description.
- **Contract Role**: Stored in `GeneratedAgentConfig.voiceDesign` to ensure voices persist with lesson documents.
- **Provider Neutrality**: Enables switching between TTS engines like VoxCPM without modifying lesson content.
- **Compatibility**: Additive design ensures backward compatibility with legacy OpenMAIC clients.

## Frequently Asked Questions

### What fields does the VoiceDesign interface contain?

The interface contains three string fields: `identity` (describing gender, age, or role), `texture` (describing pitch and vocal quality), and `delivery` (describing emotion and pace). These fields provide a semantic, human-readable description of the desired voice rather than provider-specific identifiers.

### How does VoiceDesign support multiple TTS providers?

`VoiceDesign` uses provider-neutral descriptors that TTS integrations translate into provider-specific prompts or voice seeds. For example, the VoxCPM integration in [`lib/audio/voxcpm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/audio/voxcpm.ts) uses `buildAutoVoxCPMVoicePrompt` to convert the interface into a formatted prompt string, while other providers could map the same descriptors to their own voice libraries or cloning parameters.

### Where is VoiceDesign stored in the OpenMAIC document structure?

The interface is stored as the `voiceDesign` property within `GeneratedAgentConfig` objects, which themselves are part of the `Stage` document structure in OpenMAIC's DSL. This placement ensures the vocal configuration travels with the lesson file during serialization and deserialization operations.

### Is VoiceDesign backward compatible with older OpenMAIC versions?

Yes. The `VoiceDesign` property is additive, meaning older clients that do not recognize the field will simply ignore it when parsing documents. The schema tolerates unknown fields, preserving the integrity of lessons while allowing newer clients to leverage enhanced voice capabilities.