This document provides a high-level introduction to the Stream Video Android SDK architecture, its major components, and how they interact. The SDK is a complete solution for building video calling, audio rooms, and livestreaming applications on Android, built on top of WebRTC and the Stream backend infrastructure.
For step-by-step setup instructions, see Getting Started. For detailed information about individual modules, see SDK Modules. For core programming concepts, see Key Concepts.
Sources: README.md1-205 development.md1-300
The Stream Video Android SDK enables developers to integrate real-time video and audio communication features into Android applications. The SDK provides:
stream-video-android-core): Complete WebRTC integration, call management, state synchronization, and backend communicationstream-video-android-ui-compose, stream-video-android-ui-xml): Pre-built, customizable UI for common video calling scenariosThe SDK is designed to support a 99.999% uptime SLA by leveraging Stream's global edge network and automatic failover mechanisms.
Sources: README.md23-96 stream-video-android-core/todo.md1-50
The SDK follows a layered architecture with clear separation of concerns. Applications can integrate at any level depending on their customization requirements.
Module Descriptions:
| Module | Purpose | Size (Release) |
|---|---|---|
stream-video-android-core | WebRTC integration, call logic, state management, API clients | 12.00 MB |
stream-video-android-ui-compose | Jetpack Compose UI components for video calls | 6.28 MB |
stream-video-android-ui-xml | Traditional XML/View-based UI components | 5.67 MB |
stream-video-android-ui-core | Shared UI logic, base activities, styling | N/A |
stream-video-android-filters-video | Video filters using ML Kit (blur, background replacement) | N/A |
stream-video-android-previewdata | Mock objects for UI previews and testing | N/A |
Sources: README.md1-25 metrics/size.json1-13 development.md92-98
The stream-video-android-core module contains the essential functionality for video calling. The main components and their relationships are shown below.
Key Classes and Their Responsibilities:
StreamVideoBuilder: Factory for creating StreamVideoClient instances with configuration options (StreamVideoBuilder.kt106-290)StreamVideoClient: Main entry point implementing StreamVideo interface; manages calls, handles authentication, coordinates backend communication (StreamVideoClient.kt1-1500)ClientState: Observable global state including connection status, current user, active call, and ringing call (ClientState.kt60-250)Call: Represents a single call instance with type and ID; provides methods for join, leave, device control, and participant management (Call.kt146-1250)CallState: Observable per-call state including participants, members, recording status, screen sharing, and reactions (CallState.kt219-1500)RtcSession: Manages WebRTC peer connections, SDP negotiation, ICE candidates, and media track lifecycle (RtcSession.kt210-2200)MediaManagerImpl: Abstracts platform media APIs; provides unified interface for camera, microphone, speaker, and screen sharing (MediaManager.kt1-800)Sources: stream-video-android-core/Call.kt146-171 stream-video-android-core/CallState.kt219-260 stream-video-android-core/StreamVideo.kt43-57 stream-video-android-core/StreamVideoClient.kt1-100 stream-video-android-core/call/RtcSession.kt210-270 stream-video-android-core/MediaManager.kt1-100
The SDK implements a fully reactive architecture using Kotlin's StateFlow for unidirectional data flow.
State Hierarchy:
ClientState: Global state shared across all calls
CallState: Per-call state scoped to a single call instance
ParticipantState objectsMemberState objects (permanent call members)ParticipantState: Per-participant state for active call participants
StateFlow<VideoTrack?>, StateFlow<AudioTrack?>)This three-tier hierarchy enables fine-grained UI updates: changes to a single participant's audio level only trigger recomposition of components observing that specific participant, not the entire call UI.
Sources: stream-video-android-core/CallState.kt219-450 stream-video-android-core/ClientState.kt60-200 development.md107-113
A call progresses through multiple states from creation to termination. The RealtimeConnection sealed interface defines these states.
Connection States:
| State | Description | Exposed By |
|---|---|---|
PreJoin | Initial state before call.join() | Call.state.connection |
InProgress | Join API call in flight | Call.state.connection |
Joined | Backend confirmed, RtcSession created | Call.state.connection |
Connected | WebRTC peer connections established, media flowing | Call.state.connection |
Reconnecting | Temporary connection loss, attempting recovery | Call.state.connection |
Migrating | Switching to different SFU server | Call.state.connection |
Disconnected | Call ended normally | Call.state.connection |
Failed | Permanent failure | Call.state.connection |
Reconnection Strategy:
The SDK implements two reconnection strategies based on disconnection duration:
Sources: stream-video-android-core/CallState.kt169-204 stream-video-android-core/Call.kt499-670 development.md123-160
The SDK communicates with two distinct backend systems using different protocols.
Coordinator Responsibilities:
getCall, createCall, updateCall)ProductvideoApi interface with 90+ REST endpointsSFU (Selective Forwarding Unit) Responsibilities:
SignalServerService with protobuf-based gRPC-like protocolNetwork Resilience:
PersistentSocket for automatic reconnectionRtcSessionGoAwayEvent for graceful server shutdownsSources: stream-video-android-core/api/stream-video-android-core.api1-100 stream-video-android-core/StreamVideoClient.kt1-200 stream-video-android-core/call/RtcSession.kt210-260 development.md99-106
The SDK uses a multi-module Gradle build with version catalogs and custom build conventions.
Module Dependencies:
Key Build Files:
| File | Purpose |
|---|---|
settings.gradle.kts | Defines module structure, includes custom build logic |
gradle/libs.versions.toml | Centralized dependency versions (WebRTC 1.3.6, Compose, etc.) |
build-logic/ | Custom Gradle convention plugins for shared configuration |
stream-video-android-bom/build.gradle.kts | BOM for consistent versioning across modules |
External Dependencies:
stream-webrtc:1.3.6 (Stream's fork with custom patches)CI/CD Workflows:
android.yml: Build and test on every PR and pushsdk-size-checks.yml: Monitor SDK size impact on PRssdk-size-updates.yml: Update size metrics on develop branchpublish-new-version.yml: Maven Central publishing on release tagsSources: gradle/libs.versions.toml1-100 settings.gradle.kts1-50 .github/workflows/android.yml1-23 .github/workflows/sdk-size-checks.yml1-21
Basic SDK initialization:
Creating and joining a call:
For detailed initialization options, see Client Initialization and Configuration.
Sources: stream-video-android-core/StreamVideoBuilder.kt106-194 README.md36-63 stream-video-android-core/Call.kt146-180
Running Tests:
The SDK includes both unit tests and integration tests. Unit tests use Robolectric, while integration tests run on real devices or emulators.
Test Infrastructure:
TestBase: Base class for unit tests with mocked dependenciesIntegrationTestBase: Base class for integration tests with real backend connectionsstream-video-android-previewdata moduleFor detailed testing documentation, see Testing.
Sources: development.md61-88 stream-video-android-core/src/test/kotlin/io/getstream/video/android/core/ClientAndAuthTest.kt1-50 stream-video-android-core/src/androidTest/kotlin/io/getstream/video/android/core/AndroidDeviceTest.kt1-100
Sources: README.md1-205
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.