Skip to main content

Directional audio detection API

Overview​

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Description​

The VAPIX® Directional audio detection API makes it possible to configure the directional audio detection, PTZ calibration, PTZ control and fisheye overlays.

Use cases​

Get root entity​

Use root entity to check all settings.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "audioEvents": [],
        "baseSettings": {
            "detectionThreshold": 3,
            "dwellTime": 2,
            "enabled": false,
            "envReset": true,
            "windDetect": true
        },
        "ptzControl": {
            "calibration": {
                "defaultTilt": {
                    "value": -25
                },
                "panOffset": {
                    "manuallyCalibrated": false,
                    "preCalibrated": true,
                    "value": 35
                }
            },
            "enabled": false,
            "useVisualObjects": false
        },
        "adm": {
            "viewareaTimeout": 300
        },
        "fisheyeOverlay": {
            "enabled": false
        }
    }
}

Enable directional audio detection​

Set the enabled property for directional audio detection to trigger on loud noises.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/baseSettings/enabled \
  --data '{
    "data": true
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Check the property if directional audio detection is enabled.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/baseSettings/enabled
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": false
}

Set the threshold​

Set the threshold (dB) to change the sensitivity of directional audio detection.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/baseSettings/detectionThreshold \
  --data '{
    "data": 8
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Check the current threshold.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/baseSettings/detectionThreshold
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": 8
}

Audio events​

Check the audioEvents entity to retrieve a list of up to 1000 of the latest audio events. Each audio event is of the AudioEventData data type. Theta and phi angles are relative to the mechanical housing of the detecting device. Phi is measured from the positive z-axis and theta on the xy-plane from the positive x-axis. The zero position of the theta is device dependent. Pan and tilt angles are converted from theta and phi angles in the PTZ space.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/audioEvents
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "level": 3.610333,
            "pan": -176,
            "phi": 96.511383,
            "phiValid": true,
            "theta": 211.468811,
            "threshold": 3,
            "tilt": -6,
            "timestamp": 1728292599
        },
        {
            "id": 2,
            "level": 3.530529,
            "pan": 104,
            "phi": 117.775993,
            "phiValid": true,
            "theta": 291.027374,
            "threshold": 3,
            "tilt": -27,
            "timestamp": 1728292720
        },
        {
            "id": 3,
            "level": 3.447409,
            "pan": -149,
            "phi": 0,
            "phiValid": false,
            "theta": 184.536667,
            "threshold": 3,
            "tilt": -25,
            "timestamp": 1728292961
        }
    ]
}

PTZ control​

Check the ptzControl_supported property to determine if the device supports PTZ control.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl_supported
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": true
}

If support for PTZ control is found, the ptzControl entity can be read.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "calibration": {
            "defaultTilt": {
                "value": -25
            },
            "panOffset": {
                "manuallyCalibrated": false,
                "preCalibrated": true,
                "value": 35
            }
        },
        "enabled": false,
        "useVisualObjects": false
    }
}

Default tilt​

When the directional audio detection detects a sound, a tilt angle is not always available. When that is the case, the default tilt value will be used when directing the PTZ. It can be calibrated by manually directing the PTZ to the desired tilt angle and saved with:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/defaultTilt/save \
  --data '{
    "data": {}
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {}
}

The current default tilt angle can be read with:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/defaultTilt/value
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": -25
}

Pan offset​

The pan offset between the device and a PTZ camera has to be calibrated. Some PTZ models are pre-calibrated, while others require manual calibration. To find out if a calibration is necessary, check the preCalibrated property of the panOffset entity:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/panOffset
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "manuallyCalibrated": false,
        "preCalibrated": true,
        "value": 35
    }
}

If preCalibrated is true, the calibration has already been done and no other action is required. It is still possible to perform a manual calibration. This is done by manually directing the PTZ to point in the same direction as the device's pan zero angle and save the value with:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  "http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/panOffset/save'" \
  --data '{
    "data": {}
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {}
}

It is possible to revert back to a pre-calibrated value even if preCalibrated is true and a manual calibration has been done by using a reset command. It will have no effect if preCalibrated is false.

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  "http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/panOffset/reset'" \
  --data '{
    "data": {}
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {}
}

The calibrated value can always be read with:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/ptzControl/calibration/panOffset/value
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": 35
}

Audio Detection Multiview (ADM)​

