Service: Intercom - EyevinnOSC/community GitHub Wiki
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.
- 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.
Create the dependencies first and confirm they are running before creating the Intercom instance:
- A Symphony Media Bridge (
eyevinn-docker-wrtc-sfu) withApiKeyset to a key of your choice, for example{ "name": "intercom", "ApiKey": "{{secrets.smbkey}}" }. Note its URL (describe-service-instance) and the key. - A CouchDB instance (
apache-couchdb) named for exampleintercomwith 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 (namedintercom) 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.
| 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.
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).
- User settings: enter a display name and choose audio input/output devices.
- 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).
- Manage productions: rename productions or lines, add lines, delete a line or production. Deletion is only possible when there are no active participants.
- 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.
-
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. -
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.
| 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. |
- 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.
- intercom-manager and intercom-frontend on GitHub
- companion-module-eyevinn-intercom for Bitfocus Companion and Stream Deck
- Working with Secrets
- Support: [email protected]