Submit Speech Generation Task

Instructions

Implementation Reference

• src/index.ts:89-120 (registration)

  Tool registration for 'submit_speech_generation' via server.registerTool(), with title, description, and inputSchema from textToSpeechSchema.

  // Text-to-speech tool
  server.registerTool(
    "submit_speech_generation",
    {
      title: "Submit Speech Generation Task", 
      description: "Convert text to speech asynchronously. RECOMMENDED: Submit multiple tasks in batch to saturate rate limits, then call task_barrier once to wait for all completions. Returns task ID only - actual files available after task_barrier.",
      inputSchema: textToSpeechSchema.shape
    },
    async (params: unknown): Promise<ToolResponse> => {
      try {
        const validatedParams = validateTTSParams(params);
        const { taskId } = await taskManager.submitTTSTask(async () => {
          return await ttsService.generateSpeech(validatedParams);
        });
  
        return {
          content: [{
            type: "text",
            text: `Task ${taskId} submitted`
          }]
        };
      } catch (error: any) {
        ErrorHandler.logError(error, { tool: 'submit_speech_generation', params });
        return {
          content: [{
            type: "text",
            text: `❌ Failed to submit TTS task: ${ErrorHandler.formatErrorForUser(error)}`
          }]
        };
      }
    }
  );

• src/index.ts:97-120 (handler)

  Handler function that validates params via validateTTSParams, submits async TTS task via taskManager.submitTTSTask calling ttsService.generateSpeech, and returns task ID.

    async (params: unknown): Promise<ToolResponse> => {
      try {
        const validatedParams = validateTTSParams(params);
        const { taskId } = await taskManager.submitTTSTask(async () => {
          return await ttsService.generateSpeech(validatedParams);
        });
  
        return {
          content: [{
            type: "text",
            text: `Task ${taskId} submitted`
          }]
        };
      } catch (error: any) {
        ErrorHandler.logError(error, { tool: 'submit_speech_generation', params });
        return {
          content: [{
            type: "text",
            text: `❌ Failed to submit TTS task: ${ErrorHandler.formatErrorForUser(error)}`
          }]
        };
      }
    }
  );

