# moonlight-stream/moonlight-android architecture

> Architecture diagram of the GitHub repository moonlight-stream/moonlight-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moonlight-stream/moonlight-android
- Repository: https://github.com/moonlight-stream/moonlight-android

## Overview

##### Project type and purpose
- Moonlight Android is a native Android client application for NVIDIA GameStream and the open-source Sunshine server.
- It is not a web service or back-end system; it is a mobile (Android) full-feature media-streaming application with a Java/Kotlin UI layer, platform bindings, networking, and a native (C/C++) streaming core.

##### File structure
- Top-level “app” folder: Android Studio project with Gradle build scripts, Java source under app/src/main/java, resources under app/src/main/res, and JNI code under app/src/main/jni.
- LuaScripts directory: additional scripts for parsing, not core to Android build.
- JNI folder “moonlight-core”: the native streaming engine, with OpenSSL, libopus, SDL-like layers.
- Subdirectories under java/com/limelight:
- binding – platform abstractions (audio, crypto, input, video)
- nvstream – implementation of the streaming protocol (connection management, packet handling, HTTP pairing, MDNS discovery, WOL)
- ui – Android Activities, Views, Adapters, Fragments
- utils, grid, preferences, discovery, computers – support services and models

##### Key insights from README
- Confirms purpose: “stream your full collection of games from your Windows PC to your Android device.”
- Requires Android NDK for native core.
- Mentions two external servers: NVIDIA GameStream (on PC) and Sunshine.

##### Main components
a. Frontend/UI Layer (Java/Kotlin)
- Activities & Views (AppView, StreamView, PcView, GridAdapters)
- Preferences & Configuration UI
b. Platform Binding Layer
- Audio: AndroidAudioRenderer → AudioTrack
- Video: MediaCodecDecoderRenderer → SurfaceView/TextureView
- Crypto: AndroidCryptoProvider → JNI/OpenSSL
- Input capture & translation (touch, virtual controllers, external game controllers via USB/Bluetooth)
c. Networking & Protocol Layer (pure Java under nvstream)
- PairingManager & NvHTTP (HTTP pairing & authentication)
- NvConnection & StreamConfiguration (TCP/UDP transport of RTP-like A/V data)
- MDNS discovery agents (JmDNS, Android NSD)
- Wake-on-LAN sender
d. Native Streaming Core (JNI + C/C++)
- moonlight-core library: implements core GameStream protocol, packetization, encryption/decryption using OpenSSL, audio codec via libopus, minimal SDL glue
- JNI bridge (MoonBridge) connecting Java nvstream code to native core
e. External Services
- Windows PC GameStream server or Sunshine server
- Network (local LAN or Internet)
- mDNS / DNS-SD for local discovery

##### Relationships & interactions
- UI triggers discovery → Platform Binding (DiscoveryService) → MDNS → lists available hosts
- UI initiates pairing → NvHTTP → server → returns credentials → stored via CryptoProvider
- UI starts streaming → NvConnection (Java) calls native moonlight-core (MoonBridge) → sets up RTP/DTLS over UDP
- Incoming video/audio packets arrive in native core → decrypted (OpenSSL) → decoded (libopus for audio, passed back to Java for MediaCodec video)
- Decoded frames → Platform Binding renderers → displayed in UI / AudioTrack output
- UI feeds input events (touch/controller) into InputCaptureManager → ControllerPacket/KeyboardPacket → NvConnection → native core → sends to server
- Settings, preferences, logs handled by Util classes and stored in ContentProvider

##### Architectural patterns & design principles
- Layered architecture: UI → Platform Binding → Protocol/Service → Native Core
- Separation of concerns:
- Java code handles Android-specific APIs, lifecycle, high-level protocol
- Native C/C++ code focuses purely on streaming protocol, performance-critical code
- Plug-in binding modules: each platform capability (audio, video, crypto, input) implemented behind an interface to allow testing or stubbing (NullCaptureProvider)
- Use of JNI as boundary: minimizes native footprints to one library (moonlight-core)

