Serenada

A simple, privacy-focused video calling application built with WebRTC. No accounts, no tracking, just instant calls with up to 4 participants.

Features

• Instant calls – One tap to start, share a link to connect
• No accounts required – Just open and call
• Privacy-first – No tracking, no analytics, end-to-end encrypted peer-to-peer video
• Resilient signaling – WebSocket with SSE fallback when WS is blocked
• Adaptive multi-party rooms – New-capable clients create group-capable rooms by default, with legacy-first rooms still capped at 2 participants
• Mobile-friendly – Works on Android Chrome, iOS Safari, desktop browsers, and native Android/iOS clients
• Desktop screen sharing (web) – In-call screen share control on desktop browsers that support getDisplayMedia (not shown on mobile browsers)
• Recent calls on home – Web and Android home screens show your latest calls with live room occupancy (Android supports long-press remove)
• Android saved rooms – Name and pin rooms on home, choose whether they appear above or below recent calls, and create links that add named rooms on recipient devices
• Android camera source cycle – In-call source switch cycles through selfie (default) -> world -> composite (world feed with circular selfie overlay), automatically skips composite when unsupported, and shows a flashlight toggle in world/composite when flash hardware is available; flashlight preference is remembered during the call and reapplied when returning to supported modes
• Android world/composite pinch zoom – When local video is the large in-call view in world or composite, pinch gesture zooms the camera capture itself so both local preview and the remote participant see the zoomed detail
• Android HD video toggle (experimental) – Settings include an HD Video (experimental) switch for higher camera/composite quality; default mode keeps legacy 640x480 camera constraints for stability
• iOS native client (SwiftUI) – Native iOS app in client-ios/ mirrors Android parity flow: saved rooms + recents ordering, structured deep-link parsing, invite push toggle, encrypted push snapshots, waiting-room invite action, adaptive multi-party layout with local PIP, diagnostics screen, mode-based camera cycle with composite fallback, world/composite pinch zoom, ReplayKit screen share toggle, and in-call realtime stats/debug panel
• Snapshot capture (all platforms) – SerenadaSession.captureSnapshot(source) returns the current frame at full intrinsic resolution as a JPEG/Blob; the call UI can show an opt-in shutter button anchored to the short edge of the large preview (bottom in portrait, right in landscape)
• Self-hostable – Run your own instance with full control
• Optional join alerts – Encrypted push notifications with snapshot previews (web + native Android + native iOS)
• Room invite push – In waiting state you can explicitly invite subscribers of the room; Android and iOS show these only for saved rooms and have a Settings toggle to disable invite notifications
• In-app feedback – Send bug reports and suggestions directly from the app (web footer, Android/iOS settings); messages are forwarded to a configurable Telegram chat

Quick Start

Local Development (Docker)

1. Copy the environment template:

   cp .env.example .env
   

2. Build the frontend:

   cd client
   npm install
   npm run build
   

3. Start the development stack:

   docker compose up -d --build
   

4. Open http://localhost in your browser

Manual Setup (No Docker)

If you prefer to run the components manually:

1. Frontend (Client)

cd client
npm install
npm run dev

2. Backend (Server)

cd server
go run .

Requires Go 1.24+ and a .env file in the root directory.

Android Client (Kotlin)

The native Android app lives in client-android/.

1. Open client-android/ in Android Studio.
2. Sync Gradle.
3. Run on a device or emulator (minSdk 26).
4. Default WebRTC provider is local7827 (client-android/serenada-core/libs/libwebrtc-7827-universal.aar).
5. Rebuild the patched libwebrtc AAR on Linux with bash tools/build_libwebrtc_android_7827.sh.
6. When updating that AAR, regenerate client-android/serenada-core/libs/libwebrtc-7827-universal.aar.sha256 (Gradle now verifies it before build).

