Skip to content
Wowza Video Intelligence...
/
/
/
Get default configuration

Wowza Video Intelligence Framework (VIF) REST API

The Video Intelligence Framework (VIF) adds real-time, AI-powered object detection, scene analysis, and event-driven intelligence to live video streams running on Wowza Streaming Engine (WSE).

This REST API lets you inspect system and per-stream status, read and update the default configuration, manage the active (in-memory) and saved (on-disk) configuration of individual streams, and retrieve annotated thumbnails.

VIF WSE plugin reference

Configuration hierarchy

Settings cascade through three levels of increasing specificity: Defaults (/v1/{server}/plugin/vif/config) → Stream pattern → Single stream. A more specific setting overrides a less specific one.

Active vs. saved configuration

  • Active config (/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}) is the configuration currently applied in memory to a running stream. Supports GET and PUT.

  • Saved config (/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config) is the persisted configuration in video-intelligence.json. Supports GET, PUT, POST, and DELETE.

Authentication

All requests use HTTP Basic authentication with Wowza Streaming Engine Manager credentials.

Download OpenAPI description
vif-openapi-3.1.json
vif-openapi-3.1.yaml
Overview
URL
https://www.wowza.com/docs
License
Wowza
Languages
Servers
Local Wowza Streaming Engine REST API
http://localhost:8087
Custom Wowza Streaming Engine host
http://{host}:{port}

Status & Health

Monitor VIF system and per-stream health and performance.

Operations

Configuration

Read and update the default VIF configuration.

Operations

Get default configuration

Request

Retrieves the full default VIF configuration from video-intelligence.json, including default settings, analysis parameters, event listeners, and all per-stream configuration overrides in the streams array.

Security
basicAuth
Path
serverstringrequired

WSE server name. Any value is accepted; commonly _defaultServer_.

Default "_defaultServer_"
curl -i -X GET \
  -u <username>:<password> \
  http://localhost:8087/v1/http://localhost:8087/plugin/vif/config

Responses

Configuration retrieved successfully.

Bodyapplication/json
activeboolean

Set to true to register WSE with the VI service.

Default false
vi_servicestring or null

WebSocket endpoint for the VI service, e.g. ws://HOST:PORT/ws/stream/.

vi_service_api_keystring or null

API key for authentication with the VI service.

app_namestring or null

Per-stream application name. If blank, applies to all applications.

stream_namestring or null

Stream name or regex pattern to match incoming streams, e.g. objects.*.

vif_event_listenersArray of EventListener (objects) or object

Array (or map) of VIF event listeners to trigger.

One of:

Array (or map) of VIF event listeners to trigger.

rollup_batch_intervalinteger

Seconds to hold detections for rollup and batch events.

Default 2
grayscaledboolean

Send/process frames as grayscale to reduce latency and traffic.

Default false
landscape_videoboolean

Whether the video is in landscape orientation.

Default true
object_analysisobject(ObjectAnalysis)

Object-detection configuration.

scene_analysisobject(SceneAnalysis)

Scene/VLM analysis configuration.

ignore_untracked_objectsboolean

Ignore untracked objects when a tracking_method is set.

Default false
frame_bufferinteger

Size of the frame buffer holding frames to send to the VIF service.

Default 10
catch_up_to_liveboolean

Scene/VLM only. When inference stays slower than real-time, skip the stale buffered backlog and resume at the live edge instead of letting latency grow.

Default true
catch_up_max_behind_secondsnumber or null

Scene/VLM only. How far behind live (seconds) detections may fall before catch-up skips to live. Unset derives to the buffer headroom (~2s).

auto_frame_throttleboolean

Opt-in frame-rate throttle (all modes): reduce inference_fps when inference falls behind. Renamed from auto_scene_frame_throttle (still accepted on read).

Default false
use_transcoderboolean

Use the transcoder to grab frames.

Default true
inference_fpsinteger

Frames per second sent to inferencing when use_transcoder is true.

Default -1
inference_video_heightinteger

Height of the video to be inferenced. -1 = source, 0 = model, >0 actual value.

Default -1
frame_grab_intervalinteger

Seconds between grabbing a frame when use_transcoder is false.

Default 1
skip_framesinteger

Process every Nth frame.

save_imagesboolean

Debug: save frames from the transcoder to /tmp/vif/<stream_name>.

