latestOpenAPI 3.1.0Wowza2026-08-10151446.2 KB

7128019ae2c5

Stream Management

Update active stream configuration

Updates the in-memory configuration for a running stream (highest priority in the configuration hierarchy). Commonly used to enable/disable VIF on a stream or adjust detection parameters on the fly. Send only the fields you want to change.

put/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}

Request body

activeboolean

Set to true to register WSE with the VI service.

vi_servicestring nullable

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

vi_service_api_keystring nullable

API key for authentication with the VI service.

app_namestring nullable

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

stream_namestring nullable

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

rollup_batch_intervalinteger

Seconds to hold detections for rollup and batch events.

grayscaledboolean

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

landscape_videoboolean

Whether the video is in landscape orientation.

ignore_untracked_objectsboolean

Ignore untracked objects when a tracking_method is set.

frame_bufferinteger

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

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.

catch_up_max_behind_secondsnumber nullable

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).

use_transcoderboolean

Use the transcoder to grab frames.

inference_fpsinteger

Frames per second sent to inferencing when use_transcoder is true.

inference_video_heightinteger

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

frame_grab_intervalinteger

Seconds between grabbing a frame when use_transcoder is false.

skip_framesinteger

Process every Nth frame.

save_imagesboolean

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

log_timinginteger

Debug: seconds between writing timing metrics. 0 disables.

log_max_messagesinteger

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

Example request

{
  "object_analysis": {
    "model_name": "small",
    "class_names": [
      "person",
      "car",
      "truck"
    ],
    "tracking_method": "byte_track"
  },
  "scene_analysis": {
    "class_names": [
      "taking pictures",
      "running",
      "fight"
    ]
  },
  "streams": [
    {
      "object_analysis": {
        "model_name": "small",
        "class_names": [
          "person",
          "car",
          "truck"
        ],
        "tracking_method": "byte_track"
      },
      "scene_analysis": {
        "class_names": [
          "taking pictures",
          "running",
          "fight"
        ]
      }
    }
  ]
}

Response

Active configuration updated successfully.