Live Events API Overview

The Live Events API provides real-time access to audio events detected by the Deeply system. This API uses a WebSocket connection to stream event data continuously, allowing clients to monitor events as they happen in real-time.

WebSocket Endpoint#

ws://localhost:8100/api/v1/ws

• Protocol: WebSocket (ws)

This page uses the local default host shown throughout the reference.

Clients can connect to this WebSocket endpoint to receive live events in real time. Each event received through this endpoint follows the Event object structure, providing comprehensive information about the detected audio event.

Event Data Format#

Each WebSocket message contains a JSON object with the following structure:

id#

• Type: string
• Description: Unique identifier for the event

label#

• Type: object
• Description: Classification information of the detected sound
  • id (string): Unique identifier of the sound label
  • name (object): Localized names of the label
    • ko (string): Korean name
    • en (string): English name

confidence#

• Type: float
• Description: Confidence score of the detection (0.0 to 1.0)

mic#

• Type: object
• Description: Information about the recording device
  • id (string): Unique identifier of the microphone
  • name (string): Name of the microphone
  • location (object): Geographic location of the device
    • latitude (number): Latitude coordinate
    • longitude (number): Longitude coordinate

noises#

• Type: Array[float]
• Description: Array of sound pressure level (SPL) measurements in decibels (dB)
• Details:
  • Each value represents the SPL measured at 0.1-second intervals
  • For a 2-second audio clip, the array will contain 20 measurements
  • Values typically range from 30 dB (very quiet) to 120 dB (very loud)
  • Useful for analyzing sound intensity patterns over the duration of the event

Example Response#

{
  "id": "23d6ec74155f4eb187b4e7301b71b5d9",
  "label": {
    "id": "normal_speech_female",
    "name": {
      "ko": "대화(여성)",
      "en": "normal speech female"
    }
  },
  "confidence": 0.426632,
  "mic": {
    "id": "d00c8e3364a34439183e3462e773354a1",
    "name": "Example Mic (715)",
    "location": {
      "latitude": 37.546344,
      "longitude": 126.944322
    }
  },
  "noises": [
    66.99,
    65.28,
    68.21,
    68.12,
    67.56,
    70.66,
    67.35,
    63.42,
    59.98,
    64.05,
    65.86,
    62.88,
    62.41,
    62.59,
    61.96,
    59.25,
    58.16,
    59.75,
    64.2,
    65.15
  ]
}

In this example, the noises array contains 20 measurements over a 2-second period, with values ranging from approximately 58 dB to 71 dB, indicating moderate sound levels typical of normal speech.