Check the adm_supported property to determine if the device supports ADM.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/adm_supported
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": true
}

If support for ADM exist, the adm property can be read:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/adm
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "viewareaTimeout": 300
    }
}

ADM view area timeout​

The viewareaTimeout property controls the time after an audio event where the corresponding view area turns black.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/adm/viewareaTimeout \
  --data '{
    "data": 300
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Check the current timeout:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/adm/viewareaTimeout
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": 300
}

Fisheye overlay​

Check the fisheyeOverlay_supported property to determine if the device supports fisheye overlays.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/fisheyeOverlay_supported
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": true
}

If support exists for fisheye overlays, the fisheyeOverlay entity can be read.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/fisheyeOverlay
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "enabled": false
    }
}

Enable fisheye overlays​

The enabled property has to be set before fisheye overlays can start drawing sound makers in the stream from loud noises.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/fisheyeOverlay/enabled \
  --data '{
    "data": true
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Check the enabled property if FisheyeOverlay is enabled.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/directional-audio-detection/v2/fisheyeOverlay/enabled
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": false
}

API definition​

Structure​

directional-audio-detection.v2 (Root Entity)
    ├── audioEvents (Property)
    ├── adm_supported (Property)
    ├── fisheyeOverlay_supported (Property)
    ├── ptzControl_supported (Property)
    ├── adm (Entity)
        ├── viewareaTimeout (Property)
    ├── baseSettings (Entity)
        ├── detectionThreshold (Property)
        ├── dwellTime (Property)
        ├── enabled (Property)
        ├── windDetect (Property)
        ├── testEvent (Action)
    ├── fisheyeOverlay (Entity)
        ├── enabled (Property)
    ├── ptzControl (Entity)
        ├── enabled (Property)
        ├── useVisualObjects (Property)
        ├── calibration (Entity)
            ├── defaultTilt (Entity)
                ├── value (Property)
                ├── save (Action)
            ├── panOffset (Entity)
                ├── manuallyCalibrated (Property)
                ├── preCalibrated (Property)
                ├── value (Property)
                ├── reset (Action)
                ├── save (Action)

Entities​

directional-audio-detection.v2​

  • Description: The configuration of Directional Audio Detection
  • Type: Singleton
  • Operations
    • GET
    • SET
  • Attributes
    • Dynamic Support: No
Properties​
audioEvents​
  • Description: Audio events
  • Datatype: AudioEventsData
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

This entity contains up to 1000 of the latest detected audio events.

adm_supported​
  • Description:
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
fisheyeOverlay_supported​
  • Description:
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
ptzControl_supported​
  • Description:
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

directional-audio-detection.v2.adm​

  • Description: Entity for Audio Detection Multiview
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: Yes

This entity contains a property that sets the ADM view area timeout. ADM is the capability in the DAD2 service that centers the view areas in the ADM stream around the angle provided by audio detection.

Properties​
viewareaTimeout​
  • Description: Time (s) before the contents of a view area is considered obsolete
  • Datatype: ViewareaTimeout
  • Operations
    • GET (Permissions: admin, operator)
    • SET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

directional-audio-detection.v2.baseSettings​

  • Description: Entity for base settings for Directional Audio Detection
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No

This is the entity that contains properties for configuring audio detection.

Properties​
detectionThreshold​
  • Description: The threshold (dB) for detecting a sound
  • Datatype: DetectionThreshold
  • Operations
    • GET (Permissions: admin)
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
dwellTime​
  • Description: The minimum time (s) before detecting a new sound
  • Datatype: DwellTime
  • Operations
    • GET (Permissions: admin)
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
enabled​
  • Description: Turn on or off the Directional Audio Detection
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
    • SET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
windDetect​
  • Description: Detects if an audio event is wind or not. Should be on outdoors, and off indoors.
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin)
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
testEvent​
  • Description: Generate a test event
  • Request Datatype: EmptyObject
  • Response Datatype: EmptyObject
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

directional-audio-detection.v2.fisheyeOverlay​

  • Description: Entity for FisheyeOverlay
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: Yes

This entity contains a property that enables FisheyeOverlay. FisheyeOverlay is the capability in the DAD2 service that draws sound markers in the video stream.

Properties​
enabled​
  • Description: Turn fisheye overlays on or off
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
    • SET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

