@aituber-onair/voice/dist/cjs/engines/MinimaxEngine.d.ts

Voice synthesis library for AITuber OnAir

import { Talk } from '../types/voice';
import { VoiceEngine } from './VoiceEngine';
/**
 * MiniMax endpoint types
 */
export type MinimaxEndpoint = 'global' | 'china';
/**
 * Available MiniMax TTS models
 */
export type MinimaxModel = 'speech-2.6-hd' | 'speech-2.6-turbo' | 'speech-2.5-hd-preview' | 'speech-2.5-turbo-preview' | 'speech-02-hd' | 'speech-02-turbo' | 'speech-01-hd' | 'speech-01-turbo';
/**
 * MiniMax voice speaker information
 */
export interface MinimaxVoiceSpeaker {
    voice_id: string;
    voice_name: string;
    gender: string;
    language: string;
    preview_audio?: string;
}
/**
 * MiniMax voice setting override options
 */
export interface MinimaxVoiceSettingsOptions {
    speed?: number;
    vol?: number;
    pitch?: number;
}
/**
 * MiniMax audio format options
 */
export type MinimaxAudioFormat = 'mp3' | 'wav' | 'aac' | 'pcm' | 'flac' | 'ogg';
/**
 * MiniMax audio setting override options
 */
export interface MinimaxAudioSettingsOptions {
    sampleRate?: number;
    bitrate?: number;
    format?: MinimaxAudioFormat;
    channel?: 1 | 2;
}
/**
 * MiniMax TTS voice synthesis engine
 */
