Voice Coordinator

The model

Voice involves four separate pieces, and the agent is the only one that never touches audio. It moves addresses. The audio path is a direct TCP socket from the voiced daemon to a server the target driver opens.

Inside the agent, every voice target is represented by a service instance. The instance's service type is what voiced is told when the instance is registered. The service name is the key under which input devices store the target's connection URI. The instance name embeds the target's device id and is how you find your target in the agent's logs.

Two of these classes accept third-party drivers, and they work in opposite directions. On the transcoder path your driver opens the audio socket and invents its own address. On the apple path a separate bridge driver owns the audio endpoint and your driver only relays the bridge's URL. The transcoder path is the general-purpose one; this page centers on it. The %04d in instance names is the target's device id, zero-padded to four digits, so transcoder_0042 is device 42.

Call flow

The start cycle

The agent re-reads every target's address on a timer, and it reacts to a changed address by stopping the target, not by re-pointing it. Recovery happens on a later pass. This is the single most consequential behavior on the page.

A maintenance timer fires every 95 seconds and alternates between two jobs: one tick asks voiced for status, the next runs a start pass over every instance. A start pass therefore runs every 190 seconds. On each start pass the agent sends your driver GET_VOICE_TARGET_CONFIG and compares the reply against the address it is already using.

The consequence: if your driver binds an ephemeral port (Listen("*", 0)), the address changes on every driver reload, and every reload silently tears down your target. The microphone still lights up and says it is listening, your driver receives zero bytes, and voiced's status stops listing your instance. Always bind a fixed port, and expose it as a property so an installer can move it if it collides.

Two things bypass the wait. Toggling the service's enable property stops or starts its instances immediately, and an apple-path target that reports ACTIVE through APPLETV_STATUS is started at once rather than on the next pass. Everything else waits for the timer.

Conventions

What makes a driver a candidate

At initialization the agent scans every room and builds a list of eligible third-party targets. A driver must pass all three checks or the agent never creates a target for it:

The proxy type is not one of the checks. A cable proxy, a media_player proxy, or any other watchable AV proxy works; the capability is the gate. Capabilities are read when the device is added to the project, so adding <push-to-talk> to an installed driver does nothing until the device is removed and re-added.

Registration is by exact filename

The agent keeps a map from c4z filename to a constructor, and the filename is the entire check. It does not verify authorship, model, or anything else. Candidates found by the room scan are added to the map as transcoder targets; a handful of names are wired in permanently:

The map is built when the agent initializes. The agent listens for project change events and re-parses the project a few seconds after a device is added, moved, renamed, or removed, which creates targets for any filename already in the map. A filename the scan has never seen gets into the map only when initialization runs again: the Reinitialize Driver action on the agent, or a Director restart. After installing a brand-new voice-capable driver, run that action.

Reply parsing is deliberately crude

The agent parses both UI request replies by taking whatever sits between the first > and the next <. The tag name is decoration; the content is everything. A reply that does not contain that bracket pair yields "Unknown" for the type and "" for the config.

The daemon protocol has two generations

The agent speaks to voiced assuming the newer protocol ("3.4"). If a start command comes back with an error of type Invalid argument, it downgrades itself to "3.3" and restarts every instance. The generation changes the shape of voice_target_config (structured table versus raw string; see Data shapes) and is negotiated at runtime, not read from the OS version.

Library conventions are not the contract

Everything above is wire contract: the capability tag, the map filenames, the UI request names, the reply parsing, the voiced message shapes. The handler style in the examples below is not. This page writes plain UIRequest and ExecuteCommand functions, which is what Director actually calls. Drivers built on the shared library reach the same handlers through its UIR. and EC. dispatch tables; use whichever your driver already uses. Helper names in the examples, such as CanTalk(), are placeholders to write yourself.

Requests to your driver

These arrive at your driver's UIRequest entry point, with no binding context. The first two come from the agent and are the only ones it reads. The other three come from Navigators; implement them for the microphone UI, but know that the agent ignores them.

-- transcoder form: literal id 0, then controller-reachable ip:port
<TargetConfig>0@192.168.1.50:9302</TargetConfig>

-- apple form: relayed from the bridge, scheme and trailing slash required
<TargetConfig>c4vc://2853628976@192.168.1.50:9251/</TargetConfig>

<voice_info>{"codec":{"id":1,"encoding":"PCM","bitrate":16000,
"channels":1,"bitqty":16},"host":"192.168.1.50","port":9302}</voice_info>

Commands to the agent

The agent is a singleton; find it by filename. Commands sent with C4:SendToDevice arrive at its ExecuteCommand entry point. It declares no programming commands, so none of this is visible to Composer programming.

local agentId = next(C4:GetDevicesByC4iName("control4_agent_voicecoordinator.c4z"))

C4:SendToProxy(5001, "SET_PTT_URL", { URL = "0@192.168.1.50:9302",
                                     Protocol = "Control4" })

Data shapes

The transcoder address

