Contributors Guide¶

Welcome to Gazer Mobile Stream Studio! We're excited to have you contribute to this open-source mobile streaming application. This guide will help you get started with contributing to the project.

🤝 How to Contribute¶

There are many ways to contribute to this project:

Bug Reports: Help us identify and fix issues
Feature Requests: Suggest new functionality
Code Contributions: Submit bug fixes and new features
Documentation: Improve guides and documentation
Testing: Test the app on different devices and configurations
Translation: Help translate Gazer to other languages

🚀 Getting Started¶

Prerequisites¶

Before you begin, ensure you have:

Android Studio: Latest stable version (Hedgehog 2023.1.1 or newer)
JDK: Java Development Kit 17 or newer
Git: For version control
Android Device: Physical device with USB Host support for testing
USB Capture Card: For complete feature testing

Development Environment Setup¶

Fork the Repository

# Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/android-rtmp.git
cd android-rtmp

Open in Android Studio
Launch Android Studio
Select "Open an Existing Project"
Navigate to the cloned directory
Wait for Gradle sync to complete

Install Dependencies

# Dependencies are handled automatically by Gradle
# Ensure you have the latest Android SDK components

Build and Run

# Build debug version
./gradlew assembleDebug

# Run tests
./gradlew test

📋 Development Guidelines¶

Code Style¶

We follow standard Android development practices:

Kotlin Style Guide¶

Use official Kotlin coding conventions
4 spaces for indentation (no tabs)
Line length limit: 120 characters
Use descriptive variable and function names

Android Architecture¶

Follow MVVM (Model-View-ViewModel) pattern where applicable
Use Android Architecture Components (ViewModel, LiveData, etc.)
Implement proper lifecycle management
Use coroutines for asynchronous operations

Example Code Style:¶

class UsbCaptureManager(
    private val context: Context,
    private val usbManager: UsbManager
) {
    private var _connectionState = MutableLiveData<ConnectionState>()
    val connectionState: LiveData<ConnectionState> = _connectionState

    suspend fun connectToDevice(device: UsbDevice): Result<Boolean> {
        return withContext(Dispatchers.IO) {
            try {
                // Connection logic here
                _connectionState.postValue(ConnectionState.Connected)
                Result.success(true)
            } catch (e: Exception) {
                _connectionState.postValue(ConnectionState.Error(e.message))
                Result.failure(e)
            }
        }
    }
}

File Organization¶

Follow the existing project structure:

app/src/main/
├── java/com/androidrtmp/
│   ├── MainActivity.kt
│   ├── managers/
│   │   ├── UsbCaptureManager.kt
│   │   └── StreamingManager.kt
│   ├── ui/
│   │   ├── components/
│   │   └── dialogs/
│   ├── utils/
│   └── models/
├── res/
│   ├── layout/
│   ├── layout-sw600dp/
│   ├── values/
│   └── drawable/
└── AndroidManifest.xml

Commit Guidelines¶

We follow Conventional Commits specification:

Commit Message Format:¶

<type>(<scope>): <subject>

<body>

<footer>

Types:¶

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or modifying tests
chore: Build process or auxiliary tool changes

Examples:¶

feat(usb): add support for additional capture card vendors

Add vendor IDs for more USB capture cards to improve device compatibility.
Includes support for AVerMedia and Razer devices.

Closes #123

fix(streaming): resolve memory leak in video encoder

The video encoder was not properly releasing resources after streaming
stopped, causing memory usage to continuously increase.

docs(readme): update installation instructions

Add more detailed steps for enabling USB host mode on different
Android versions.

🐛 Reporting Issues¶

When reporting bugs, please include:

Bug Report Template:¶

**Device Information:**
- Android Version: (e.g., Android 12)
- Device Model: (e.g., Samsung Galaxy S22)
- App Version: (e.g., 1.2.0)

**Capture Card Information:**
- Brand/Model: (e.g., Elgato Cam Link 4K)
- Connection Type: (e.g., USB-C with adapter)

**Issue Description:**
A clear description of what went wrong.

**Steps to Reproduce:**
1. Connect USB capture card
2. Open app
3. Configure stream settings
4. Start streaming
5. Issue occurs

**Expected Behavior:**
What should have happened.

**Actual Behavior:**
What actually happened.

**Screenshots/Logs:**
Include relevant screenshots or log outputs if available.

