{
  "openapi": "3.1.0",
  "info": {
    "title": "Wowza Video Intelligence Framework (VIF) REST API",
    "description": "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).\n\nThis 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.\n\n## Configuration hierarchy\nSettings 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.\n\n## Active vs. saved configuration\n- **Active config** (`/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}`) is the\n  configuration currently applied in memory to a running stream. Supports `GET` and `PUT`.\n\n- **Saved config** (`/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config`) is the\n  persisted configuration in `video-intelligence.json`. Supports `GET`, `PUT`,\n  `POST`, and `DELETE`.\n\n\n## Authentication\nAll requests use HTTP Basic authentication with Wowza Streaming Engine Manager credentials.\n",
    "contact": {
      "name": "Wowza Support",
      "url": "https://www.wowza.com/docs"
    },
    "license": {
      "name": "Wowza",
      "url": "https://www.wowza.com/legal"
    }
  },
  "externalDocs": {
    "description": "VIF WSE plugin reference",
    "url": "https://github.com/WowzaMediaSystems/wowza-video-intelligence-framework/blob/main/docs/README.wse-plugin.md"
  },
  "servers": [
    {
      "url": "http://localhost:8087",
      "description": "Local Wowza Streaming Engine REST API"
    },
    {
      "url": "http://{host}:{port}",
      "description": "Custom Wowza Streaming Engine host",
      "variables": {
        "host": {
          "default": "localhost"
        },
        "port": {
          "default": "8087"
        }
      }
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "Status & Health",
      "description": "Monitor VIF system and per-stream health and performance."
    },
    {
      "name": "Configuration",
      "description": "Read and update the default VIF configuration."
    },
    {
      "name": "Stream Management",
      "description": "Manage the active and saved configuration of individual streams."
    },
    {
      "name": "Media",
      "description": "Retrieve annotated media such as thumbnails."
    }
  ],
  "paths": {
    "/v1/{server}/plugin/vif/status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        }
      ],
      "get": {
        "tags": [
          "Status & Health"
        ],
        "operationId": "getSystemStatus",
        "summary": "Get system status",
        "description": "Returns a full snapshot of the VIF system: host information (WSE/VIF versions, CPU, NVIDIA GPU type and utilization) and an array of every stream currently registered with the VI service.\n",
        "responses": {
          "200": {
            "description": "System status returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemStatus"
                },
                "examples": {
                  "healthy": {
                    "$ref": "#/components/examples/SystemStatusExample"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/config": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        }
      ],
      "get": {
        "tags": [
          "Configuration"
        ],
        "operationId": "getDefaultConfig",
        "summary": "Get default configuration",
        "description": "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.\n",
        "responses": {
          "200": {
            "description": "Configuration retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Configuration"
        ],
        "operationId": "updateDefaultConfig",
        "summary": "Update default configuration",
        "description": "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.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfigUpdate"
              },
              "examples": {
                "enable": {
                  "summary": "Enable VIF globally",
                  "value": {
                    "active": true
                  }
                },
                "objectClasses": {
                  "summary": "Set object detection classes",
                  "value": {
                    "object_analysis": {
                      "class_names": [
                        "person",
                        "car",
                        "truck"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Configuration updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        },
        {
          "$ref": "#/components/parameters/AppName"
        },
        {
          "$ref": "#/components/parameters/StreamName"
        }
      ],
      "get": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "getActiveStreamConfig",
        "summary": "Get active stream configuration",
        "description": "Returns the configuration currently applied in memory to the running stream. The stream name may be a specific stream or a stream pattern (regex).\n",
        "responses": {
          "200": {
            "description": "Active configuration returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "updateActiveStreamConfig",
        "summary": "Update active stream configuration",
        "description": "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.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfigUpdate"
              },
              "examples": {
                "enable": {
                  "summary": "Enable VIF on the stream",
                  "value": {
                    "active": "true"
                  }
                },
                "disable": {
                  "summary": "Disable VIF on the stream",
                  "value": {
                    "active": "false"
                  }
                },
                "disableOverlays": {
                  "summary": "Disable the overlay event listener",
                  "value": {
                    "vif_event_listeners": {
                      "Overlays": {
                        "methods": [
                          "disabled"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Active configuration updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        },
        {
          "$ref": "#/components/parameters/AppName"
        },
        {
          "$ref": "#/components/parameters/StreamName"
        }
      ],
      "get": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "getSavedStreamConfig",
        "summary": "Get saved stream configuration",
        "description": "Returns the persisted (on-disk) configuration for the stream or stream pattern.",
        "responses": {
          "200": {
            "description": "Saved configuration returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "updateSavedStreamConfig",
        "summary": "Update saved stream configuration",
        "description": "Merges the supplied fields into the persisted configuration for the stream or stream pattern. Send only the fields you want to change.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfigUpdate"
              },
              "examples": {
                "deactivate": {
                  "summary": "Deactivate a stream pattern",
                  "value": {
                    "active": "false"
                  }
                },
                "objectClasses": {
                  "summary": "Set object detection classes",
                  "value": {
                    "object_analysis": {
                      "class_names": [
                        "person",
                        "car"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved configuration updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "createSavedStreamConfig",
        "summary": "Create saved stream configuration",
        "description": "Creates a new persisted configuration entry for the stream or stream pattern. Use this to add a new per-stream configuration to `video-intelligence.json`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfig"
              },
              "examples": {
                "newStream": {
                  "summary": "Create config for an object detection stream pattern",
                  "value": {
                    "active": true,
                    "stream_name": "objects.*",
                    "object_analysis": {
                      "class_names": [
                        "person",
                        "car",
                        "truck"
                      ],
                      "confidence_threshold": 0.5
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved configuration created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "201": {
            "description": "Saved configuration created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "deleteSavedStreamConfig",
        "summary": "Delete saved stream configuration",
        "description": "Removes the persisted configuration entry for the stream or stream pattern.",
        "responses": {
          "200": {
            "description": "Saved configuration deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "204": {
            "description": "Saved configuration deleted (no content)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        },
        {
          "$ref": "#/components/parameters/AppName"
        },
        {
          "$ref": "#/components/parameters/StreamName"
        }
      ],
      "get": {
        "tags": [
          "Status & Health"
        ],
        "operationId": "getStreamStatus",
        "summary": "Get single stream status",
        "description": "Returns detailed status and performance metrics for a specific stream. The stream must be registered with the VI service. If `status` is anything other than `running`, inspect the `reason` field for diagnostic information.\n",
        "responses": {
          "200": {
            "description": "Stream status returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamStatus"
                },
                "examples": {
                  "running": {
                    "$ref": "#/components/examples/StreamStatusExample"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/thumbnail": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        },
        {
          "$ref": "#/components/parameters/AppName"
        },
        {
          "$ref": "#/components/parameters/StreamName"
        }
      ],
      "get": {
        "tags": [
          "Media"
        ],
        "operationId": "getStreamThumbnail",
        "summary": "Get a stream thumbnail",
        "description": "Returns a thumbnail image (JPEG) for the stream. Optionally include graphical detection overlays and select a specific buffered frame.\n",
        "parameters": [
          {
            "name": "overlay",
            "in": "query",
            "required": false,
            "description": "When `true`, render detection overlays onto the returned image.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "frameId",
            "in": "query",
            "required": false,
            "description": "Frame identifier to retrieve from the buffer. `0` is the latest frame.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thumbnail image returned successfully.",
            "content": {
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/{server}/plugin/vif/vhosts/{vhost}/applications/{appName}/instances/{instance}/streams/{streamName}/config": {
      "parameters": [
        {
          "$ref": "#/components/parameters/Server"
        },
        {
          "$ref": "#/components/parameters/VHost"
        },
        {
          "$ref": "#/components/parameters/AppName"
        },
        {
          "$ref": "#/components/parameters/Instance"
        },
        {
          "$ref": "#/components/parameters/StreamName"
        }
      ],
      "get": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "getSavedStreamConfigQualified",
        "summary": "Get saved stream configuration (vhost/instance qualified)",
        "description": "Fully qualified variant of the saved-configuration endpoint that explicitly specifies the virtual host and application instance. Defaults are `_defaultVHost_` and `_definst_`.\n",
        "responses": {
          "200": {
            "description": "Saved configuration returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "updateSavedStreamConfigQualified",
        "summary": "Update saved stream configuration (vhost/instance qualified)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfigUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved configuration updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "createSavedStreamConfigQualified",
        "summary": "Create saved stream configuration (vhost/instance qualified)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VifConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved configuration created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VifConfig"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Stream Management"
        ],
        "operationId": "deleteSavedStreamConfigQualified",
        "summary": "Delete saved stream configuration (vhost/instance qualified)",
        "responses": {
          "200": {
            "description": "Saved configuration deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "204": {
            "description": "Saved configuration deleted (no content)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Wowza Streaming Engine Manager credentials."
      }
    },
    "parameters": {
      "Server": {
        "name": "server",
        "in": "path",
        "required": true,
        "description": "WSE server name. Any value is accepted; commonly `_defaultServer_`.",
        "schema": {
          "type": "string",
          "default": "_defaultServer_"
        }
      },
      "AppName": {
        "name": "appName",
        "in": "path",
        "required": true,
        "description": "Name of the Wowza application the stream is running on (e.g. `live`).",
        "schema": {
          "type": "string"
        }
      },
      "StreamName": {
        "name": "streamName",
        "in": "path",
        "required": true,
        "description": "Stream name or a stream pattern (regex) used to match streams, e.g. `objects.*`.",
        "schema": {
          "type": "string"
        }
      },
      "VHost": {
        "name": "vhost",
        "in": "path",
        "required": true,
        "description": "Virtual host name. Defaults to `_defaultVHost_`.",
        "schema": {
          "type": "string",
          "default": "_defaultVHost_"
        }
      },
      "Instance": {
        "name": "instance",
        "in": "path",
        "required": true,
        "description": "Application instance name. Defaults to `_definst_`.",
        "schema": {
          "type": "string",
          "default": "_definst_"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request was malformed or contained invalid parameters.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication failed. Check the WSE Manager username and password.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "The requested server, application, or stream was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "SystemStatus": {
        "type": "object",
        "description": "Full system snapshot returned by the status endpoint.",
        "properties": {
          "host": {
            "$ref": "#/components/schemas/HostInfo"
          },
          "streams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StreamStatus"
            }
          }
        },
        "required": [
          "host",
          "streams"
        ]
      },
      "HostInfo": {
        "type": "object",
        "description": "Host-level information and hardware utilization.",
        "properties": {
          "wse_version": {
            "type": "string",
            "examples": [
              "4.9.1"
            ]
          },
          "vif_module_version": {
            "type": "string",
            "examples": [
              "1.2.0"
            ]
          },
          "cpu_avg": {
            "type": "number",
            "description": "Average CPU utilization (%)."
          },
          "nvidia_gpu_type": {
            "type": "string",
            "examples": [
              "NVIDIA A10"
            ]
          },
          "nvidia_driver_version": {
            "type": "string"
          },
          "cuda_version": {
            "type": "string"
          },
          "gpu_avg": {
            "$ref": "#/components/schemas/Measurement"
          },
          "gpu_memory_avg": {
            "$ref": "#/components/schemas/Measurement"
          },
          "gpu_encode_avg": {
            "$ref": "#/components/schemas/Measurement"
          },
          "gpu_decode_avg": {
            "$ref": "#/components/schemas/Measurement"
          }
        }
      },
      "Measurement": {
        "type": "object",
        "description": "A measured value with its unit.",
        "properties": {
          "value": {
            "type": "number"
          },
          "unit": {
            "type": "string",
            "examples": [
              "%",
              "MB"
            ]
          }
        },
        "required": [
          "value",
          "unit"
        ]
      },
      "StreamStatus": {
        "type": "object",
        "description": "Status and performance metrics for a single stream.",
        "properties": {
          "api_version": {
            "type": "string"
          },
          "wse_version": {
            "type": "string"
          },
          "vif_module_version": {
            "type": "string"
          },
          "vi_service_url": {
            "type": "string",
            "format": "uri"
          },
          "vi_service_version": {
            "type": "string"
          },
          "vhost_name": {
            "type": "string"
          },
          "app_name": {
            "type": "string"
          },
          "instance_name": {
            "type": "string"
          },
          "stream_name": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "model_name": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "frame_rate": {
            "type": "number"
          },
          "skip_frames": {
            "type": "integer"
          },
          "duration": {
            "type": "integer"
          },
          "resize_output": {
            "type": "boolean"
          },
          "grayscaled": {
            "type": "boolean"
          },
          "detector_type": {
            "type": "string",
            "enum": [
              "object",
              "scene"
            ]
          },
          "status": {
            "type": "string",
            "examples": [
              "running",
              "stopped",
              "error"
            ]
          },
          "reason": {
            "type": "string",
            "description": "Diagnostic detail when status is not `running`."
          },
          "vif_event_listeners": {
            "$ref": "#/components/schemas/EventListenerStatus"
          },
          "performance": {
            "$ref": "#/components/schemas/Performance"
          }
        }
      },
      "EventListenerStatus": {
        "type": "object",
        "description": "Configured event listeners grouped by built-in type.",
        "properties": {
          "Id3Tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "Webhooks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "LogFiles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "Overlays": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Performance": {
        "type": "object",
        "description": "Per-stream processing performance metrics (all times in milliseconds).",
        "properties": {
          "ping_rtt_avg": {
            "type": "number"
          },
          "ping_pong_rtt_avg": {
            "type": "number"
          },
          "preprocess_time_avg": {
            "type": "number"
          },
          "inference_time_avg": {
            "type": "number"
          },
          "postprocess_time_avg": {
            "type": "number"
          },
          "total_processing_time_avg": {
            "type": "number"
          },
          "frame_detect_time_avg": {
            "type": "number"
          },
          "video_frames_ttl": {
            "type": "integer"
          },
          "object_frames_detected": {
            "type": "integer"
          },
          "behind_live_ms": {
            "type": "number",
            "description": "How far behind the live edge the analyzed frame currently is."
          }
        }
      },
      "VifConfig": {
        "type": "object",
        "description": "Full VIF configuration object as stored in `video-intelligence.json`. The top level holds the default settings; per-stream overrides live in the `streams` array.\n",
        "properties": {
          "active": {
            "type": "boolean",
            "default": false,
            "description": "Set to true to register WSE with the VI service."
          },
          "vi_service": {
            "type": [
              "string",
              "null"
            ],
            "description": "WebSocket endpoint for the VI service, e.g. ws://HOST:PORT/ws/stream/."
          },
          "vi_service_api_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "API key for authentication with the VI service."
          },
          "app_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Per-stream application name. If blank, applies to all applications."
          },
          "stream_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stream name or regex pattern to match incoming streams, e.g. objects.*."
          },
          "vif_event_listeners": {
            "description": "Array (or map) of VIF event listeners to trigger.",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EventListener"
                }
              },
              {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/EventListener"
                }
              }
            ]
          },
          "rollup_batch_interval": {
            "type": "integer",
            "default": 2,
            "description": "Seconds to hold detections for rollup and batch events."
          },
          "grayscaled": {
            "type": "boolean",
            "default": false,
            "description": "Send/process frames as grayscale to reduce latency and traffic."
          },
          "landscape_video": {
            "type": "boolean",
            "default": true,
            "description": "Whether the video is in landscape orientation."
          },
          "object_analysis": {
            "$ref": "#/components/schemas/ObjectAnalysis"
          },
          "scene_analysis": {
            "$ref": "#/components/schemas/SceneAnalysis"
          },
          "ignore_untracked_objects": {
            "type": "boolean",
            "default": false,
            "description": "Ignore untracked objects when a tracking_method is set."
          },
          "frame_buffer": {
            "type": "integer",
            "default": 10,
            "description": "Size of the frame buffer holding frames to send to the VIF service."
          },
          "catch_up_to_live": {
            "type": "boolean",
            "default": true,
            "description": "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.\n"
          },
          "catch_up_max_behind_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Scene/VLM only. How far behind live (seconds) detections may fall before catch-up skips to live. Unset derives to the buffer headroom (~2s).\n"
          },
          "auto_frame_throttle": {
            "type": "boolean",
            "default": false,
            "description": "Opt-in frame-rate throttle (all modes): reduce inference_fps when inference falls behind. Renamed from auto_scene_frame_throttle (still accepted on read).\n"
          },
          "use_transcoder": {
            "type": "boolean",
            "default": true,
            "description": "Use the transcoder to grab frames."
          },
          "inference_fps": {
            "type": "integer",
            "default": -1,
            "description": "Frames per second sent to inferencing when use_transcoder is true."
          },
          "inference_video_height": {
            "type": "integer",
            "default": -1,
            "description": "Height of the video to be inferenced. -1 = source, 0 = model, >0 actual value."
          },
          "frame_grab_interval": {
            "type": "integer",
            "default": 1,
            "description": "Seconds between grabbing a frame when use_transcoder is false."
          },
          "skip_frames": {
            "type": "integer",
            "description": "Process every Nth frame."
          },
          "save_images": {
            "type": "boolean",
            "default": false,
            "description": "Debug: save frames from the transcoder to /tmp/vif/<stream_name>."
          },
          "log_timing": {
            "type": "integer",
            "default": 0,
            "description": "Debug: seconds between writing timing metrics. 0 disables."
          },
          "log_max_messages": {
            "type": "integer",
            "default": 0,
            "description": "Debug: max log messages to write for vif/ws/wss. -1 all, 0 disabled."
          },
          "streams": {
            "type": "array",
            "description": "Per-stream configuration overrides.",
            "items": {
              "$ref": "#/components/schemas/VifConfig"
            }
          }
        },
        "additionalProperties": true
      },
      "VifConfigUpdate": {
        "description": "Partial configuration used for updates. Send only the fields to change; all properties are optional. Boolean fields are accepted as native booleans or as the strings \"true\"/\"false\".\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/VifConfig"
          }
        ]
      },
      "ObjectAnalysis": {
        "type": "object",
        "description": "Object-detection configuration.",
        "properties": {
          "model_name": {
            "type": "string",
            "examples": [
              "small",
              "medium",
              "large"
            ]
          },
          "class_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "person",
                "car",
                "truck"
              ]
            ]
          },
          "confidence_threshold": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "tracking_method": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "byte_track"
            ]
          },
          "byte_track_properties": {
            "$ref": "#/components/schemas/ByteTrackProperties"
          }
        },
        "additionalProperties": true
      },
      "ByteTrackProperties": {
        "type": "object",
        "description": "ByteTrack object-tracking tuning parameters.",
        "properties": {
          "track_creation_minimum_confidence": {
            "type": "number"
          },
          "max_lost_track_frames_before_track_removal": {
            "type": "integer"
          },
          "minimum_consecutive_track_overlap": {
            "type": "number"
          },
          "track_creation_minimum_consecutive_frames": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "SceneAnalysis": {
        "type": "object",
        "description": "Scene/VLM analysis configuration.",
        "properties": {
          "class_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "taking pictures",
                "running",
                "fight"
              ]
            ]
          },
          "type": {
            "type": "string"
          },
          "sensitivity": {
            "type": "number"
          },
          "confidence_threshold": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "additionalProperties": true
      },
      "EventListener": {
        "type": "object",
        "description": "A VIF event listener definition.",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Descriptive name of the event listener."
          },
          "class_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Java class (with namespace) for the event. Built-in classes: Id3Event, WebhookEvent2, LogFileEvent, OverlayEvent (default namespace com.wowza.wms.plugin.videointelligence.event).\n"
          },
          "methods": {
            "description": "Which events are sent and how often.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "disabled",
                  "immediate",
                  "batch",
                  "rollup"
                ]
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "disabled",
                    "immediate",
                    "batch",
                    "rollup"
                  ]
                }
              }
            ],
            "default": "disabled"
          },
          "confidence_threshold": {
            "type": "number",
            "default": 0,
            "description": "Threshold for objects/scenes used by immediate and batch methods."
          },
          "suppress_empty_detections": {
            "type": "boolean",
            "default": false,
            "description": "Do not call the listener when there are no detections."
          },
          "properties": {
            "type": [
              "object",
              "null"
            ],
            "description": "Custom key/value properties for the event. Included by default are stream_name, width, height, frame_rate, and detector_type. The OverlayEvent supports jitter, debug_string, show_stats, overlay_delay, overlay_thread_drawing, replace_video, and fade_step.\n",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "success"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "status"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "examples": [
              "error"
            ]
          },
          "code": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "examples": {
      "SystemStatusExample": {
        "summary": "Healthy system with one active stream",
        "value": {
          "host": {
            "wse_version": "4.9.1",
            "vif_module_version": "1.2.0",
            "cpu_avg": 23.5,
            "nvidia_gpu_type": "NVIDIA A10",
            "nvidia_driver_version": "535.129.03",
            "cuda_version": "12.2",
            "gpu_avg": {
              "value": 45.2,
              "unit": "%"
            },
            "gpu_memory_avg": {
              "value": 3200,
              "unit": "MB"
            },
            "gpu_encode_avg": {
              "value": 12.1,
              "unit": "%"
            },
            "gpu_decode_avg": {
              "value": 18.7,
              "unit": "%"
            }
          },
          "streams": [
            {
              "api_version": "v1",
              "vi_service_url": "http://vi-service:8089",
              "vi_service_version": "1.2.0",
              "vhost_name": "_defaultVHost_",
              "app_name": "live",
              "instance_name": "_definst_",
              "stream_name": "security_cam_01",
              "active": true,
              "model_name": "large",
              "width": 1920,
              "height": 1080,
              "frame_rate": 30,
              "skip_frames": 5,
              "duration": 0,
              "resize_output": false,
              "grayscaled": false,
              "detector_type": "object",
              "status": "running",
              "reason": "",
              "vif_event_listeners": {
                "Id3Tags": [],
                "Webhooks": [
                  "https://your-webhook.example.com/detections"
                ],
                "LogFiles": [
                  "/usr/local/WowzaStreamingEngine/logs/vif.log"
                ],
                "Overlays": []
              },
              "performance": {
                "ping_rtt_avg": 1.2,
                "ping_pong_rtt_avg": 2.4,
                "preprocess_time_avg": 3.1,
                "inference_time_avg": 12.3,
                "postprocess_time_avg": 2.8,
                "total_processing_time_avg": 18.7,
                "frame_detect_time_avg": 19.2,
                "video_frames_ttl": 54000,
                "object_frames_detected": 12340
              }
            }
          ]
        }
      },
      "StreamStatusExample": {
        "summary": "A single running stream",
        "value": {
          "wse_version": "4.9.1",
          "vif_module_version": "1.2.0",
          "api_version": "v1",
          "vi_service_url": "http://vi-service:8089",
          "vi_service_version": "1.2.0",
          "instance_name": "_definst_",
          "stream_name": "security_cam_01",
          "active": true,
          "model_name": "large",
          "width": 1920,
          "height": 1080,
          "frame_rate": 30,
          "skip_frames": 5,
          "duration": 0,
          "resize_output": false,
          "grayscaled": false,
          "detector_type": "object",
          "status": "running",
          "reason": "",
          "vif_event_listeners": {
            "Id3Tags": [],
            "Webhooks": [
              "https://your-webhook.example.com/detections"
            ],
            "LogFiles": [
              "/usr/local/WowzaStreamingEngine/logs/vif.log"
            ],
            "Overlays": []
          },
          "performance": {
            "ping_rtt_avg": 1.2,
            "ping_pong_rtt_avg": 2.4,
            "preprocess_time_avg": 3.1,
            "inference_time_avg": 12.3,
            "postprocess_time_avg": 2.8,
            "total_processing_time_avg": 18.7,
            "frame_detect_time_avg": 19.2,
            "video_frames_ttl": 54000,
            "object_frames_detected": 12340
          }
        }
      }
    }
  }
}