export declare class MinimaxEngine implements VoiceEngine {
    private groupId?;
    private model;
    private defaultVoiceId;
    private language;
    private endpoint;
    private voiceOverrides;
    private audioOverrides;
    /**
     * Set GroupId for MiniMax API
     *
     * GroupId is a unique identifier for the user group in MiniMax's system.
     * Unlike other TTS engines that only require an API key, MiniMax requires both
     * an API key and a GroupId for authentication and usage tracking.
     *
     * This GroupId is used by MiniMax for:
     * - User group management
     * - Usage statistics tracking
     * - Billing and quota management
     *
     * You must obtain this pre-generated value from your MiniMax account dashboard.
     *
     * @param groupId GroupId for MiniMax API (required for production synthesis)
     */
    setGroupId(groupId: string): void;
    /**
     * Set endpoint region for MiniMax API
     * @param endpoint Endpoint region ('global' or 'china')
     */
    setEndpoint(endpoint: MinimaxEndpoint): void;
    /**
     * Set model for MiniMax TTS
     * Available models:
     * - speech-2.6-hd: Latest flagship HD model with highest fidelity
     * - speech-2.6-turbo: Low-latency Turbo model from 2.6 generation
     * - speech-2.5-hd-preview: Latest high-quality model (preview)
     * - speech-2.5-turbo-preview: Latest fast model (preview)
     * - speech-02-hd: High-quality model
     * - speech-02-turbo: Fast model
     * - speech-01-hd: Previous generation high-quality model
     * - speech-01-turbo: Previous generation fast model
     * @param model Model name
     */
    setModel(model: MinimaxModel): void;
    /**
     * Set language boost
     * @param language Language to boost recognition
     */
    setLanguage(language: string): void;
    /**
     * Set voice setting overrides (speed, volume, pitch)
     * @param settings Voice setting overrides
     */
    setVoiceSettings(settings: MinimaxVoiceSettingsOptions): void;
    /**
     * Set speech speed multiplier
     * @param speed Speed multiplier
     */
    setSpeed(speed?: number): void;
    /**
     * Set output volume multiplier
     * @param vol Volume multiplier
     */
    setVolume(vol?: number): void;
    /**
     * Set pitch adjustment in semitones
     * @param pitch Pitch adjustment
     */
    setPitch(pitch?: number): void;
    /**
     * Set audio encoding overrides (sample rate, bitrate, format, channel)
     * @param settings Audio setting overrides
     */
    setAudioSettings(settings: MinimaxAudioSettingsOptions): void;
    /**
     * Set audio sampling rate (Hz)
     * @param sampleRate Sampling rate
     */
    setSampleRate(sampleRate?: number): void;
    /**
     * Set audio bitrate (bps)
     * @param bitrate Bitrate
     */
    setBitrate(bitrate?: number): void;
    /**
     * Set audio output format
     * @param format Audio format
     */
    setAudioFormat(format?: MinimaxAudioFormat): void;
    /**
     * Set audio channel count
     * @param channel Number of channels
     */
    setAudioChannel(channel?: 1 | 2): void;
    /**
     * Alias for setLanguage to emphasize MiniMax terminology
     * @param language Language boost string
     */
    setLanguageBoost(language: string): void;
    /**
     * Get current API endpoint URL based on selected endpoint
     * @returns API endpoint URL
     */
    private getTtsApiUrl;
    /**
     * Get current voice list API endpoint URL based on selected endpoint
     * @returns Voice list API endpoint URL
     */
    private getVoiceListApiUrl;
    /**
     * Get available voice speakers list
     * Requires only API key
     * @param apiKey MiniMax API key
     * @returns Promise<MinimaxVoiceSpeaker[]>
     */
    getVoiceList(apiKey: string): Promise<MinimaxVoiceSpeaker[]>;
    /**
     * Build MiniMax voice settings by merging emotion defaults with overrides
     * @param voiceId Target voice ID
     * @param defaults Default emotion-based values
     */
    private buildVoiceSetting;
    /**
     * Build MiniMax audio settings from overrides
     */
    private buildAudioSetting;
    /**
     * Test voice synthesis with minimal requirements
     * Requires API key and voice ID, but not GroupId
     * @param text Text to synthesize (shorter text recommended for testing)
     * @param voiceId Voice ID to test
     * @param apiKey MiniMax API key
     * @returns Promise<ArrayBuffer>
     */
    testVoice(text: string, voiceId: string, apiKey: string): Promise<ArrayBuffer>;
    /**
     * Full production audio synthesis
     * Requires API key, voice ID, and GroupId
     * @param input Talk object
     * @param speaker Voice ID
     * @param apiKey MiniMax API key
     * @param voiceActor Not used for MiniMax (for interface compatibility)
     * @returns Promise<ArrayBuffer>
     */
    fetchAudio(input: Talk, speaker: string, apiKey?: string, voiceActor?: any): Promise<ArrayBuffer>;
    /**
     * Audio synthesis with flexible GroupId requirement
     * @param input Talk object
     * @param speaker Voice ID
     * @param apiKey MiniMax API key
     * @param requireGroupId Whether to require GroupId (default: true)
     * @returns Promise<ArrayBuffer>
     */
    fetchAudioWithOptions(input: Talk, speaker: string, apiKey?: string, requireGroupId?: boolean): Promise<ArrayBuffer>;
    /**
     * Check if GroupId is configured
     * @returns boolean
     */
    hasGroupId(): boolean;
    /**
     * Get current endpoint setting
     * @returns MinimaxEndpoint
     */
    getEndpoint(): MinimaxEndpoint;
    /**
     * Set custom API endpoint URL (VoiceEngine interface compatibility)
     * @param apiUrl custom API endpoint URL
     */
    setApiEndpoint(apiUrl: string): void;
    /**
     * Get voice settings based on emotion
     * @param emotion Emotion type
     * @returns Voice settings
     */
    private getVoiceSettings;
    /**
     * Merge incoming voice overrides into the current override map
     * Passing undefined removes the override and falls back to defaults
     * @param settings Voice setting overrides
     */
    private updateVoiceOverrides;
    /**
     * Merge incoming audio overrides into the current override map
     * Passing undefined removes the override and falls back to defaults
     * @param settings Audio setting overrides
     */
    private updateAudioOverrides;
    /**
     * Convert hex string to ArrayBuffer
     * @param hex Hex string
     * @returns ArrayBuffer
     */
    private hexToArrayBuffer;
    getTestMessage(textVoiceText?: string): string;
}