By default the app targets https://serenada.app, and the server host can be changed in Settings. The Android app language can also be set in Settings: Auto (default), English, Русский, Español, Français. Auto follows the device language and falls back to English. To enable native Android push receive, provide Firebase Gradle properties when building the app (firebaseAppId, firebaseApiKey, firebaseProjectId, firebaseSenderId).

iOS Client (Swift + SwiftUI)

The native iOS app lives in client-ios/.

1. Install xcodegen (if not already installed).
2. Generate project files:

   cd client-ios
   xcodegen generate
   

3. Open SerenadaiOS.xcodeproj in Xcode.
4. Run SerenadaiOS on iOS 16+ simulator/device.
5. WebRTC is resolved automatically via SPM from the zello-ios-web-rtc package (pinned in the root Package.swift) — no vendored XCFramework step is needed.
6. For local-only device signing overrides (without committing team IDs), use client-ios/LocalSigning.xcconfig. See client-ios/README.md.

iOS universal links are enabled for serenada.app, ru.serenada.app, and serenada-app.ru via associated domains plus /.well-known/apple-app-site-association. Note: iOS Simulator can run signaling and call flow, but local camera preview reliability varies by host setup; use a physical iPhone to validate local camera capture.

Production Deployment

See DEPLOY.md for detailed self-hosting instructions.

Quick setup script (downloads, installs dependencies, and provisions the stack):

curl -fsSL https://serenada.app/tools/setup.sh -o setup-serenada.sh
bash setup-serenada.sh

Load Testing (WS Signaling)

The server includes an in-repo load conduit for signaling capacity validation.

Quick run (local Docker stack):

./server/loadtest/run-local.sh

What it does:

• Starts local services with ENABLE_INTERNAL_STATS=1
• Sets a local INTERNAL_STATS_TOKEN automatically (override via env if needed)
• Validates /api/room-id and /api/internal/stats
• Runs go run ./cmd/loadconduit from server/
• Writes a JSON report to server/loadtest/reports/

Common overrides:

START_CLIENTS=20 STEP_CLIENTS=20 MAX_CLIENTS=200 STEADY_SECONDS=600 ./server/loadtest/run-local.sh

Stabilization and join-tolerance controls:

PRE_RAMP_STABILIZE_SECONDS=10 MAX_JOIN_ERROR_RATE=0.005 ./server/loadtest/run-local.sh

To avoid local/NAT throttling while testing, set a bypass allowlist:

RATE_LIMIT_BYPASS_IPS=127.0.0.1,::1 ./server/loadtest/run-local.sh

Direct conduit usage:

cd server
go run ./cmd/loadconduit --base-url http://localhost --report-json ./loadtest/reports/manual.json

Detailed request/timing sequence:

• server/loadtest/LOAD_SIMULATION_SEQUENCE.md

Integration Tests

bash tools/integration-test/run.sh    # Run signaling integration tests (requires Go 1.24+)

Version Parity

Verify SDK versions and shared protocol constants match across all platforms:

node scripts/check-version-parity.mjs
node scripts/check-signaling-protocol-constants.mjs

Architecture

┌─────────────────┐         ┌─────────────────┐
│   Browser A     │◄───────►│   Browser B     │
│  (React SPA)    │  WebRTC │  (React SPA)    │
└────────┬────────┘         └────────┬────────┘
         │                           │
         │ WS/SSE (signaling)        │
         ▼                           ▼
┌─────────────────────────────────────────────┐
│              Go Signaling Server            │
└─────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│            STUN/TURN Server (Coturn)        │
└─────────────────────────────────────────────┘

• Frontend: React + TypeScript + Vite
• Backend: Go (signaling server)
• Media: WebRTC with STUN/TURN support via Coturn
• Deployment: Docker Compose with Nginx reverse proxy

SDK Pattern (Headless SDK + Optional UI)

All three native SDKs follow a headless core + optional UI pattern:

