Skip to content

API_REFERENCE.md

Latest commit

 

History

History
179 lines (153 loc) · 5.8 KB

API_REFERENCE.md

File metadata and controls

179 lines (153 loc) · 5.8 KB

API Reference

Last Updated: December 11, 2025 - Reflects Phase 4 completion and current system capabilities

This document provides detailed documentation for all REST endpoints and WebSocket events in the Enhanced Metal Detector AI Web Portal running on port 5002.

REST Endpoints

Dashboard

  • GET /
    Description: Renders the main dashboard page showing system overview and quick stats.
    Response: HTML template (dashboard.html)

Classify

  • GET /classify
    Description: Renders the classification page for file upload and microphone recording.
    Response: HTML template (classify.html)

  • POST /api/upload
    Description: Uploads and classifies an audio file.
    Parameters:

    • file: Audio file (multipart/form-data, supports WAV, MP3, M4A)
      Response: JSON
      Example:
    {
  "success": true,
  "filename": "sample.wav",
  "predicted_label": "gold",
  "confidence": 0.95,
  "processing_time": 1.23,
  "all_probabilities": {"gold": 0.95, "iron": 0.04, "other": 0.01},
  "model_votes": {"CNN": "gold", "TRANSFORMER": "gold", "TRADITIONAL": "gold"},
  "waveform": [0.1, 0.2, ...],
  "sample_rate": 22050,
  "duration": 5.0,
  "timestamp": "2024-09-10T12:00:00"
}

  • POST /api/quick-classify (CSRF exempt)
    Description: Classifies a quick audio chunk (used for real-time streaming).
    Parameters:

    • audio: Array of audio samples (JSON)
    • sample_rate: Integer (optional, default 22050)
      Response: JSON
      Example:
    {
  "success": true,
  "predicted_label": "iron",
  "confidence": 0.85,
  "all_probabilities": {"gold": 0.10, "iron": 0.85, "other": 0.05}
}

Realtime

  • GET /realtime
    Description: Renders the real-time streaming and classification page.
    Response: HTML template (realtime.html)

Analytics

  • GET /analytics
    Description: Renders the analytics page with charts and insights.
    Response: HTML template (analytics.html)

  • GET /api/analytics/model-performance
    Description: Retrieves model performance metrics for visualization.
    Response: JSON with metrics data (accuracy, precision, recall, etc.)

Dataset

  • GET /dataset
    Description: Renders the dataset management page.
    Response: HTML template (dataset.html)

  • GET /api/dataset/info
    Description: Gets dataset statistics including event detection counts.
    Response: JSON
    Example:

    {
  "total_files": 100,
  "total_events": 250,
  "classes": {
    "gold": {"files": 40, "events": 100},
    "iron": {"files": 30, "events": 80}
  }
}

  • POST /api/dataset/upload
    Description: Uploads new audio samples to the dataset.
    Parameters:

    • file: Audio file
    • class_label: String (target class)
      Response: JSON success message

  • POST /api/dataset/augment
    Description: Applies data augmentation to the dataset.
    Parameters (JSON):

    • techniques: Object (e.g., {"time_stretch": true, "pitch_shift": true})
    • factor: Integer (augmentation multiplier)
    • target_classes: Array or 'all'
      Response: JSON success message with details

  • POST /api/dataset/balance
    Description: Balances dataset classes by oversampling/undersampling.
    Response: JSON with original and new distributions

  • GET /api/dataset/export
    Description: Exports the entire dataset as a ZIP file including metadata.
    Response: ZIP file attachment

Training

  • GET /training
    Description: Renders the model training management page.
    Response: HTML template (training.html)

  • POST /api/training/start
    Description: Starts a new model training session.
    Parameters (JSON): config object with epochs, batch_size, etc.
    Response: JSON success message

  • GET /api/training/status
    Description: Gets current training status and progress.
    Response: JSON with status, progress, metrics

Other

  • GET /api/waveform/path:audio_path
    Description: Generates waveform data for visualization.
    Parameters: audio_path (string)
    Response: JSON with downsampled waveform array

  • GET /health
    Description: System health check endpoint.
    Response: JSON
    Example:

    {
  "status": "healthy",
  "models_loaded": true,
  "timestamp": "2024-09-10T12:00:00"
}

WebSocket Events

Namespace: SocketIO (used for real-time communication)

Client → Server

  • connect - Establishes WebSocket connection
  • disconnect - Closes connection (automatically cleans up active streams)
  • start_stream - Starts audio streaming session
    Parameters: None (session_id auto-generated)
    Response: stream_started event
  • audio_data - Sends audio chunk for processing
    Parameters: { audio: float32[], sampleRate: number }
    Note: Audio is buffered and processed every 2 seconds
  • stop_stream - Stops streaming session
    Parameters: None (uses current session)
    Response: stream_stopped event

Server → Client

  • stream_started - Confirms streaming session started
    Data: { message: "Audio streaming started" }
  • stream_stopped - Confirms streaming session stopped
    Data: { message: "Audio streaming stopped" }
  • classification_result - Real-time classification result
    Data: { predicted_label, confidence, timestamp, all_probabilities }
  • training_update - Training progress update
    Data: { progress, metrics, status }
  • stream_error - Error during streaming
    Data: { error: message }

Recent WebSocket Improvements

  • Session Management: Automatic cleanup on disconnect, prevents orphaned streams
  • Error Handling: Graceful handling of duplicate stop events and session conflicts
  • Performance: Optimized threading mode for better PyTorch compatibility
  • Stability: Fixed "Invalid frame header" errors and connection issues