chatrtc/android-app/README.md

# ChatRTC - Android WebRTC Chat Application

A modern Android chat application with WebRTC support for audio/video calling and emoji text messaging.

## Features

- **Nickname-based joining**: Users only need to enter their nickname to join the chat
- **Text messaging with emoji support**: Full emoji keyboard and rendering support
- **Audio/Video calling**: WebRTC-powered audio and video communication
- **Modern UI**: Material Design components with beautiful chat bubbles
- **Camera controls**: Toggle video, mute audio, and switch between front/back cameras
- **Real-time communication**: Instant messaging and WebRTC peer-to-peer connections

## Project Structure

```
chatrtc/
├── app/                          # Android application
│   ├── src/main/java/com/chatrtc/app/
│   │   ├── MainActivity.java     # Nickname entry screen
│   │   ├── ChatActivity.java     # Main chat interface
│   │   ├── adapter/
│   │   │   └── ChatAdapter.java  # RecyclerView adapter for messages
│   │   ├── model/
│   │   │   └── ChatMessage.java  # Message data model
│   │   └── webrtc/
│   │       └── WebRTCManager.java # WebRTC connection management
│   └── src/main/res/             # Android resources
└── signaling-server/             # Node.js signaling server
    ├── server.js                 # Socket.IO signaling server
    └── package.json              # Server dependencies
```

## Setup Instructions

### 1. Android App Setup

1. **Prerequisites**:
   - Android Studio Arctic Fox or later
   - JDK 8 or later
   - Android SDK API 24+ (Android 7.0)

2. **Open the project**:
   ```bash
   cd chatrtc
   # Open in Android Studio
   ```

3. **Configure signaling server URL**:
   - Open `app/src/main/java/com/chatrtc/app/webrtc/WebRTCManager.java`
   - Update the `SIGNALING_SERVER_URL` constant with your server URL:
   ```java
   private static final String SIGNALING_SERVER_URL = "https://your-server.com";
   // For local development: "http://10.0.2.2:3000"
   ```

4. **Build and run**:
   - Connect your Android device or start an emulator
   - Click "Run" in Android Studio

### 2. Signaling Server Setup

1. **Install Node.js**: Download from [nodejs.org](https://nodejs.org/)

2. **Install dependencies**:
   ```bash
   cd signaling-server
   npm install
   ```

3. **Start the server**:
   ```bash
   npm start
   # or for development with auto-restart:
   npm run dev
   ```

4. **Server will run on**: `http://localhost:3000`

## Usage

1. **Start the signaling server** (see setup instructions above)
2. **Install and run the Android app** on your device(s)
3. **Enter your nickname** on the welcome screen
4. **Grant permissions** for camera and microphone when prompted
5. **Start chatting**:
   - Send text messages with emoji support
   - Toggle video/audio using the control buttons
   - Switch cameras using the camera switch button
   - Multiple users can join the same chat room

## Key Components

### Android App

- **MainActivity**: Handles nickname entry and permissions
- **ChatActivity**: Main chat interface with video views and message list
- **WebRTCManager**: Manages WebRTC connections, media streams, and signaling
- **ChatAdapter**: Handles different message types (own, other, system)
- **Emoji Support**: Uses Vanniktech emoji library for full emoji rendering

### WebRTC Features

- **Peer-to-peer connections**: Direct audio/video streams between users
- **Data channels**: For text message transmission
- **STUN servers**: Google's STUN servers for NAT traversal
- **Camera management**: Front/back camera switching
- **Media controls**: Toggle audio/video streams

### Signaling Server

- **Socket.IO based**: Real-time bidirectional communication
- **Room management**: Users join a common chat room
- **WebRTC signaling**: Handles offer/answer/ICE candidate exchange
- **User management**: Tracks connected users and broadcasts join/leave events

## Dependencies

### Android
- **WebRTC**: `org.webrtc:google-webrtc:1.0.32006`
- **Socket.IO**: `io.socket:socket.io-client:2.0.1`
- **Emoji Support**: `com.vanniktech:emoji-google:0.16.0`
- **Material Design**: `com.google.android.material:material:1.9.0`

### Server
- **Express**: Web server framework
- **Socket.IO**: Real-time communication
- **CORS**: Cross-origin resource sharing

## Network Configuration

For local development, the app includes network security configuration to allow HTTP connections to localhost and common local IP addresses.

## Permissions

The app requires:
- `CAMERA`: For video calling
- `RECORD_AUDIO`: For audio calling  
- `MODIFY_AUDIO_SETTINGS`: For audio management
- `INTERNET`: For signaling server connection
- `ACCESS_NETWORK_STATE`: For network status

## Deployment

### Android App
- Build APK: `./gradlew assembleDebug`
- Install: `adb install app/build/outputs/apk/debug/app-debug.apk`

### Signaling Server
- Deploy to any Node.js hosting service (Heroku, Railway, etc.)
- Update the `SIGNALING_SERVER_URL` in the Android app
- Ensure HTTPS is used for production (required by WebRTC)

## Troubleshooting

1. **Connection issues**: Check signaling server URL and network connectivity
2. **Permission errors**: Ensure camera/microphone permissions are granted
3. **Video not showing**: Check camera availability and permissions
4. **Audio not working**: Verify microphone permissions and device audio settings

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is open source and available under the MIT License.