HarborFM

Group Calls (WebRTC)

Group calls let you record remote guests via WebRTC. The host starts a call; guests join by link or code. Recordings can be added as segments in the episode editor.

Note: Group calls require the optional webrtc-service and correct configuration. If you don't see the Record or group-call UI, see the main README section "WebRTC (group calls)" and Deployment: Docker.

Starting and Joining Calls

Group calls use WebRTC so you can record remote guests in real time. The host starts a call from the episode editor; guests join via a link or a short code.

Starting a Call (Host)

  1. Open the episode editor for the episode you want to record.
  2. Use the option to start a group call. The app may ask for microphone (and optionally camera) permission.
  3. Once the call room is created, you'll see a join link and often a 4-digit code. Share the link or code with guests so they can join.
  4. When guests have joined, you can start recording from the in-call controls. See Call settings and recordings.

Guest join links use the podcast linking or managed domain when configured (e.g. https://your-show.example/call/join/...) instead of the app hostname. Join pages serve episode/podcast Open Graph meta for link previews.

If you don't see the group-call option, WebRTC may not be enabled or configured on the instance. See the main README ("WebRTC (group calls)") and ensure WEBRTC_ENABLED, WEBRTC_SERVICE_URL, and WEBRTC_PUBLIC_WS_URL are set. After Hostname is set in Settings, WebRTC Settings values take precedence over WEBRTC_* env vars (env still seeds empty settings). Changing Hostname updates the public WebSocket URL when it still pointed at the previous host.

Joining a Call (Guest)

  1. Open the join link in your browser (or enter the 4-digit code on the call-join page if the host shared it).
  2. Allow microphone (and camera if requested) when the browser asks.
  3. You'll enter the same room as the host. Wait for the host to start recording when ready.

Guests see a recording banner with elapsed time above "You're In The Call" while recording is active. Keep the tab active when possible; on mobile, returning to the tab remounts the mediasoup room if the producer died while backgrounded so you can produce again.

Troubleshooting

  • No audio / can't connect - The server must have UDP ports open for WebRTC (default range 40000–40200, or 41000–41100 in Docker). Behind NAT, the admin must set MEDIASOUP_ANNOUNCED_IP to the server's public IP. See main README and Deployment.
  • No "Record" or group-call UI - Confirm WEBRTC_ENABLED and the WebRTC URLs are set; check server and webrtc-service logs (docker compose logs webrtc or pm2 logs webrtc).
  • Guest drops from participant list after ~10 minutes - Guests send a signaling WebSocket heartbeat every 30s (same as the host) so reverse proxies do not idle-drop /api/call/ws. Ensure your proxy allows long-lived WebSockets.
  • Silent after switching apps on mobile - Returning to the tab should recreate the producer; if audio stays silent, leave and rejoin or have the host restart the call.

See Also

Call Settings and Recordings

During a group call you can use in-call controls, chat, and soundboard, and save the call as a recording that becomes a segment.

In-Call Controls

  • Mute / unmute - Toggle your microphone.
  • Leave - Leave the call (host may have additional options to end the call for everyone).
  • Settings - Mic selector, auto gain control, listen-to-self, volume, and related options.
  • Chat - In-call group chat.
  • Soundboard - Short audio clips with waveform preview and search; play into the call.
  • Wake lock - On mobile, the join page tries to keep the screen awake during calls.

Show Notes for Guests

If the host enables guest visibility on the episode Show Notes panel, participants can open See Show Notes to view planned topics and durations. Notes update live over the call WebSocket. See Episodes: Show Notes.

Recording the Call

  1. As the host, start the call and wait for guests to join (see Starting and joining calls).
  2. Click Record (or "Start recording") in the call UI. All participants' audio is captured (multitrack; guest remounts create a new producer so segments stay time-aligned).
  3. When finished, click Stop recording. The webrtc-service writes the recording to disk; the main app then makes it available.
  4. The recording can be added as a segment to the current episode. Follow the prompt or use the episode editor to attach the recording; it will appear in the segment list like any other segment.

You can then trim, reorder, or combine it with other segments and run Build Final Episode. See Segments.

Host-Away Behavior

If the host leaves or disconnects, the call may stay open for a short grace period (configurable by the instance; page refreshes use a longer remount grace so the call is less likely to end). If the host is away too long, the call may end. Recording is typically tied to the host; if the host leaves during recording, behavior may vary (e.g. recording stops). See main README for HOST_AWAY_GRACE_* and HOST_AWAY_CHECK_INTERVAL_MS.

See Also