Recently Played Manager

The model

The agent stores containers: an album, a playlist, a station, a track. It does not store individual songs as they roll past. One entry is written when playback of a container starts, and it is updated in place if the same container plays again.

Every entry gets a random 20-character key and is filed into three indexes: by key, by room, and by driver. A fourth table holds the timestamp used for ordering. Reads are always scoped. A Navigator asks for a room's history or a driver's history, never the whole store.

Each index is capped at 20 entries. Writes are persisted on a five-second debounce, so a burst of updates costs one flush.

Call flow

Conventions

Finding the agent

The agent is installed automatically and there is exactly one per project. Resolve its device id by filename, and re-resolve it when rooms are registered rather than caching it across a driver restart.

RECENTLY_PLAYED_AGENT = next(C4:GetDevicesByC4iName("recentlyplayed-agent.c4z"))

If the lookup returns nil, skip the integration silently. Every call below is an ordinary C4:SendToDevice to that id.

Payload encoding

Structured arguments cross the boundary as base64-encoded JSON. Anything the agent returns arrives wrapped in a <b64json> element that must be unwrapped before decoding.

-- writing
local key = C4:SendToDevice(RECENTLY_PLAYED_AGENT, "SetHistoryItem", {
  itemInfo = Serialize(itemInfo),
})

-- reading
local ret = C4:SendToDevice(RECENTLY_PLAYED_AGENT, "GetHistoryItemsByRooms", {
  rooms = roomId,
})

local inner = string.match(ret, "<b64json>(.+)</b64json>")
local items = Deserialize(inner)

Room arguments

Anywhere a rooms value is accepted it may be a number, a comma-separated string, or a table of either (nested tables are flattened). A call that resolves to zero rooms is rejected.

Entry points

Which DriverWorks handler a command lands in depends on what is being addressed. The agent has no proxy binding of its own, so commands sent to it arrive as ordinary driver commands; your service driver does have a proxy, so commands the agent sends back arrive on that binding instead.

The four read and replay commands are deliberately exposed on both of the agent's entry points, and the UI handlers forward straight through, so there is one behavior to reason about rather than two. The three maintenance commands are reachable as Composer actions, which arrive as an ExecuteCommand named LUA_ACTION carrying the real name in tParams.ACTION.

Nothing here is declared as a driver command in the agent's own manifest, so none of it appears in Composer programming. The three actions are the entire Composer-visible surface; everything else is code-only.

Library conventions are not the contract

The examples in this document are written against the shared driver library, where EC., UIR. and RFP. are dispatch tables that a generated ExecuteCommand, UIRequest and ReceivedFromProxy route into. That layer is a convenience, not part of the agent's interface. A driver that does not use it writes the plain handler and branches on the command name:

function ReceivedFromProxy(idBinding, strCommand, tParams)
  if strCommand == "PLAY_RECENT" then
    -- …
  elseif strCommand == "GET_CONTAINER_INFO" then
    -- …
  end
end

The same applies to the helpers. Serialize and Deserialize are base64 over JSON and nothing more: C4:Base64Encode(JSON:encode(t)) and its inverse. GetContainerInfo is not an agent concept at all: it is a stub the media service player library ships for drivers to override, called from that library's own GET_CONTAINER_INFO branch. Without the library there is no such function, only the command.

What is genuinely fixed is the wire contract: the command names, the parameter names, and base64-encoded JSON for itemInfo and info.

Driver → agent

Commands a driver sends to the agent's device id. Every one of these is a no-op returning nil while Agent Enabled is Off, except the three maintenance commands at the end.

itemInfo = {
  driverId    = PROXY_ID,        -- required, the calling driver's PROXY device id
  rooms       = "101,102",       -- required, at least one room must resolve
  keyToUpdate = nil,             -- set to update an existing entry in place
  info = {
    driverId  = PROXY_ID,
    container = {
      id       = "12345",        -- required, coerced to a string
      itemType = "album",        -- required, driver's own vocabulary
      title    = "Kind of Blue",
      subtitle = "Miles Davis",
      image    = "https://…/640x640.jpg",
    },
  },
}

Agent → driver

Two commands the agent sends back. They arrive on the driver's proxy binding and must be handled in ReceivedFromProxy. Neither is optional for a driver that wants working history.

function RFP.PLAY_RECENT(idBinding, strCommand, tParams, args)
  local info      = Deserialize(tParams.info)
  local container = info.container or {}

  if container.id and container.itemType and tParams.rooms then
    PlayItem(container.itemType, container.id, tParams.rooms)
  end