• SerenadaCore — Entry point. createRoom() returns the room URL and ID (async on all platforms). Call join() afterward to start the call and get a SerenadaSession.
• SerenadaSession — The active call session. Exposes two observable snapshots:
  • state (CallState) — App-facing call state: phase, local/remote participants, connection status, errors.
  • diagnostics (CallDiagnostics) — Low-level transport info: ICE/peer/signaling states, realtime stats (including active inbound/outbound audio and video codecs), camera/flash state, feature degradations.
• SerenadaCallFlow — Pre-built UI component (SwiftUI / Jetpack Compose / React) that consumes a session and renders the full call flow. Optional — you can build your own UI from state and diagnostics.

Android enforces main-thread access on all public SDK entrypoints with fail-fast preconditions.

Signaling Modes

All SDKs now support two signaling modes through the same SerenadaConfig, and they validate the choice at construction time:

• Built-in Serenada signaling: set serverHost.
• Custom signaling provider: set signalingProvider.

Provide exactly one of serverHost or signalingProvider.

In custom-provider mode:

• join() still creates a normal SerenadaSession.
• The built-in provider-facing identifier is peerId; built-in cid mapping stays internal.
• hostPeerId and roomStateUpdated remain optional.
• runAll() still works, and TURN probing uses provider-supplied ICE servers.
• Server-only APIs require serverHost: createRoom(), native createRoomId(), RoomWatcher, validateServerHost(), and runConnectivityChecks().

On web, provider-delivered peer messages are exposed through session.onPeerMessage(...). Raw Serenada transport envelopes are no longer part of the public SDK surface.

Independent Content Video (Screen Share)

Screen share is moving from the single camera-video path to its own independent content stream, so a capable peer can send camera and screen share at the same time. The SDK surface and media path are gated behind a config flag that is off by default in the headless SDK and enabled explicitly by the bundled Serenada host apps. Third-party host apps should enable it once their media integration and UI can render the content stream. With the flag off, behavior is exactly today's: screen share reuses the camera video path and replaces the camera track while sharing.

• Config flag enableIndependentContentVideo (SerenadaConfig, default false). It advertises capabilities.independentContentVideo=true at join and enables the independent content media path for capable peers. Legacy peers fall back to the single-video screen-share path for that connection.
• Session media policy videoMediaEnabled (SerenadaConfig, default true) is now also signaled at join as mediaPolicy.videoMediaEnabled. It is immutable for the session and controls whether any video (camera or content) is negotiated. Strict audio-only (videoMediaEnabled=false) negotiates no video at all.
• New participant state (remote Participant and LocalParticipant):
  • cameraEnabled — camera video specifically. With the flag on this is the precise camera signal; with the flag off it mirrors videoEnabled.
  • videoEnabled — retained legacy "video active" field; mirrors cameraEnabled when the flag is on.
  • content — { active, type, revision }, the screen-share presentation state (absent when not sharing). type is currently "screenShare"; revision orders quick stop/start toggles.
• New content rendering APIs (the existing camera renderer APIs stay camera-specific):
  • Web: session.getRemoteContentStream(cid), session.getRemoteCameraStream(cid), session.getLocalContentStream().
  • Android: session.attachRemoteContentRenderer(renderer, cid) / detachRemoteContentRenderer(renderer, cid), session.attachLocalContentRenderer(renderer) / detachLocalContentRenderer(renderer).
  • iOS: session.attachRemoteContentRenderer(_:forParticipant:) / detachRemoteContentRenderer(_:forParticipant:), session.attachLocalContentRenderer(_:) / detachLocalContentRenderer(_:).

When enabled, capability and policy are negotiated per peer: a capable peer receives camera and screen share on independent streams; a legacy peer falls back to the single-video model for that connection only (screen share preempts camera on that peer). See the Protocol Specification for the join capability/mediaPolicy fields and content_state wire format.

Pluggable Audio Coordinators