• src/config/schemas.ts:72-141 (schema)

  Input schema (textToSpeechSchema) defining all TTS parameters: text, outputFile, highQuality, voiceId, speed, volume, pitch, emotion, format, sampleRate, bitrate, languageBoost, intensity, timbre, sound_effects.

  export const textToSpeechSchema = z.object({
    text: z.string()
      .min(1, 'Text is required')
      .max(CONSTRAINTS.TTS.TEXT_MAX_LENGTH, `Text to convert to speech. Max ${CONSTRAINTS.TTS.TEXT_MAX_LENGTH} characters. Use newlines for paragraph breaks. For custom pauses, insert <#x#> where x is seconds (0.01-99.99, max 2 decimals). Pause markers must be between pronounceable text and cannot be consecutive`),
      
    outputFile: filePathSchema.describe('Absolute path for audio file'),
    
    highQuality: z.boolean()
      .default(false)
      .describe('Use high-quality model (speech-2.8-hd) for audiobooks/premium content. Default: false (uses faster speech-2.8-turbo)'),
      
    voiceId: z.enum(Object.keys(VOICES) as [VoiceId, ...VoiceId[]])
      .default('female-shaonv' as VoiceId)
      .describe(`Voice ID for speech generation. Available voices: ${Object.keys(VOICES).map(id => `${id} (${VOICES[id as VoiceId]?.name || id})`).join(', ')}`),
      
    speed: z.number()
      .min(CONSTRAINTS.TTS.SPEED_MIN)
      .max(CONSTRAINTS.TTS.SPEED_MAX)
      .default(1.0)
      .describe(`Speech speed multiplier (${CONSTRAINTS.TTS.SPEED_MIN}-${CONSTRAINTS.TTS.SPEED_MAX}). Higher values = faster speech`),
      
    volume: z.number()
      .min(CONSTRAINTS.TTS.VOLUME_MIN)
      .max(CONSTRAINTS.TTS.VOLUME_MAX)
      .default(1.0)
      .describe(`Audio volume level (${CONSTRAINTS.TTS.VOLUME_MIN}-${CONSTRAINTS.TTS.VOLUME_MAX}). Higher values = louder audio`),
      
    pitch: z.number()
      .min(CONSTRAINTS.TTS.PITCH_MIN)
      .max(CONSTRAINTS.TTS.PITCH_MAX)
      .default(0)
      .describe(`Pitch adjustment in semitones (${CONSTRAINTS.TTS.PITCH_MIN} to ${CONSTRAINTS.TTS.PITCH_MAX}). Negative = lower pitch, Positive = higher pitch`),
      
    emotion: z.enum(CONSTRAINTS.TTS.EMOTIONS as readonly [Emotion, ...Emotion[]])
      .default('neutral' as Emotion)
      .describe(`Emotional tone of the speech. Options: ${CONSTRAINTS.TTS.EMOTIONS.join(', ')}`),
      
    format: z.enum(CONSTRAINTS.TTS.FORMATS as readonly [AudioFormat, ...AudioFormat[]])
      .default('mp3' as AudioFormat)
      .describe(`Output audio format. Options: ${CONSTRAINTS.TTS.FORMATS.join(', ')}`),
      
    sampleRate: z.enum(CONSTRAINTS.TTS.SAMPLE_RATES as readonly [SampleRate, ...SampleRate[]])
      .default("32000" as SampleRate)
      .describe(`Audio sample rate in Hz. Options: ${CONSTRAINTS.TTS.SAMPLE_RATES.join(', ')}`),
      
    bitrate: z.enum(CONSTRAINTS.TTS.BITRATES as readonly [Bitrate, ...Bitrate[]])
      .default("128000" as Bitrate)  
      .describe(`Audio bitrate in bps. Options: ${CONSTRAINTS.TTS.BITRATES.join(', ')}`),
      
    languageBoost: z.string().default('auto').describe('Enhance recognition for specific languages/dialects. Options: Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans, auto. Use "auto" for automatic detection'),
  
    
    intensity: z.number()
      .int()
      .min(CONSTRAINTS.TTS.VOICE_MODIFY_INTENSITY_MIN)
      .max(CONSTRAINTS.TTS.VOICE_MODIFY_INTENSITY_MAX)
      .optional()
      .describe('Voice intensity adjustment (-100 to 100). Values closer to -100 make voice more robust, closer to 100 make voice softer'),
      
    timbre: z.number()
      .int()
      .min(CONSTRAINTS.TTS.VOICE_MODIFY_TIMBRE_MIN)
      .max(CONSTRAINTS.TTS.VOICE_MODIFY_TIMBRE_MAX)
      .optional()
      .describe('Voice timbre adjustment (-100 to 100). Values closer to -100 make voice more mellow, closer to 100 make voice more crisp'),
      
    sound_effects: z.enum(CONSTRAINTS.TTS.SOUND_EFFECTS as readonly [SoundEffect, ...SoundEffect[]])
      .optional()
      .describe(getSoundEffectsDescription())
  });

• src/config/schemas.ts:338-348 (helper)

  validateTTSParams function that parses and validates TTS parameters using textToSpeechSchema.

  export function validateTTSParams(params: unknown): TextToSpeechParams {
    try {
      return textToSpeechSchema.parse(params);
    } catch (error) {
      if (error instanceof z.ZodError) {
        const messages = error.errors.map(e => `${e.path.join('.')}: ${e.message}`);
        throw new Error(`Validation failed: ${messages.join(', ')}`);
      }
      throw error;
    }
  }

• src/services/tts-service.ts:60-78 (handler)

  TextToSpeechService.generateSpeech method that builds API payload, makes request to text-to-speech endpoint, processes response, and saves audio file.

  async generateSpeech(params: TextToSpeechParams): Promise<TTSResult> {
    try {
      // Build API payload (MCP handles validation)
      const payload = this.buildPayload(params);
      
      // Make API request
      const response = await this.post(API_CONFIG.ENDPOINTS.TEXT_TO_SPEECH, payload) as TTSResponse;
      
      // Process response
      return await this.processTTSResponse(response, params);
      
    } catch (error: any) {
      const processedError = ErrorHandler.handleAPIError(error);
      ErrorHandler.logError(processedError, { service: 'tts', params });
      
      // Throw the error so task manager can properly mark it as failed
      throw processedError;
    }
  }