synthesize_speech
Convert text to audio using customizable voice, speed, emotion, and pacing for expressive and professional speech synthesis in multiple formats.
Instructions
Convert text to speech with advanced voice controls and natural expression
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| emotion | No | Voice emotion | neutral |
| filename | No | Custom filename for saved audio | |
| outputFormat | No | Audio output format | wav |
| pacing | No | Speech pacing style | natural |
| saveFile | No | Save audio to file | |
| speed | No | Speech speed (0.25-3.0) | |
| text | Yes | Text to convert to speech | |
| voiceId | No | Voice to use for synthesis | af_heart |
| volume | No | Audio volume (0.1-2.0) |
Implementation Reference
- src/typescript/index.ts:236-341 (handler)Main handler function for synthesize_speech tool. Validates inputs, enhances text for natural speech, calculates adjusted speed, and orchestrates native TTS synthesis.
async synthesizeSpeech(params: { text: string; voiceId?: string; speed?: number; emotion?: keyof typeof VoiceEmotions; pacing?: keyof typeof PacingStyles; volume?: number; outputFormat?: string; saveFile?: boolean; filename?: string; }) { const { text, voiceId = this.config.defaultVoice, speed = this.config.defaultSpeed, emotion = this.config.defaultEmotion as keyof typeof VoiceEmotions, pacing = this.config.defaultPacing as keyof typeof PacingStyles, volume = 1.0, outputFormat = 'wav', saveFile = this.config.enableFileOutput, filename } = params; // Ensure TTS engine is initialized await this.ensureInitialized(); // Input validation and sanitization if (!text || typeof text !== 'string') { throw new Error('Text must be a non-empty string'); } if (text.length > this.config.maxTextLength) { throw new Error(`Text length (${text.length}) exceeds maximum allowed (${this.config.maxTextLength})`); } // Validate voice ID if (voiceId && !Object.keys(AvailableVoices).includes(voiceId)) { throw new Error(`Invalid voice ID: ${voiceId}`); } // Validate speed range if (speed < 0.25 || speed > 3.0) { throw new Error(`Speed ${speed} out of range (0.25-3.0)`); } // Validate volume range if (volume < 0.1 || volume > 2.0) { throw new Error(`Volume ${volume} out of range (0.1-2.0)`); } // Validate output format if (!AudioFormats.includes(outputFormat as any)) { throw new Error(`Unsupported output format: ${outputFormat}`); } // Sanitize text input const sanitizedText = text .replace(/[<>]/g, '') // Remove HTML-like tags .replace(/[\x00-\x1F\x7F]/g, '') // Remove control characters .trim(); if (!sanitizedText) { throw new Error('Text is empty after sanitization'); } // Enhance text for natural speech const enhancedText = this.enhanceTextForSpeech(sanitizedText, emotion, pacing); // Calculate final speed const finalSpeed = this.calculateFinalSpeed(speed, emotion, pacing); // Synthesize using native TypeScript TTS engine const result = await this.synthesizeWithNativeTTS( enhancedText, voiceId, finalSpeed, emotion, pacing, volume, outputFormat, saveFile, filename ); if (result.success) { this.activeRequests.set(result.requestId, { status: 'completed', result }); return { success: true, requestId: result.requestId, duration: result.duration, voiceUsed: voiceId, speedUsed: finalSpeed, emotion, pacing, outputFormat, filePath: saveFile ? result.audioPath : undefined, message: `Successfully synthesized ${text.length} characters with ${voiceId} voice` }; } else { throw new Error(result.error || 'Synthesis failed'); } } - src/typescript/index.ts:569-630 (registration)Tool registration in MCP ListTools handler defining name, description, and input schema.
{ name: 'synthesize_speech', description: 'Convert text to speech with advanced voice controls and natural expression', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to convert to speech', maxLength: config.maxTextLength, }, voiceId: { type: 'string', description: 'Voice to use for synthesis', enum: Object.keys(AvailableVoices), default: config.defaultVoice, }, speed: { type: 'number', description: 'Speech speed (0.25-3.0)', minimum: 0.25, maximum: 3.0, default: config.defaultSpeed, }, emotion: { type: 'string', description: 'Voice emotion', enum: Object.keys(VoiceEmotions), default: config.defaultEmotion, }, pacing: { type: 'string', description: 'Speech pacing style', enum: Object.keys(PacingStyles), default: config.defaultPacing, }, volume: { type: 'number', description: 'Audio volume (0.1-2.0)', minimum: 0.1, maximum: 2.0, default: 1.0, }, outputFormat: { type: 'string', description: 'Audio output format', enum: [...AudioFormats], default: 'wav', }, saveFile: { type: 'boolean', description: 'Save audio to file', default: config.enableFileOutput, }, filename: { type: 'string', description: 'Custom filename for saved audio', }, }, required: ['text'], }, }, - src/typescript/index.ts:739-757 (handler)MCP CallToolRequestSchema handler case that receives tool call and invokes the synthesizeSpeech implementation.
case 'synthesize_speech': const result = await ttsServer.synthesizeSpeech(args as any); return { content: [ { type: 'text', text: `🎙️ **TTS Synthesis Complete**\n\n` + `**Request ID:** ${result.requestId}\n` + `**Voice:** ${result.voiceUsed} (${AvailableVoices[result.voiceUsed as keyof typeof AvailableVoices]?.name})\n` + `**Duration:** ${result.duration?.toFixed(2)}s\n` + `**Speed:** ${result.speedUsed?.toFixed(2)}x\n` + `**Emotion:** ${result.emotion}\n` + `**Pacing:** ${result.pacing}\n` + `**Format:** ${result.outputFormat.toUpperCase()}\n` + `${result.filePath ? `**File:** ${result.filePath}\n` : ''}` + `\n${result.message}`, }, ], }; - src/typescript/index.ts:573-628 (schema)JSON schema for synthesize_speech tool inputs including all parameters and validation rules.
type: 'object', properties: { text: { type: 'string', description: 'Text to convert to speech', maxLength: config.maxTextLength, }, voiceId: { type: 'string', description: 'Voice to use for synthesis', enum: Object.keys(AvailableVoices), default: config.defaultVoice, }, speed: { type: 'number', description: 'Speech speed (0.25-3.0)', minimum: 0.25, maximum: 3.0, default: config.defaultSpeed, }, emotion: { type: 'string', description: 'Voice emotion', enum: Object.keys(VoiceEmotions), default: config.defaultEmotion, }, pacing: { type: 'string', description: 'Speech pacing style', enum: Object.keys(PacingStyles), default: config.defaultPacing, }, volume: { type: 'number', description: 'Audio volume (0.1-2.0)', minimum: 0.1, maximum: 2.0, default: 1.0, }, outputFormat: { type: 'string', description: 'Audio output format', enum: [...AudioFormats], default: 'wav', }, saveFile: { type: 'boolean', description: 'Save audio to file', default: config.enableFileOutput, }, filename: { type: 'string', description: 'Custom filename for saved audio', }, }, required: ['text'], - src/typescript/native-tts.ts:74-108 (helper)NativeTTSEngine.synthesizeText - Low-level TTS synthesis called by main handler to produce raw audio data.
async synthesizeText( text: string, voiceConfig: VoiceConfig, outputFormat: string = 'wav' ): Promise<SynthesisResult> { const requestId = randomUUID(); try { await this.initialize(); // Validate inputs if (!text || text.length === 0) { throw new Error('Text cannot be empty'); } if (text.length > 50000) { throw new Error(`Text too long: ${text.length} characters (max 50000)`); } // Simulate neural TTS synthesis const audioSegment = await this.generateAudioSegment(text, voiceConfig); return { success: true, audioSegment, requestId }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error), requestId }; }