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

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:

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

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:

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 (lines 118-120), the system builds generation prompts:

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

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