The agent parses your config reply with the pattern "(.+)@(.+):(.+)", or "(.+):(.+)" when there is no @, into id, ip, and port. The id is unused on the transcoder path; every known target sends 0. Do not use the apple form here.

The apple address

Apple targets are parsed with "c4vc://(.+)@(.+):(.+)/". The scheme and the trailing slash are load-bearing; without them the match fails and the target never starts. The id becomes appled_id in what voiced receives.

What voiced receives

On the current protocol generation the agent re-parses your address into a structured table; on the older generation it forwards the raw string. You never speak this protocol yourself, but its shape is what you will see in logs.

-- registration, current generation ("3.4")
{
  method = "start",
  args = {
    name = "transcoder_0042",              -- instance name
    service = "transcoder",                -- service type
    voice_target_config = {
      target_ip_v4 = "192.168.1.50",
      target_port = 9302,
    },
  },
}

-- older generation ("3.3"): both name and type are "comcast",
-- voice_target_config is the raw address string, and a data field is added

Every message on the daemon socket is JSON terminated by a NUL byte ('\000'), on TCP port 9250 of the main controller. The five methods the agent uses are manage (claim the daemon), status (enumerate services), start, stop, and clear (wipe instance data, then stop).

What comes back

-- status response, one entry per registered service
{
  method = "status",
  data = {
    services = {
      {
        name = "transcoder_0042",
        c4vc_uris = { "c4vc://2853628976@192.168.1.50:9251/" },
        status = { ... },
      },
    },
  },
}

The first entry of c4vc_uris is the URI pushed to input devices for this service. An instance missing from the status list has its URI cleared and is treated as stopped. If your transcoder_<id> is absent, or present with an empty c4vc_uris, the agent never successfully started it; the problem is discovery or enablement, not audio.

The audio stream

What arrives on your socket is signed 16-bit little-endian mono PCM at 16 kHz, in whatever chunk sizes the sender's reads produce. A socket read can land mid-sample; carry leftover bytes across reads if you resample or reframe.

Composer surface

The agent exposes two actions and a handful of properties. The service enables are the switches behind "disabled in the voice UI".

The agent declares no programming commands and no variables. Service enables persist across restarts.

Behavior notes

Integration recipe

The minimum for a transcoder-path target, written with plain entry points. VOICE_PORT should come from a ranged-integer property so it is fixed but movable.

-- 1. driver.xml: the discovery gate, inside <capabilities>
--    <push-to-talk>True</push-to-talk>
--    The device must also be a watchable source in a room.

-- 2. Open the audio server on a fixed port. Listen is asynchronous;
--    the address is not valid until OnListen fires.
local VOICE_PORT = 9302   -- from a property
local gServerUp = false

C4:CreateTCPServer()
  :Option("reuseaddr", true)
  :OnListen(function(server)
    gServerUp = true
    local url = "0@" .. C4:GetControllerNetworkAddress() .. ":" .. VOICE_PORT
    C4:SendToProxy(5001, "SET_PTT_URL", { URL = url, Protocol = "Control4" })
  end)
  :OnAccept(function(server, client)
    client:OnRead(function(cli, data)
      HandleAudioChunk(data)   -- 16 kHz s16le mono PCM; write this yourself
      cli:ReadUpTo(10 * 1024)
    end)
    client:OnDisconnect(function() EndAudioSession() end)
    client:ReadUpTo(10 * 1024)
  end)
  :Listen("*", VOICE_PORT)

-- 3. Answer the UI requests, all gated on readiness.
function UIRequest(strCommand, tParams)
  local host  = C4:GetControllerNetworkAddress() or ""
  local url   = "0@" .. host .. ":" .. tostring(VOICE_PORT)
  local ready = gServerUp and host ~= ""

  if strCommand == "GET_VOICE_TARGET_CONFIG" then
    if not ready then return "<TargetConfig></TargetConfig>" end
    return "<TargetConfig>" .. url .. "</TargetConfig>"

  elseif strCommand == "GET_VOICE_TARGET_TYPE" then
    return "<TargetType>googletv</TargetType>"  -- rewritten to comcast

  elseif strCommand == "GET_PTT_URL" then
    if not ready then return "<PTT><URL></URL><Protocol></Protocol></PTT>" end
    return "<PTT><URL>" .. url ..
           "</URL><Protocol>Control4</Protocol></PTT>"

  elseif strCommand == "GET_VOICE_PROTOCOL" then
    return "<VoiceProtocol>PCM</VoiceProtocol>"

  elseif strCommand == "GET_VOICE_INFO" then
    if not ready then return "<voice_info></voice_info>" end
    return "<voice_info>" .. C4:JsonEncode({
      codec = { id = 1, encoding = "PCM", bitrate = 16000,
                channels = 1, bitqty = 16 },
      host = host, port = VOICE_PORT,
    }) .. "</voice_info>"
  end
end

-- 4. After first install: run the agent's Reinitialize Driver action so
--    the filename enters its map. On later reloads the fixed port keeps
--    the address stable, so the agent never needs to re-point.