end

Navigator surface

Navigator's built-in Listen screen is the primary consumer, and it reaches the agent through the UI request path rather than by sending driver commands. It reads a room's history when the screen opens, replays an entry on tap, and removes one on swipe. These are the same four operations documented above, under the same names and with the same parameters and return values.

historyUpdated

After any write or removal the agent pushes an event to attached user interfaces so a list on screen can refresh without polling.

<historyUpdated>
  <key>a1b2c3…</key>
  <rooms>101,102</rooms>
  <driverId>42</driverId>
</historyUpdated>

On removal, rooms lists only the rooms the entry was actually pulled from, and driverId is omitted entirely if no driver index held the key. Parse these elements by name. The order they are emitted in is not stable between events.

Data shapes

History item

One element of the array returned by either read command.

{
  key       = "kQ7m…",             -- 20 characters
  timestamp = 1731024000,          -- os.time() of the last write
  driverId  = 42,
  roomIds   = "101,102",           -- every room this entry appears in
  info = {
    driverId   = 42,
    driverIcon = "controller://driver/<driver>/icons/device/experience_512.png",
    container  = {
      id               = "12345",
      itemType         = "Album",  -- display string, capitalized
      itemTypeForDriver= "album",  -- original value, use this to replay
      title            = "Kind of Blue",
      subtitle         = "Miles Davis",
      image            = "https://…/640x640.jpg",
    },
  },
}

Results are sorted newest first and deduplicated on a hash of id and itemType, so the same album surfacing from two rooms appears once. The limit is applied after deduplication.

Item type display names

The agent capitalizes the first letter of itemType for display and carries a small internal table of overrides, keyed on driver filename, for the handful of cases where a raw value would read badly in a list, such as an all-caps constant or a fully qualified metadata class name. That table is not extensible from outside the agent, so choosing an itemType that already reads as a noun is the only way to control the label.

Composer surface

Behavior notes

Integration recipe

The minimum a service driver needs. Resolve the agent when rooms are registered, write on playback, and handle the two inbound commands.

-- 1. resolve, when rooms are registered
RECENTLY_PLAYED_AGENT = next(C4:GetDevicesByC4iName("recentlyplayed-agent.c4z"))

-- 2. write, when a container starts playing
local function RecordPlayback(container, rooms)
  if not RECENTLY_PLAYED_AGENT then
    return
  end

  local itemInfo = {
    driverId    = PROXY_ID,
    rooms       = table.concat(rooms, ","),
    keyToUpdate = CurrentQueue.RecentlyPlayedKey,
    info = {
      driverId  = PROXY_ID,
      container = {
        id       = container.id,
        itemType = container.itemType,
        title    = container.title,
        subtitle = container.subtitle,
        image    = container.image,
      },
    },
  }

  local key = C4:SendToDevice(RECENTLY_PLAYED_AGENT, "SetHistoryItem", {
    itemInfo = Serialize(itemInfo),
  })

  if key then
    CurrentQueue.RecentlyPlayedKey = key
  end
end

-- 3. replay
function RFP.PLAY_RECENT(idBinding, strCommand, tParams, args)
  local info      = Deserialize(tParams.info)
  local container = info.container or {}

  if container.id and container.itemType and tParams.rooms then
    PlayItem(container.itemType, container.id, tParams.rooms)
  end
end

-- 4. backfill metadata, only needed if step 2 can omit title and image
function GetContainerInfo(containerId, containerType, keyToUpdate, rooms)
  if not (containerId and containerType and keyToUpdate) then
    return
  end

  LookUpContainer(containerId, containerType, function(data)
    local itemInfo = {
      keyToUpdate = keyToUpdate,
      driverId    = PROXY_ID,
      rooms       = rooms,
      info = {
        driverId  = PROXY_ID,
        container = {
          id       = containerId,
          itemType = containerType,
          title    = data.title,
          subtitle = data.artist,
          image    = data.image,
        },
      },
    }

    C4:SendToDevice(RECENTLY_PLAYED_AGENT, "SetHistoryItem", {
      itemInfo = Serialize(itemInfo),
    })
  end)
end

Drivers built on the standard media service player library get steps 1 and 2 for free: the library resolves the agent when it registers rooms, and writes an entry whenever a queue is built with container information attached. Steps 3 and 4 stay the driver's responsibility, since only the driver knows how to turn an id back into playback.