Camera Extras and Dynamic URLs

The model

A camera driver has always been able to declare fixed URLs and a fixed feature set in its manifest. These capabilities invert that. The driver publishes its controls and its URLs at runtime, as XML, over the proxy binding it already owns.

Two independent mechanisms share one opt in style, and a driver may adopt either without the other.

Extras are driver defined controls rendered in the camera interface. The driver sends a document describing sections and objects. Each object names the command the proxy will send back when a viewer manipulates it, so the driver defines both the control and its callback in one place. Nothing about an extra is declared in the manifest, which means the control set can differ per device, per model, or per firmware revision.

Dynamic URLs replace static stream and snapshot addresses. Rather than resolving a URL once at setup, the driver answers with a current list whenever one is needed, and can invalidate the previous answer at any time. This suits devices whose addresses depend on how they are attached, on a credential that rotates, or on a recorder that fronts them.

Both mechanisms are pure notification traffic. There are no new bindings and no new proxies. Everything travels over the existing camera proxy binding, which is conventionally 5001.

Extras are not a camera concept. The same notifications and the same document format are used by drivers across many proxy types, including thermostats, lights, fireplaces and keypads. Only the dynamic URL half is specific to cameras. Read the extras sections below as general proxy technique that happens to be documented here against a camera.

Opting in

Three flags inside the manifest's <capabilities> block. They gate the behavior: without them, the notifications below are ignored.

<capabilities>
  <modes>H265,H264,SNAPSHOT</modes>

  <has_extras>true</has_extras>
  <requires_dynamic_stream_urls>true</requires_dynamic_stream_urls>
  <requires_dynamic_snapshot_urls>true</requires_dynamic_snapshot_urls>
</capabilities>

The stream and snapshot flags are independent. A device that serves stills from a stable path but streams from a rotating one sets only the stream flag.

Call flow

Conventions

Everything is a notification

Each message below is an ordinary proxy notification on the camera binding. There is no response and no return value. The driver announces state, and the interface catches up.

C4:SendToProxy(CAMERA_BINDING, "EXTRAS_SETUP_CHANGED", { XML = document }, "NOTIFY")

Payloads are XML strings, not tables

The documents travel as a single string parameter, conventionally XML, built by the driver. This is unlike most proxy traffic, where parameters are a flat table of scalars. Escape any value that could contain a quote or an angle bracket, since device supplied names frequently do.

Identifiers are yours, and they are load bearing

An object's id is chosen by the driver. It is the handle used to update that control's value later, so it must stay stable for as long as the control exists. The command attribute is likewise arbitrary and is simply the command name the proxy will send back. Deriving one from the other keeps the two ends aligned.

Library conventions are not the contract

The examples here dispatch inbound commands through a table looked up by name, which is a common driver idiom rather than a requirement. What is fixed is the notification names, the parameter names (XML, KEY, URLS), the element and attribute names in the documents, and the fact that the inbound command is whatever the driver put in the command attribute. A driver may receive that command in a plain ReceivedFromProxy with a chain of comparisons and behave identically.

Driver notifications

Sent by the driver on the camera proxy binding. All are fire and forget.

Proxy commands

Inbound commands arrive on the camera binding and are handled like any other proxy traffic.

Payload shapes

extras_setup

Sections group controls under a heading. Objects are the controls. Four object types exist: list, slider, switch, and button.

<extras_setup>
  <extra>
    <section label="Illumination">

      <object type="list" id="beam_mode" label="Beam mode"
              command="SET_BEAM_MODE" value="auto">
        <list maxselections="1" minselections="1">
          <item text="Automatic" value="auto"/>
          <item text="Manual"    value="manual"/>
        </list>
      </object>

      <object type="slider" id="beam_level" label="Brightness"
              command="SET_BEAM_LEVEL" value="50" min="1" max="100"/>

      <object type="switch" id="beam_enabled" label="Enabled"
              command="SET_BEAM_ENABLED" value="true"/>

      <object type="button" id="beam_test" label="Test"
              command="SET_BEAM_TEST"/>

    </section>
  </extra>
</extras_setup>

extras_state

Value updates for controls already published.

<extras_state>
  <extra>
    <object id="beam_level" value="72"/>
  </extra>
</extras_state>

streams and snapshots

Both wrap a flat list. Order is meaningful: the first entry is treated as the primary, higher quality source, and later entries as progressively lighter alternates.

<streams key="REQUEST_KEY">
  <stream url="rtsp://host:554/main" codec="h265" resolution="2560x1440"/>
  <stream url="rtsp://host:554/sub"  codec="h264" resolution="640x480"/>
</streams>

The key attribute is omitted when the publication was not prompted by a request. Snapshot documents follow the same pattern with snapshots and snapshot element names.

Behavior notes

Integration recipe

The minimum for a driver that wants both halves. Helper names here are placeholders for whatever the driver already has.

-- 1. publish the panel once capabilities are known
local function PublishExtras()
  local doc = {}

  doc[#doc + 1] = '<extras_setup><extra>'
  doc[#doc + 1] = '<section label="Illumination">'
  doc[#doc + 1] = string.format(
    '<object type="slider" id="%s" label="%s" command="%s"'
      .. ' value="%d" min="1" max="100"/>',
    "beam_level", "Brightness", "SET_BEAM_LEVEL", DeviceState.level)
  doc[#doc + 1] = '</section></extra></extras_setup>'

  C4:SendToProxy(CAMERA_BINDING, "EXTRAS_SETUP_CHANGED", {
    XML = table.concat(doc),
  }, "NOTIFY")
end

-- 2. handle the command the control declared
local function OnBeamLevel(tParams)
  local level = tonumber(tParams.LEVEL or tParams.VALUE)

  if not WriteLevelToDevice(level) then
    level = DeviceState.level  -- push the old value back
  else
    DeviceState.level = level
  end

  C4:SendToProxy(CAMERA_BINDING, "EXTRAS_STATE_CHANGED", {
    XML = string.format(
      '<extras_state><extra><object id="%s" value="%s"/></extra></extras_state>',
      "beam_level", tostring(level)),
  }, "NOTIFY")
end

-- 3. publish stream URLs
local function PublishStreams(key)
  local doc = {}

  if key then
    doc[#doc + 1] = string.format('<streams key="%s">', key)
  else
    doc[#doc + 1] = '<streams>'
  end

  for _, s in ipairs(BuildStreamList()) do
    doc[#doc + 1] = string.format(
      '<stream url="%s" codec="%s" resolution="%s"/>', s.url, s.codec, s.resolution)
  end

  doc[#doc + 1] = '</streams>'

  C4:SendToProxy(CAMERA_BINDING, "STREAM_URLS_READY", {
    KEY  = key,
    URLS = table.concat(doc),
  }, "NOTIFY")
end

-- 4. invalidate whenever addressing changes
local function OnAddressingChanged()
  C4:SendToProxy(CAMERA_BINDING, "DYNAMIC_URLS_CHANGED", {}, "NOTIFY")
end

Escaping is omitted above for brevity. Device supplied labels and stream names routinely contain characters that will break a document built by concatenation, so run every interpolated value through an XML escape before it reaches the string.