Agent-controlled stereo recording with stereo_recording

The stereo_recording function is the agent-controlled cousin of the plain recording call. It produces a Stereo recording — a two-channel file with the agent on one side and the customer on the other — triggered through the VICIdial Agent API against a logged-in Agent session. For the broader map of these functions, start with the VICIdial API overview.

When you'd use it

Split-channel audio is worth the extra bookkeeping when you plan to run the file through automated processing. Speech-to-text and Voice analytics engines are far more accurate when the agent and customer sit on separate channels, because nobody talks over the boundary. Quality teams also like it for scoring talk-over and interruptions. You'd start it from your own tooling at the moment you want a clean two-channel capture rather than the default mono mix.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: stereo_recording (agent_user, value=BEGIN)
  API->>V: send start signal to agent screen
  V->>Agent: two-channel capture starts
  V-->>App: SUCCESS stereo_recording function sent
  App->>API: stereo_recording (value=END)
  API->>V: stop active stereo recording
  V-->>App: SUCCESS

Same shape as the mono call: api.php with user and pass, the agent named in agent_user, function=stereo_recording, and a value. The difference is in the values themselves and the one-at-a-time rule below.

Parameters

• value — REQUIRED. BEGIN sends a start signal; END stops all active agent-controlled stereo recordings on the agent screen; STATUS returns active stereo recording and session info (agent-controlled recordings only).
• stage — OPTIONAL. A label appended to the filename, limited to 14 characters (truncated past that). Only works with the BEGIN value.

STATUS returns the same pipe-delimited fields as the mono function — user, recording_id, filename, server, start_time, agent_server, Session ID, agent_status — but only reports on agent-controlled stereo files.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=stereo_recording&value=BEGIN&stage=_MIDCALL

A good start returns SUCCESS: stereo_recording function sent - 6666|BEGIN_MIDCALL||||192.168.1.5|8600051|PAUSED. A STATUS call that finds a live file returns NOTICE: stereo_recording active - 6666|121242|20120810-012008__6666_|192.168.1.5|2012-08-10 01:20:10|192.168.1.5|8600051|PAUSED, and a quiet session returns NOTICE: not stereo_recording. Trying to END when nothing is running gives ERROR: stop stereo_recording error.

Gotchas to watch

The big difference from plain recording: you cannot have multiple agent-controlled stereo recordings running at the same time. One BEGIN, one file — a second BEGIN won't stack the way mono START does. Note the verbs are BEGIN and END here, not START and STOP, so a script written for one function won't drop straight onto the other. Stereo files are roughly double the size of a mono mix, which matters for your Recording retention window and disk planning. If you need plain mono capture instead, the recording lookup function is the companion for finding finished files of either kind.

Want a box where stereo recording and the agent API are wired up from the first login? Take a look at our plans.