chatrtc/SETUP.md

🚀 ChatRTC - Complete Setup Guide

Project Overview

ChatRTC is a complete Android WebRTC chat application with a Node.js signaling server. Users can join with just a nickname and enjoy:

• 💬 Text messaging with emoji support
• 📹 Video calling with WebRTC
• 🎤 Audio calling
• 👥 Multi-user chat rooms
• 📱 Modern Android UI

📁 Project Structure

chatrtc/
├── app/                          # Android Application
│   ├── src/main/java/com/chatrtc/app/
│   │   ├── MainActivity.java     # Nickname entry & permissions
│   │   ├── ChatActivity.java     # Main chat interface
│   │   ├── adapter/
│   │   │   └── ChatAdapter.java  # Chat message RecyclerView adapter
│   │   ├── model/
│   │   │   └── ChatMessage.java  # Message data model
│   │   └── webrtc/
│   │       └── WebRTCManager.java # WebRTC connection management
│   └── src/main/res/             # Android resources (layouts, drawables, etc.)
├── server/                       # Node.js Signaling Server
│   ├── server.js                 # Main server implementation
│   ├── package.json              # Dependencies and scripts
│   ├── start-server.sh           # Easy startup script
│   ├── test-client.js            # Server testing utility
│   └── README.md                 # Server documentation
└── README.md                     # This file

🛠️ Quick Setup

1. Server Setup (5 minutes)

# Navigate to server directory
cd server

# Install dependencies
npm install

# Start the server
npm start
# or use the convenient script:
./start-server.sh start dev

Server will be running at:

• 🌐 Local: http://localhost:3000
• 📱 Android Emulator: http://10.0.2.2:3000
• 🔗 Network: http://YOUR_IP:3000

2. Android App Setup

1. Open in Android Studio: Open the chatrtc folder
2. Update Server URL: In WebRTCManager.java, update:

   private static final String SIGNALING_SERVER_URL = "http://10.0.2.2:3000"; // For emulator
   // or "http://YOUR_SERVER_IP:3000" for real device
   

3. Build & Run: Connect device/emulator and click Run

3. Test the App

1. Grant Permissions: Allow camera and microphone access
2. Enter Nickname: Type any nickname and join
3. Start Chatting: Send messages, toggle video/audio
4. Multi-user: Run on multiple devices to test P2P connections

🎯 Key Features Implemented

Android App Features

• ✅ Simple nickname entry - No registration required
• ✅ Emoji support - Full emoji keyboard and rendering
• ✅ WebRTC video/audio - Peer-to-peer communication
• ✅ Modern chat UI - Material Design with chat bubbles
• ✅ Media controls - Toggle video/audio, switch cameras
• ✅ Permission handling - Smooth camera/mic permission flow

Server Features

• ✅ Real-time signaling - WebRTC offer/answer/ICE exchange
• ✅ Room management - Multiple users in chat rooms
• ✅ User tracking - Monitor connections and states
• ✅ REST API - Server monitoring and room info
• ✅ Error handling - Comprehensive error management
• ✅ Production ready - PM2 support, logging, CORS

📱 Android Integration Details

WebRTC Connection Flow

1. User enters nickname → joins default room
2. Server notifies other users → triggers WebRTC offer
3. Peer connection established → direct P2P communication
4. Data channels used for text messages
5. Media streams for audio/video

Key Android Components

• MainActivity: Handles nickname input and permissions
• ChatActivity: Main UI with video views and chat list
• WebRTCManager: Manages all WebRTC connections and signaling
• ChatAdapter: Handles different message types (own/other/system)

🖥️ Server API Reference

REST Endpoints

Endpoint	Method	Description
/	GET	Server status dashboard (HTML)
/api/status	GET	Server statistics (JSON)
/api/rooms	GET	List all active rooms
/api/rooms/:id	GET	Specific room information
/health	GET	Health check endpoint

Socket.IO Events

Client → Server:

• join-room - Join chat room with nickname
• offer/answer/ice-candidate - WebRTC signaling
• media-state - Video/audio state updates
• chat-message - Text message fallback

Server → Client:

• joined-room - Successful room join confirmation
• user-joined/user-left - User connection notifications
• offer/answer/ice-candidate - WebRTC signaling relay
• user-media-state - Media state broadcasts

🔧 Development & Testing

Server Commands

# Development with auto-restart
npm run dev

# Production mode
npm start

# Process manager (recommended for production)
./start-server.sh start pm2

# Test server connectivity
./start-server.sh test

# Show server info
./start-server.sh info

Android Development

# Build debug APK
./gradlew assembleDebug

# Install on connected device
adb install app/build/outputs/apk/debug/app-debug.apk

# View app logs
adb logcat | grep ChatRTC

Testing Multi-User Scenarios

1. Multiple Devices: Install on different Android devices
2. Emulator + Device: Run on emulator and real device
3. Multiple Emulators: Create multiple AVDs for testing

🚀 Production Deployment

Server Deployment

# Using PM2 (recommended)
npm install -g pm2
npm run pm2:start

# Using Docker
docker build -t chatrtc-server .
docker run -p 3000:3000 chatrtc-server

# Manual deployment
NODE_ENV=production npm start

Android Release

# Generate release APK
./gradlew assembleRelease

# Generate signed APK (configure keystore first)
./gradlew bundleRelease

🐛 Troubleshooting

Common Issues

Server won't start:

• Check if port 3000 is available: lsof -i :3000
• Verify Node.js installation: node --version

Android connection failed:

• Verify server URL in WebRTCManager.java
• Check network connectivity
• Ensure server is accessible from device network

WebRTC not working:

• Grant camera/microphone permissions
• Check for HTTPS requirement in production
• Verify STUN server connectivity

No video/audio:

• Test on real device (emulator has limited media support)
• Check device camera/microphone functionality
• Verify WebRTC peer connection establishment

Debug Commands

# Check server status
curl http://localhost:3000/api/status

# Monitor server logs
tail -f server/logs/chatrtc-server.log

# Android logs
adb logcat | grep -E "(WebRTC|ChatRTC|WebRTCManager)"

📊 Performance & Scalability

Current Limitations

• P2P only: Direct connections between 2 users
• Single server: One signaling server instance
• Memory-based storage: User data not persisted

Scaling Options

• MCU/SFU: Media server for group calls
• Redis: Distributed session storage
• Load balancer: Multiple server instances
• Database: Persistent user/room data

🎨 Customization

UI Customization

• Colors: Edit app/src/main/res/values/colors.xml
• Layouts: Modify XML layouts in res/layout/
• Icons: Replace drawable resources
• Themes: Update res/values/themes.xml

Server Customization

• Room limits: Modify server configuration
• STUN/TURN servers: Update WebRTC configuration
• Message limits: Configure rate limiting
• Logging: Adjust log levels and destinations

📄 License

MIT License - Feel free to use and modify for your projects!

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

🆘 Support

• 📝 Issues: Create GitHub issues for bugs/features
• 📚 Documentation: Check server and app README files
• 🔍 Debugging: Enable debug logs for detailed information

---

🎉 You're all set! Your ChatRTC application is ready for development and deployment.