Development Setup Guide¶

This guide will help you set up a development environment for Gazer Mobile Stream Studio.

Prerequisites¶

Required Software¶

Android Studio: Hedgehog 2023.1.1 or newer
JDK: Java Development Kit 17 or newer
Git: For version control
Python 3.8+: For documentation building (MkDocs)

Hardware Requirements¶

Development Machine: Windows 10/11, macOS 10.14+, or Ubuntu 18.04+
Android Device: Physical device with USB Host support for testing
USB Capture Card: For complete functionality testing

Development Environment Setup¶

1. Clone the Repository¶

# Clone the main repository
git clone https://github.com/yourusername/android-rtmp.git
cd android-rtmp

# If you're contributing, fork first and clone your fork
git clone https://github.com/YOUR_USERNAME/android-rtmp.git
cd android-rtmp

# Add upstream remote for keeping your fork updated
git remote add upstream https://github.com/yourusername/android-rtmp.git

2. Android Studio Setup¶

Download Android Studio
Download from developer.android.com
Install with default settings
Install Required SDK Components
Open SDK Manager (Tools → SDK Manager)
Install the following:
- Android SDK Platform 34 (target)
- Android SDK Platform 24 (minimum)
- Android SDK Build-Tools 34.0.0
- Android Emulator (optional)
- USB Driver (Windows only)
Open Project
Launch Android Studio
Select "Open an Existing Project"
Navigate to the cloned android-rtmp directory
Wait for Gradle sync to complete

3. Project Structure Overview¶

android-rtmp/
├── app/                          # Main application module
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/androidrtmp/    # Kotlin source code
│   │   │   ├── res/                     # Android resources
│   │   │   └── AndroidManifest.xml      # App manifest
│   │   ├── test/                        # Unit tests
│   │   └── androidTest/                 # Instrumentation tests
│   ├── build.gradle.kts                 # Module build configuration
│   └── proguard-rules.pro               # ProGuard configuration
├── gradle/                              # Gradle wrapper files
├── docs/                                # Documentation (MkDocs)
├── .github/workflows/                   # GitHub Actions
├── build.gradle.kts                     # Root build configuration
├── settings.gradle.kts                  # Gradle settings
├── mkdocs.yml                          # Documentation configuration
└── README.md                           # Project README

4. Build Configuration¶

The project uses Kotlin DSL for Gradle configuration:

Root `build.gradle.kts`:¶

plugins {
    id("com.android.application") version "8.1.4" apply false
    id("org.jetbrains.kotlin.android") version "1.9.10" apply false
}

App `build.gradle.kts`:¶

android {
    namespace = "com.androidrtmp"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.androidrtmp"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

Development Workflow¶

1. Building the Project¶

# Clean build
./gradlew clean

# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

# Install debug build on connected device
./gradlew installDebug

2. Running Tests¶

# Run unit tests
./gradlew test

# Run instrumentation tests (requires connected device)
./gradlew connectedAndroidTest

# Run specific test class
./gradlew test --tests="com.androidrtmp.UsbCaptureManagerTest"

3. Code Quality¶

# Run lint checks
./gradlew lint

# Generate lint report
./gradlew lintDebug

IDE Configuration¶

Android Studio Preferences¶

Code Style
File → Settings → Editor → Code Style → Kotlin
Set tab size to 4 spaces
Enable "Use tab character" = false
File Templates
Add copyright header template
Configure Kotlin file templates
Plugins (Recommended)
Kotlin
Android
Git Integration
Markdown Support

Git Configuration¶

# Set up Git user (if not already done)
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Set up commit message template (optional)
git config --global commit.template .gitmessage

Documentation Development¶

MkDocs Setup¶

The project uses MkDocs with Material theme for documentation:

# Install Python dependencies
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

# Deploy to GitHub Pages (maintainers only)
mkdocs gh-deploy

Documentation Structure¶

docs/
├── index.md              # Homepage
├── usage.md              # User guide
├── contributors.md       # Contribution guide
├── api/
│   ├── architecture.md   # Architecture overview
│   └── components.md     # Component API reference
└── dev/
    ├── setup.md         # This file
    └── testing.md       # Testing guide

Development Tools¶

Useful Android Studio Shortcuts¶

Ctrl/Cmd + Shift + A: Find Action
Ctrl/Cmd + N: Go to Class
Ctrl/Cmd + Shift + N: Go to File
Ctrl/Cmd + Alt + L: Reformat Code
Ctrl/Cmd + Alt + O: Optimize Imports
Shift + F6: Refactor → Rename

ADB Commands¶

# List connected devices
adb devices

# Install APK
adb install app/build/outputs/apk/debug/app-debug.apk

# View logs
adb logcat

# View logs for specific package
adb logcat | grep "com.androidrtmp"

# Clear app data
adb shell pm clear com.androidrtmp

Debugging USB Issues¶

# List USB devices
adb shell lsusb

# Check USB host support
adb shell cat /proc/bus/usb/devices

# Monitor USB events
adb shell getevent | grep usb

Hardware Setup for Testing¶

USB Capture Card Testing¶

Compatible Devices
Elgato Cam Link series
Generic HDMI to USB adapters
AVerMedia capture devices
Test Setup
Connect video source to capture card
Connect capture card to Android device
Use USB OTG adapter if necessary
Verification
Device appears in USB device list
App recognizes as compatible device
Video preview works correctly

Troubleshooting¶

Common Issues¶

Gradle Sync Failed¶

# Clear Gradle caches
./gradlew clean
rm -rf ~/.gradle/caches/

USB Host Not Working¶

Verify device supports USB Host mode
Check USB OTG cable/adapter
Ensure proper USB permissions in manifest

Build Errors¶

Check Android SDK installation
Verify Kotlin version compatibility
Clean and rebuild project

Emulator Issues¶

Use physical device for USB functionality
Emulator doesn't support USB Host mode
Some features require real hardware

Getting Help¶

Documentation: Check existing docs first
Issues: Search GitHub issues
Discussions: Use GitHub discussions for questions
Stack Overflow: Tag with android and rtmp

Contributing Workflow¶

Before Starting Development¶

Create Issue: Describe the feature/bug
Discuss: Get feedback from maintainers
Fork: Fork the repository
Branch: Create feature branch

# Create and switch to feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ...

# Commit changes
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub

Code Review Process¶

Self Review: Review your own changes first
Tests: Ensure all tests pass
Documentation: Update relevant docs
Pull Request: Create PR with detailed description
Address Feedback: Respond to review comments
Merge: Maintainer will merge after approval

Performance Profiling¶

Memory Profiling¶

# Generate heap dump
adb shell am dumpheap com.androidrtmp /data/local/tmp/heap.hprof
adb pull /data/local/tmp/heap.hprof

CPU Profiling¶

Use Android Studio's CPU Profiler
Monitor main thread performance
Check for ANRs (Application Not Responding)

Network Monitoring¶

Monitor RTMP connection stability
Check bandwidth usage
Profile streaming performance

This setup guide should get you up and running with Android RTMP USB Capture development. If you encounter any issues, please check the troubleshooting section or create an issue on GitHub.