Service: Intercom - EyevinnOSC/community GitHub Wiki

Open Intercom

Open Source Intercom (serviceId eyevinn-intercom-manager) is a low-latency, browser-based voice intercom built on WebRTC for broadcast and media production environments. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. It is powered by the Symphony Media Bridge open source media server. License: MIT. Source: Eyevinn/intercom-manager (backend) and Eyevinn/intercom-frontend.

Key concepts:

  • A production is a communication session, typically one per show or event.
  • A line is an audio channel within a production; participants on the same line hear each other.
  • An Audio Feed line is a listen-only monitoring channel (for example program output from a mixer).
  • A Saved Configuration is a named set of lines you can rejoin with one click, optionally with a Bitfocus Companion address.

What it can do

  • Real-time audio communication organized into productions and lines, with push-to-talk and hotkeys.
  • WHIP ingress and WHEP egress for lines, so external audio sources (OBS, hardware encoders) can feed a line and external players or recorders can listen.
  • Share lines with external users through single-use invite links (needs oscAccessToken).
  • Save and share configurations; Stream Deck integration through the Bitfocus Companion module.

Creating an instance

Create the dependencies first and confirm they are running before creating the Intercom instance:

  1. A Symphony Media Bridge (eyevinn-docker-wrtc-sfu) with ApiKey set to a key of your choice, for example { "name": "intercom", "ApiKey": "{{secrets.smbkey}}" }. Note its URL (describe-service-instance) and the key.
  2. A CouchDB instance (apache-couchdb) named for example intercom with an admin password. Use only alphanumeric characters in the password: characters such as @, :, / or # break the database connection URL. Then create a database inside it (named intercom) using the CouchDB admin panel (Fauxton) at the instance URL.

Each Intercom instance needs its own dedicated database. Do not share a CouchDB host and database name between Intercom instances; use a separate CouchDB instance per Intercom, or distinct database names (for example /intercom-show1 and /intercom-show2) in one CouchDB instance.

Store sensitive values as service secrets (create-service-secret, serviceId: "eyevinn-intercom-manager"). Because dbUrl embeds the password, store the whole URL as one secret. Then call create-service-instance with serviceId: "eyevinn-intercom-manager":

{
  "name": "tutorial",
  "smbUrl": "https://<tenant>-intercom.eyevinn-docker-wrtc-sfu.auto.prod-se.osaas.io",
  "smbApiKey": "{{secrets.smbkey}}",
  "dbUrl": "{{secrets.intercomdburl}}",
  "oscAccessToken": "{{secrets.osctoken}}"
}

where the intercomdburl secret holds https://admin:<password>@<tenant>-intercom.apache-couchdb.auto.prod-se.osaas.io/intercom. Verify with wait-for-service-ready or describe-service-instance, then open the instance URL in a browser.

A dedicated portal at intercom.apps.osaas.io can also deploy a ready-made Intercom site (database and media bridge on shared infrastructure) from a site name of lowercase letters and numbers. Use the manual setup above if you need a dedicated Symphony Media Bridge, a custom database, or self-hosting of any component.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/word characters only (^\w+$), at most 20 characters.
smbUrl Yes string URL of the Symphony Media Bridge (must start with http). The catalog associates it with eyevinn-docker-wrtc-sfu.
smbApiKey Yes string, sensitive API key of that Symphony Media Bridge; must match the ApiKey set on the bridge. Example format: myPassword123.
dbUrl Yes string, sensitive CouchDB URL including credentials, with the database as path, for example https://admin:<password>@<host>/intercom (must start with http). The catalog associates it with apache-couchdb (default user admin, default path intercom).
oscAccessToken No string, sensitive OSC personal access token used for link sharing and reauthentication. Without it, sharing lines with external users does not work.
whipAuthKey No string, sensitive Authentication key for the WHIP endpoints, used to secure WHIP media ingestion.
iceServers No string Comma-separated list of STUN/TURN servers for WebRTC connectivity. Format: turn:username:[email protected],stun:stun.example.com. If no STUN server is given and WHIP endpoints are used, stun:stun.l.google.com:19302 is used automatically.

A {{secrets.NAME}} reference must be the whole field value. Secrets referenced must exist in this service's scope; a missing secret gives no immediate error.

Using the instance

Requirements for users: Chrome 115+, Edge 115+, Firefox 113+, Safari 16.4+ or Opera 101+, and a microphone (the app asks for permission on first visit; if blocked, reset it through the lock icon in the address bar and reload).

  1. User settings: enter a display name and choose audio input/output devices.
  2. Create a production: click Create, enter a production name and a first line; add lines with + Add Line; tick Audio Feed on listen-only lines. Example for a live broadcast: "Director" line, "Talent" line, and a "Program Feed" line (Audio Feed).
  3. Manage productions: rename productions or lines, add lines, delete a line or production. Deletion is only possible when there are no active participants.
  4. Join a line: expand a production card and click Join. The call view shows participants, push-to-talk, mute controls and hotkey configuration; the kebab menu offers line sharing and WHIP/WHEP URLs.
  5. Invite others: team members (invited to your OSC tenant) open the Intercom service and see the same productions. For external users, generate single-use invite URLs from the share icon on a production card or Share Line in the call kebab menu; each URL works once, so generate one per recipient. This needs oscAccessToken.
  6. Save configurations: while in calls, click Save Configuration, choose Public (stored on the server, visible to all users of the instance) or Local (browser only), and optionally a Companion address (host:port). Saved configurations record your role on Audio Feed lines. Configurations can be joined, shared by URL, edited and deleted from the landing page.

Hotkeys: mute/unmute, push-to-talk, speaker on/off, volume up/down, and P for global mute of all lines (configure from the call kebab menu).

WHIP/WHEP: push audio from OBS, hardware encoders or other WebRTC sources into a line, or pull audio from a line into external players or recorders. Generate the URLs from the call kebab menu.

API documentation (Swagger UI) is available at /api/docs/ on the running instance.

Troubleshooting

Problem Possible cause Solution
No audio Microphone blocked, or wrong input device Allow the microphone and reload; reopen settings from your username (top-right) and select the right device.
"Browser not supported" Outdated browser Update to a supported version.
Instance does not start Wrong database URL, missing database, unreachable SMB, missing secret Check dbUrl format https://admin:<password>@<host>/<database>, that the database exists, that smbUrl is reachable and the key matches, and use get-logs-for-instance.
Sharing does not work Missing oscAccessToken Set oscAccessToken on the instance.
Echo or feedback Multiple tabs open Join a line from one browser tab only.
Connection drops Restrictive network or firewall WebRTC needs UDP access; ask your network admin about STUN/TURN.

Limitations

  • The manual setup uses three service instances (Symphony Media Bridge, CouchDB, Intercom), which count against your plan's service slots.
  • Each Intercom instance needs its own database name.

Resources

⚠️ **GitHub.com Fallback** ⚠️