Android SDK installation and setup

MeshStream Android SDK adds P2P media delivery to an Android player. Your app keeps its existing player; the SDK manages playback sessions, media request routing, and CDN fallback.

Platform and minimum version

Item	Current release support
Android version	ARM32 / x86: Android 4.2 (API 17)+; ARM64 / x86_64: Android 5.0 (API 21)+
CPU ABI	armeabi-v7a, arm64-v8a, x86, and x86_64 in one universal AAR
Java / Kotlin	Java 8 or Kotlin projects
Example player	Media3 / ExoPlayer; selected and managed by the application

Current release support

Version 1.0.9 includes four ABIs in one Maven package for ARM devices and ARM64, x86, and x86_64 emulators. The historical 1.0.8 ARM32 / ARM64 and 1.0.7 ARM64 artifacts remain unchanged.

ARM32 / x86 target API 17 and ARM64 / x86_64 target API 21. Your player may require a newer version; the Media3 Demo requires API 24.

Before you start

Prepare:

• An SDK Key created in the console;
• A player that supports your target media format, such as Media3/ExoPlayer;
• A playable HLS .m3u8, DASH .mpd, or an MP4/MP3 URL with Range support.

The player remains responsible for manifest parsing, ABR, decoding, and rendering. The SDK does not replace the player or change its quality policy.

Project configuration

Java / Kotlin compilation target

The SDK uses Java 8 bytecode. The host project must support Java 8 or newer. For a Java 8 application, for example, configure its module's build.gradle.kts:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

Keep existing Java 11/17 or newer targets and align the Kotlin JVM target with the Java target. Flutter, React Native, and Uniapp projects must also satisfy their framework's JDK requirements.

Network permissions

The Maven artifact declares these permissions. Gradle merges them into your application Manifest; neither requires a runtime permission prompt:

Permission	Purpose
android.permission.INTERNET	Access media origins, acceleration services, and peers
android.permission.ACCESS_NETWORK_STATE	Detect network type and connectivity changes

The SDK does not require additional external storage read/write or ACCESS_WIFI_STATE permissions. Configure any permissions required by your player, downloads, or other application features separately. Before release, check Android Studio's Merged Manifest to confirm your host rules have not removed the network permissions above.

Add the dependency

MeshStream Android SDK is distributed through Maven. Add the repository below to your project repository configuration, then declare the dependency in your application module. This example uses Kotlin DSL:

repositories {
    google()
    mavenCentral()
    maven {
        url = uri("https://sdk.meshstream.net/maven")
        content { includeGroup("io.meshstream") }
    }
}

dependencies {
    implementation("io.meshstream:meshstream-android-sdk:1.0.9")
}

Gradle resolves and downloads the SDK and its native dependencies automatically; you do not need to download or copy an AAR manually. Version 1.0.9 includes armeabi-v7a, arm64-v8a, x86, and x86_64; devices and emulators use the same Maven dependency.

For production projects, pin the SDK version and keep the repository URL in a project-level build configuration for centralized maintenance. The dependency coordinate is io.meshstream:meshstream-android-sdk; upgrading only requires changing the version number.

Allow the local playback proxy

session.playbackUrl uses an on-device http://127.0.0.1:<port>/ proxy. Android 9+ blocks cleartext traffic by default for apps targeting API 28+, so the player must be allowed to access this loopback address even when the original media uses HTTPS.

On Android 7.0 (API 24)+, allow only loopback addresses in the application module's src/main/res/xml/network_security_config.xml so the policy applies to both Debug and Release:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">127.0.0.1</domain>
        <domain includeSubdomains="false">localhost</domain>
    </domain-config>
</network-security-config>

Reference android:networkSecurityConfig="@xml/network_security_config" on <application> in AndroidManifest.xml. Merge the loopback rule into any existing network policy. Android 6.0 (API 23) does not support per-domain exceptions; set android:usesCleartextTraffic="true" there if permitted by your application's network policy. On API 24+, the network security configuration takes precedence. Public HTTP media origins require a separate rule; HTTPS origins do not need a cleartext exception.

Shrinking and memory

R8 / ProGuard

The released AAR contains consumer ProGuard rules that preserve its public API and JNI bridge. Gradle applies them automatically when you integrate through Maven and enable R8; you do not need to copy another SDK's keep rules.

Configure your application's and player's own rules as required. Before publishing, validate initialization, playback, statistics, and resource cleanup with the actual Release build that enables shrinking and obfuscation.

Media cache budget

The SDK does not require android:largeHeap="true" by default. This option primarily affects the Java/ART heap; it does not replace native memory controls or guarantee protection from out-of-memory conditions.

Set the per-client media cache budget with P2pConfig.maxMemoryBytes, which defaults to 64 MiB. Memory-sensitive applications can adjust it to their device and workload, for example:

val client = P2pSdk.create(
    applicationContext,
    P2pConfig(
        key = "your_sdk_key",
        maxMemoryBytes = 16L * 1024 * 1024,
    ),
)

This budget applies only to SDK media caching, not total process memory. The player, decoder, connections, and in-flight requests have other costs. Account for all client budgets when creating multiple clients; smaller budgets may also reduce the segments available for P2P reuse. Close sessions when changing content or leaving the playback screen, and close clients when no longer needed.

Next step

After completing the setup above, continue to Quick integration to create a session, connect your player, and release playback resources.