On iOS and Android, the SDKs support a pluggable audio session model via SerenadaAudioCoordinator. This lets the host app control the process-global audio session, routing policies, and Bluetooth state machines (useful when embedding Serenada alongside another audio engine like a push-to-talk system), while retaining the SDK's internal call routing and proximity monitor behaviors.

If audioCoordinator is omitted, the SDK uses its internal default coordinator. The concrete default coordinator is not public API; custom integrations should implement SerenadaAudioCoordinator and inject that implementation through SerenadaConfig.

Configuration

To use a custom coordinator, provide it and an AudioIntent in SerenadaConfig:

iOS (Swift)

let config = SerenadaConfig(
    serverHost: "serenada.app",
    audioCoordinator: MyCustomAudioCoordinator(),
    audioIntent: AudioIntent(
        supportsVideo: true,
        muteOwnMicDuringExternalAudio: true, // Mute when interrupted (e.g. by PTT)
        duckOwnPlaybackDuringExternalAudio: true // Duck remote playback during interruption
    )
)

Android (Kotlin)

val config = SerenadaConfig(
    serverHost = "serenada.app",
    audioCoordinator = MyCustomAudioCoordinator(),
    audioIntent = AudioIntent(
        supportsVideo = true,
        muteOwnMicDuringExternalAudio = true,
        duckOwnPlaybackDuringExternalAudio = true
    )
)

Coordinator Contract

The coordinator implementation is responsible for:

• Activating/deactivating the hardware audio session.
• Managing audio focus, modes, and Bluetooth routing.
• Publishing available devices, current input/output routes, and session events (interruptions, resume, focus changes) to the SDK.

On Android, coordinator handoff is serialized process-wide across Serenada sessions, including handoffs between default and custom coordinators. The SDK does not activate the next coordinator until the previous coordinator's deactivateCallSession() returns. Custom implementations must therefore suspend until focus, mode, route, Bluetooth, and callback cleanup is complete instead of launching cleanup in the background; blocking system work should run off the main thread.

The session exposes coordinator state for custom UI:

• availableAudioDevices: routes published by the active coordinator.
• currentAudioDevice: selected or active output route.
• isMicMuted: effective microphone mute state.
• isMicMutedByExternalAudio: whether external audio is currently forcing a mute.
• selectAudioDevice(...): requests routing to a coordinator-published route.
• setMicMuted(...): sets the user-requested microphone mute state.

Mute & Ducking Composition

The session maintains a composed microphone mute state calculated as: isMicMuted = userMuted || externalAudioMuted || !routeInputAvailable

When the coordinator publishes an audioSessionInterrupted event (e.g., due to incoming/outgoing PTT or a phone call), the SDK:

1. Mutes the local WebRTC track (if muteOwnMicDuringExternalAudio is enabled) to prevent audio leaks.
2. Lowers the volume of all remote participant audio tracks to 15% (if duckOwnPlaybackDuringExternalAudio is enabled).
3. Restores full volume and unmutes the mic cleanly upon receiving audioSessionResumed.

Documentation

• SDK API Reference – Generated API docs for all platforms (Web, Android, iOS)
• Deployment Guide – Self-hosting instructions
• Protocol Specification – Signaling protocol (WebSocket + SSE)
• Push Notifications – Encrypted snapshot notifications
• Snapshot Capture – SerenadaSession.captureSnapshot API and call-UI shutter button
• Android Client README – Kotlin native app setup and build notes
• iOS Client README – SwiftUI native app setup and build notes
• server/loadtest/run-local.sh – Local signaling load sweep runner
• server/loadtest/LOAD_SIMULATION_SEQUENCE.md – Detailed load-conduit HTTP/WS call sequence and timing

Technology

Component	Technology
Frontend	React 19, TypeScript, Vite
Backend	Go 1.24+
Media	WebRTC, Coturn
Proxy	Nginx
Containers	Docker, Docker Compose

License

This project is licensed under the BSD 3-Clause License. See LICENSE for details.