TTS Status API Documentation

This document describes the new status tracking endpoints that provide real-time information about TTS processing.

Overview

The status API allows you to monitor TTS request processing in real-time, view progress information, check statistics, and review request history.

Endpoints

🔍 GET /status

Get comprehensive TTS processing status information.

Query Parameters:

• include_memory (boolean): Include memory usage information
• include_history (boolean): Include recent request history
• include_stats (boolean): Include processing statistics
• history_limit (integer): Number of history records to return (1-20)

Example:

curl "http://localhost:4123/status?include_memory=true&include_stats=true"

Response:

{
  "status": "generating_audio",
  "is_processing": true,
  "request_id": "abc12345",
  "start_time": 1704067200.0,
  "duration_seconds": 2.5,
  "text_length": 156,
  "text_preview": "This is the text being processed...",
  "voice_source": "default",
  "parameters": {
    "exaggeration": 0.7,
    "cfg_weight": 0.5,
    "temperature": 0.8
  },
  "progress": {
    "current_chunk": 2,
    "total_chunks": 4,
    "current_step": "Generating audio for chunk 2/4",
    "progress_percentage": 50.0,
    "estimated_completion": 1704067205.0
  },
  "total_requests": 42
}

⚡ GET /status/progress

Get lightweight progress information (optimized for polling).

Example:

curl "http://localhost:4123/status/progress"

Response when processing:

{
  "is_processing": true,
  "status": "generating_audio",
  "current_step": "Generating audio for chunk 2/4",
  "current_chunk": 2,
  "total_chunks": 4,
  "progress_percentage": 50.0,
  "duration_seconds": 2.5,
  "estimated_completion": 1704067205.0,
  "text_preview": "This is the text being processed..."
}

Response when idle:

{
  "is_processing": false,
  "status": "idle",
  "message": "No active TTS requests"
}

📊 GET /status/statistics

Get comprehensive processing statistics.

Query Parameters:

• include_memory (boolean): Include current memory usage

Example:

curl "http://localhost:4123/status/statistics?include_memory=true"

Response:

{
  "total_requests": 42,
  "completed_requests": 38,
  "error_requests": 4,
  "success_rate": 90.5,
  "average_duration_seconds": 3.2,
  "average_text_length": 124.5,
  "is_processing": false,
  "current_memory": {
    "cpu_memory_mb": 256.7,
    "gpu_memory_allocated_mb": 1024.3
  }
}

📝 GET /status/history

Get recent TTS request history.

Query Parameters:

• limit (integer): Number of records to return (1-50, default: 10)

Example:

curl "http://localhost:4123/status/history?limit=5"

Response:

{
  "request_history": [
    {
      "request_id": "abc12345",
      "status": "completed",
      "start_time": 1704067200.0,
      "end_time": 1704067203.5,
      "duration_seconds": 3.5,
      "text_length": 156,
      "text_preview": "Hello world, this is a test...",
      "voice_source": "default",
      "parameters": {
        "exaggeration": 0.7,
        "cfg_weight": 0.5,
        "temperature": 0.8
      }
    }
  ],
  "total_records": 5,
  "limit": 5
}

🗑️ POST /status/history/clear

Clear TTS request history.

Query Parameters:

• confirm (boolean): Required confirmation flag

Example:

curl -X POST "http://localhost:4123/status/history/clear?confirm=true"

📋 GET /info

Get comprehensive API information including status, memory, and statistics.

Example:

curl "http://localhost:4123/info"

Response:

{
  "api_name": "Chatterbox TTS API",
  "version": "1.0.0",
  "status": "operational",
  "tts_status": {
    /* current status */
  },
  "statistics": {
    /* processing stats */
  },
  "memory_info": {
    /* memory usage */
  },
  "recent_requests": [
    /* last 3 requests */
  ],
  "uptime_info": {
    "total_requests": 42,
    "success_rate": 90.5,
    "is_processing": false
  }
}

Status Values

The status field can have these values:

• idle: No active requests
• initializing: Starting request processing
• processing_text: Validating and preparing text
• chunking: Splitting text into chunks
• generating_audio: Generating audio for chunks
• concatenating: Combining audio chunks
• finalizing: Converting to output format
• completed: Request completed successfully
• error: Request failed with error

Endpoint Aliases

All endpoints support multiple path formats for compatibility:

Primary Path	Aliases
/status	/v1/status, /processing, /processing/status
/status/progress	/v1/status/progress, /progress
/status/history	/v1/status/history, /history
/status/statistics	/v1/status/statistics, /stats
/info	/v1/info, /api/info

Frontend Integration

Real-time Progress Monitoring

import { createTTSService } from './services/tts';

const ttsService = createTTSService('http://localhost:4123');

// Monitor progress during generation
const monitorProgress = async () => {
  const interval = setInterval(async () => {
    try {
      const progress = await ttsService.getProgress();
      if (progress.is_processing) {
        console.log(`Progress: ${progress.progress_percentage}%`);
        console.log(`Step: ${progress.current_step}`);
      } else {
        clearInterval(interval);
        console.log('Processing complete');
      }
    } catch (error) {
      console.error('Failed to get progress:', error);
    }
  }, 1000);
};

React Hook Example

import { useQuery } from '@tanstack/react-query';

const useProcessingStatus = () => {
  return useQuery({
    queryKey: ['tts-status'],
    queryFn: () => ttsService.getProgress(),
    refetchInterval: 1000, // Poll every second
    enabled: true,
  });
};

// Usage in component
const { data: status } = useProcessingStatus();
if (status?.is_processing) {
  // Show progress UI
}

Testing

Run the status endpoint tests:

python tests/test_status.py

This will test:

• ✅ All status endpoints
• 🎤 Status tracking during TTS generation
• 🔄 Concurrent request handling
• 📊 Real-time progress monitoring

Notes

• Status information is thread-safe for concurrent requests
• Progress percentages are calculated based on chunk processing
• Memory information requires memory monitoring to be enabled
• History is limited to the last 10 requests by default
• Estimated completion times are calculated based on current progress

Error Handling

All endpoints return appropriate HTTP status codes:

• 200: Success
• 400: Bad request (invalid parameters)
• 500: Internal server error

Error responses follow this format:

{
  "error": {
    "message": "Error description",
    "type": "error_type"
  }
}