Default false
log_timinginteger

Debug: seconds between writing timing metrics. 0 disables.

Default 0
log_max_messagesinteger

Debug: max log messages to write for vif/ws/wss. -1 all, 0 disabled.

Default 0
streamsArray of objects(VifConfig)

Per-stream configuration overrides.

property name*anyadditional property
Response
application/json
{
  "active": false,
  "vi_service": "string",
  "vi_service_api_key": "string",
  "app_name": "string",
  "stream_name": "string",
  "vif_event_listeners": [
    { … }
  ],
  "rollup_batch_interval": 2,
  "grayscaled": false,
  "landscape_video": true,
  "object_analysis": {
    "model_name": "small",
    "class_names": [ … ],
    "confidence_threshold": 1,
    "tracking_method": "byte_track",
    "byte_track_properties": { … }
  },
  "scene_analysis": {
    "class_names": [ … ],
    "type": "string",
    "sensitivity": 0,
    "confidence_threshold": 1
  },
  "ignore_untracked_objects": false,
  "frame_buffer": 10,
  "catch_up_to_live": true,
  "catch_up_max_behind_seconds": 0,
  "auto_frame_throttle": false,
  "use_transcoder": true,
  "inference_fps": -1,
  "inference_video_height": -1,
  "frame_grab_interval": 1,
  "skip_frames": 0,
  "save_images": false,
  "log_timing": 0,
  "log_max_messages": 0,
  "streams": [
    {}
  ]
}

Update default configuration

Request

Updates the global VIF default configuration. Send only the fields you want to change; unspecified fields are left unchanged. Some settings may require a WSE restart to take effect.

Security
basicAuth
Path
serverstringrequired

WSE server name. Any value is accepted; commonly _defaultServer_.

Default "_defaultServer_"
Bodyapplication/jsonrequired
activeboolean

Set to true to register WSE with the VI service.

Default false
vi_servicestring or null

WebSocket endpoint for the VI service, e.g. ws://HOST:PORT/ws/stream/.

vi_service_api_keystring or null

API key for authentication with the VI service.

app_namestring or null

Per-stream application name. If blank, applies to all applications.

stream_namestring or null

Stream name or regex pattern to match incoming streams, e.g. objects.*.

vif_event_listenersArray of EventListener (objects) or object

Array (or map) of VIF event listeners to trigger.

One of:

Array (or map) of VIF event listeners to trigger.

rollup_batch_intervalinteger

Seconds to hold detections for rollup and batch events.

Default 2
grayscaledboolean

Send/process frames as grayscale to reduce latency and traffic.

Default false
landscape_videoboolean

Whether the video is in landscape orientation.

Default true
object_analysisobject(ObjectAnalysis)

Object-detection configuration.

scene_analysisobject(SceneAnalysis)

Scene/VLM analysis configuration.

ignore_untracked_objectsboolean

Ignore untracked objects when a tracking_method is set.

Default false
frame_bufferinteger

Size of the frame buffer holding frames to send to the VIF service.

Default 10
catch_up_to_liveboolean

Scene/VLM only. When inference stays slower than real-time, skip the stale buffered backlog and resume at the live edge instead of letting latency grow.

Default true
catch_up_max_behind_secondsnumber or null

Scene/VLM only. How far behind live (seconds) detections may fall before catch-up skips to live. Unset derives to the buffer headroom (~2s).

auto_frame_throttleboolean

Opt-in frame-rate throttle (all modes): reduce inference_fps when inference falls behind. Renamed from auto_scene_frame_throttle (still accepted on read).

Default false
use_transcoderboolean

Use the transcoder to grab frames.

Default true
inference_fpsinteger

Frames per second sent to inferencing when use_transcoder is true.

Default -1
inference_video_heightinteger

Height of the video to be inferenced. -1 = source, 0 = model, >0 actual value.

Default -1
frame_grab_intervalinteger

Seconds between grabbing a frame when use_transcoder is false.

Default 1
skip_framesinteger

Process every Nth frame.

save_imagesboolean

Debug: save frames from the transcoder to /tmp/vif/<stream_name>.

Default false
log_timinginteger

Debug: seconds between writing timing metrics. 0 disables.

Default 0
log_max_messagesinteger

Debug: max log messages to write for vif/ws/wss. -1 all, 0 disabled.