directional-audio-detection.v2.ptzControl​

  • Description: Entity for ptz control
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: Yes

This entity contains a property that enables PTZ Control and calibration entity.

Properties​
enabled​
  • Description: Turn ptz control on or off
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator)
    • SET (Permissions: admin, operator)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
useVisualObjects​
  • Description: Turn use visual objects on or off
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin)
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

directional-audio-detection.v2.ptzControl.calibration​

  • Description: Calibration of ptz control
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No

This method contains two other entities, defaultTilt and panOffset.

Properties​

This entity has no properties.

Actions​

This entity has no actions.

directional-audio-detection.v2.ptzControl.calibration.defaultTilt​

  • Description: Default tilt value to use when Directional Audio Detection event doesn't contain tilt value
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No

This entity contains a property and actions to manage the the default tilt value that is used when directional audio detection doesn't get any tilt angle towards the detected sound.

Properties​
value​
  • Description: The default tilt value
  • Datatype: DefaultTilt
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
save​
  • Description: Save default tilt value from the PTZ camera
  • Request Datatype: EmptyObject
  • Response Datatype: EmptyObject
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

directional-audio-detection.v2.ptzControl.calibration.panOffset​

  • Description: Pan offset to PTZ camera
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No

This entity contains properties and actions that manage the pan offset. A sound detected by the directional audio detection has a pan angle relative to its own entity. This needs to be translated to a pan angle that the PTZ camera can understand. This value is pre-calibrated for some PTZ models, while others will require a manual calibration. The pre-calibrated value is fixed and can not be modified by the user, however a manual calibration can always be done, and overrides the pre-calibrated value. A factory default will restore any manual calibration to the pre-calibrated value.

Properties​
manuallyCalibrated​
  • Description: If panOffset has been manually calibrated
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
preCalibrated​
  • Description: If panOffset is pre-calibrated from factory default
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
value​
  • Description: The pan offset value
  • Datatype: PanOffset
  • Operations
    • GET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
reset​
  • Description: Reset to pre-calibrated value, if manual calibration has been done
  • Request Datatype: EmptyObject
  • Response Datatype: EmptyObject
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No
save​
  • Description: Save pan offset value from the PTZ camera
  • Request Datatype: EmptyObject
  • Response Datatype: EmptyObject
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

Data types​

AudioEventData​

  • Description: Audio event data
  • Type: complex
  • Fields
    • id
      • Description: Event ID
      • Type: integer
      • Nullable: No / Gettable: Yes
    • level
      • Description: The audio level when triggered (dB)
      • Type: number
      • Nullable: No / Gettable: Yes
    • pan
      • Description: Pan angle to audio source that triggered
      • Type: number
      • Nullable: No / Gettable: Yes
    • phi
      • Description: Phi angle, the polar angle, measured from the positive z-axis
      • Type: number
      • Nullable: No / Gettable: Yes
    • phiValid
      • Description: Phi angle valid, not all audio detection generates a phi value
      • Type: boolean
      • Nullable: No / Gettable: Yes
    • theta
      • Description: Theta angle, the azimuthal angle, measured in the xy-plane from the positive x-axis
      • Type: number
      • Nullable: No / Gettable: Yes
    • threshold
      • Description: Audio detection threshold value (dB)
      • Type: DetectionThreshold
      • Nullable: No / Gettable: Yes
    • tilt
      • Description: Tilt angle to audio source that triggered
      • Type: integer
      • Nullable: No / Gettable: Yes
    • timestamp
      • Description: The number of seconds since January 1, 1970 UTC.
      • Type: integer
      • Nullable: No / Gettable: Yes

AudioEventsData​

  • Description: Array of audio event data
  • Type: array
  • Element type: AudioEventData
  • Null Value: No

DefaultTilt​

  • Description: Default tilt position value
  • Type: number
  • Minimum Value: -90
  • Maximum Value: 0

DetectionThreshold​

  • Description: Detection threshold data
  • Type: number
  • Minimum Value: 1
  • Maximum Value: 20

DwellTime​

  • Description: Dwell time value (s)
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 600

EmptyObject​

  • Description: Empty object
  • Type: complex

PanOffset​

  • Description: Pan offset value
  • Type: number
  • Minimum Value: -180
  • Maximum Value: 180

ViewareaTimeout​

  • Description: Audio Detection Multiview view area timeout (s)
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 7200