##### Detailing
- Resource files (layouts, drawables) and scripts (LuaScripts) as annotations or side-notes if needed, but focus on runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        direction TB
        AppView["AppView"]:::java
        PcView["PcView"]:::java
        HelpActivity["HelpActivity"]:::java
        Game["Game Model"]:::java
    end

    %% Platform Binding Layer
    subgraph "Platform Binding Layer"
        direction TB
        AudioRenderer["AndroidAudioRenderer"]:::java
        VideoRenderer["MediaCodecDecoderRenderer"]:::java
        CryptoProvider["AndroidCryptoProvider"]:::java
        InputBinding["Input Binding (touch/virtual/controller)"]:::java
    end

    %% Protocol & Services Layer
    subgraph "Protocol & Services"
        direction TB
        PairingManager["PairingManager"]:::java
        NvHTTP["NvHTTP"]:::java
        NvConnection["NvConnection"]:::java
        StreamConfig["StreamConfiguration"]:::java
        MDNS["MDNS Discovery Agents"]:::java
        WOL["Wake-on-LAN Sender"]:::java
        AVTransport["AV Transport (RTP/UDP)"]:::java
        InputPackets["InputPacket Handlers"]:::java
    end

    %% JNI Boundary
    subgraph "JNI Boundary"
        direction TB
        MoonBridge["MoonBridge (JNI Bridge)"]:::java
    end

    %% Native Streaming Core
    subgraph "Native Streaming Core"
        direction TB
        CoreLib["moonlight-core Library"]:::native
        OpenSSL["OpenSSL"]:::native
        Opus["libopus"]:::native
        MiniSDL["Mini SDL Glue"]:::native
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GameStream["GameStream/Sunshine Server"]:::external
        Network["LAN/Internet"]:::external
        DNS_SD["mDNS / DNS-SD"]:::external
    end

    %% Connections
    AppView -->|triggers discovery| MDNS
    PcView -->|triggers discovery| MDNS
    HelpActivity -->|accesses prefs| CryptoProvider
    Game -->|loaded prefs| CryptoProvider

    MDNS -->|lists hosts| AppView
    AppView -->|init pairing| PairingManager
    PairingManager -->|HTTP auth| NvHTTP
    NvHTTP -->|requests creds| GameStream
    GameStream -->|returns creds| NvHTTP
    NvHTTP -->|provides creds| AppView

    AppView -->|start stream| NvConnection
    NvConnection -->|configure| StreamConfig
    NvConnection -->|call native| MoonBridge
    MoonBridge -->|init core| CoreLib

    CoreLib -->|uses| OpenSSL
    CoreLib -->|uses| Opus
    CoreLib -->|uses| MiniSDL

    CoreLib -->|stream data| MoonBridge
    MoonBridge -->|packets| NvConnection
    NvConnection -->|deliver audio| AudioRenderer
    NvConnection -->|deliver video| VideoRenderer

    AppView -->|capture input| InputBinding
    InputBinding -->|generate packets| InputPackets
    InputPackets -->|send via| NvConnection
    NvConnection -->|send to| CoreLib
    CoreLib -->|network| Network
    Network -->|to/from| GameStream

    %% Click Events
    click AppView "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/AppView.java"
    click PcView "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/PcView.java"
    click HelpActivity "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/HelpActivity.java"
    click Game "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/Game.java"
    click AudioRenderer "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/binding/audio/AndroidAudioRenderer.java"
    click VideoRenderer "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/binding/video/MediaCodecDecoderRenderer.java"
    click CryptoProvider "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/binding/crypto/AndroidCryptoProvider.java"
    click InputBinding "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/java/com/limelight/binding/input"
    click PairingManager "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/http/PairingManager.java"
    click NvHTTP "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/http/NvHTTP.java"
    click NvConnection "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/NvConnection.java"
    click StreamConfig "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/StreamConfiguration.java"
    click MDNS "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/java/com/limelight/nvstream/mdns"
    click WOL "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/wol/WakeOnLanSender.java"
    click AVTransport "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/java/com/limelight/nvstream/av"
    click InputPackets "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/java/com/limelight/nvstream/input"
    click MoonBridge "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/java/com/limelight/nvstream/jni/MoonBridge.java"
    click CoreLib "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/jni/moonlight-core"
    click OpenSSL "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/jni/moonlight-core/openssl"
    click Opus "https://github.com/moonlight-stream/moonlight-android/tree/master/app/src/main/jni/moonlight-core/libopus"
    click MiniSDL "https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/jni/moonlight-core/minisdl.c"

    %% Styles
    classDef java fill:#D0E8FF,stroke:#1E90FF,stroke-width:1px
    classDef native fill:#FFE8C0,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#888888,stroke-width:1px
```