**Additional Context:**
Any other relevant information.

✨ Submitting Features¶

Feature Request Process:¶

Check Existing Issues: Search for similar feature requests
Create Feature Request: Use the feature request template
Discuss: Engage in discussion about implementation
Plan: Outline the technical approach
Implement: Create the feature following guidelines
Test: Thoroughly test on multiple devices
Submit: Create pull request with detailed description

Feature Request Template:¶

**Feature Summary:**
Brief description of the proposed feature.

**Problem Statement:**
What problem does this solve for users?

**Proposed Solution:**
Detailed description of how the feature should work.

**Alternative Solutions:**
Other ways this problem could be solved.

**Technical Considerations:**
Any technical challenges or requirements.

**User Stories:**
- As a streamer, I want to...
- So that I can...

**Acceptance Criteria:**
- [ ] Feature works on phones and tablets
- [ ] Feature integrates with existing UI
- [ ] Feature is properly tested
- [ ] Documentation is updated

🔀 Pull Request Process¶

Before Submitting:¶

Update Your Branch

git checkout main
git pull upstream main
git checkout your-feature-branch
git rebase main

Test Thoroughly
Test on multiple Android versions if possible
Test with different USB capture cards
Verify existing functionality still works
Run automated tests: ./gradlew test
Update Documentation
Update relevant docs in /docs folder
Update inline code comments
Update README if needed
Check Code Quality
Follow established code style
Remove debug code and console logs
Ensure proper error handling

Pull Request Template:¶

## Summary
Brief description of changes made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Related Issues
Closes #(issue number)

## Changes Made
- List specific changes
- Include technical details
- Mention any architectural changes

## Testing Performed
- [ ] Tested on Android phone
- [ ] Tested on Android tablet
- [ ] Tested with USB capture card
- [ ] Tested streaming functionality
- [ ] Automated tests pass

## Screenshots/Videos
Include relevant screenshots or screen recordings if applicable.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Code commented where necessary
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No new warnings introduced

🧪 Testing Guidelines¶

Manual Testing Requirements:¶

Core Functionality:¶

[ ] USB device detection and connection
[ ] Video preview rendering
[ ] Camera overlay functionality
[ ] RTMP streaming to various platforms
[ ] Settings persistence
[ ] Permission handling

Device Testing:¶

[ ] Phone layout (portrait/landscape)
[ ] Tablet layout (portrait/landscape)
[ ] Different Android versions (API 24+)
[ ] Various screen sizes and densities

Hardware Testing:¶

[ ] Different USB capture cards
[ ] USB-C and micro-USB connections
[ ] Various video input formats
[ ] Different camera configurations

Automated Testing:¶

We use JUnit for unit tests and Espresso for UI tests:

# Run unit tests
./gradlew test

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

📚 Resources¶

Documentation:¶

Libraries Used:¶

Useful Tools:¶

Android Studio
Scrcpy - Screen mirroring for testing
USB Device Info - USB debugging

👥 Community¶

Communication Channels:¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and community discussions
Pull Requests: Code review and collaboration

Code of Conduct:¶

We are committed to providing a welcoming and inclusive experience for all contributors. Please:

Be respectful and considerate
Use inclusive language
Accept constructive criticism gracefully
Focus on what is best for the community
Show empathy towards other contributors

Recognition:¶

All contributors will be acknowledged in our project documentation. Significant contributions may be featured in release notes.

📄 License¶

By contributing to this project, you agree that your contributions will become part of the commercial Gazer Mobile Stream Studio application. Contributors may receive compensation or recognition as determined by the project maintainers.

🙋‍♀️ Getting Help¶

If you need help with contributing:

Check Documentation: Review this guide and project documentation
Search Issues: Look for similar questions or problems
Ask Questions: Create a GitHub discussion for general questions
Start Small: Begin with small bug fixes or documentation improvements

We appreciate all contributions, no matter how small. Thank you for helping make Gazer Mobile Stream Studio better for everyone!

Quick Start Checklist for New Contributors:¶

[ ] Fork the repository
[ ] Set up development environment
[ ] Build and run the app successfully
[ ] Read through the codebase
[ ] Find a "good first issue" to work on
[ ] Create a feature branch
[ ] Make your changes
[ ] Test thoroughly
[ ] Submit a pull request
[ ] Respond to code review feedback

Welcome to the team! 🎉