Default 0
streamsArray of objects(VifConfig)

Per-stream configuration overrides.

property name*anyadditional property
curl -i -X PUT \
  -u <username>:<password> \
  http://localhost:8087/v1/http://localhost:8087/plugin/vif/config \
  -H 'Content-Type: application/json' \
  -d '{
    "active": true
  }'

Responses

Configuration updated successfully.

Bodyapplication/json
activeboolean

Set to true to register WSE with the VI service.

Default false
vi_servicestring or null

WebSocket endpoint for the VI service, e.g. ws://HOST:PORT/ws/stream/.

vi_service_api_keystring or null

API key for authentication with the VI service.

app_namestring or null

Per-stream application name. If blank, applies to all applications.

stream_namestring or null

Stream name or regex pattern to match incoming streams, e.g. objects.*.

vif_event_listenersArray of EventListener (objects) or object

Array (or map) of VIF event listeners to trigger.

One of:

Array (or map) of VIF event listeners to trigger.

rollup_batch_intervalinteger

Seconds to hold detections for rollup and batch events.

Default 2
grayscaledboolean

Send/process frames as grayscale to reduce latency and traffic.

Default false
landscape_videoboolean

Whether the video is in landscape orientation.

Default true
object_analysisobject(ObjectAnalysis)

Object-detection configuration.

scene_analysisobject(SceneAnalysis)

Scene/VLM analysis configuration.

ignore_untracked_objectsboolean

Ignore untracked objects when a tracking_method is set.

Default false
frame_bufferinteger

Size of the frame buffer holding frames to send to the VIF service.

Default 10
catch_up_to_liveboolean

Scene/VLM only. When inference stays slower than real-time, skip the stale buffered backlog and resume at the live edge instead of letting latency grow.

Default true
catch_up_max_behind_secondsnumber or null

Scene/VLM only. How far behind live (seconds) detections may fall before catch-up skips to live. Unset derives to the buffer headroom (~2s).

auto_frame_throttleboolean

Opt-in frame-rate throttle (all modes): reduce inference_fps when inference falls behind. Renamed from auto_scene_frame_throttle (still accepted on read).

Default false
use_transcoderboolean

Use the transcoder to grab frames.

Default true
inference_fpsinteger

Frames per second sent to inferencing when use_transcoder is true.

Default -1
inference_video_heightinteger

Height of the video to be inferenced. -1 = source, 0 = model, >0 actual value.

Default -1
frame_grab_intervalinteger

Seconds between grabbing a frame when use_transcoder is false.

Default 1
skip_framesinteger

Process every Nth frame.

save_imagesboolean

Debug: save frames from the transcoder to /tmp/vif/<stream_name>.

Default false
log_timinginteger

Debug: seconds between writing timing metrics. 0 disables.

Default 0
log_max_messagesinteger

Debug: max log messages to write for vif/ws/wss. -1 all, 0 disabled.

Default 0
streamsArray of objects(VifConfig)

Per-stream configuration overrides.

property name*anyadditional property
Response
application/json
{
  "active": false,
  "vi_service": "string",
  "vi_service_api_key": "string",
  "app_name": "string",
  "stream_name": "string",
  "vif_event_listeners": [
    { … }
  ],
  "rollup_batch_interval": 2,
  "grayscaled": false,
  "landscape_video": true,
  "object_analysis": {
    "model_name": "small",
    "class_names": [ … ],
    "confidence_threshold": 1,
    "tracking_method": "byte_track",
    "byte_track_properties": { … }
  },
  "scene_analysis": {
    "class_names": [ … ],
    "type": "string",
    "sensitivity": 0,
    "confidence_threshold": 1
  },
  "ignore_untracked_objects": false,
  "frame_buffer": 10,
  "catch_up_to_live": true,
  "catch_up_max_behind_seconds": 0,
  "auto_frame_throttle": false,
  "use_transcoder": true,
  "inference_fps": -1,
  "inference_video_height": -1,
  "frame_grab_interval": 1,
  "skip_frames": 0,
  "save_images": false,
  "log_timing": 0,
  "log_max_messages": 0,
  "streams": [
    {}
  ]
}

Stream Management

Manage the active and saved configuration of individual streams.

Operations

Media

Retrieve annotated media such as thumbnails.

Operations