LAN Collaboration System

A robust, standalone, server-based multi-user communication application that operates exclusively over a Local Area Network (LAN). This system provides real-time collaboration tools including video, audio, chat, presentation, and file-sharing functionalities without requiring internet connectivity.

🎯 Features

✅ Implemented Features

• Multi-User Video Conferencing

  • Real-time video streaming via UDP
  • H.264 encoding/decoding
  • Dynamic video grid layout
  • Support for multiple simultaneous participants
  • Jitter buffer for packet reordering

• Multi-User Audio Conferencing

  • Real-time audio streaming via UDP
  • Opus encoding/decoding (high quality, low latency)
  • Server-side audio mixing
  • Low-latency audio playback
  • Automatic echo cancellation

• Screen & Slide Sharing

  • TCP-based screen sharing
  • Presenter controls (request/revoke)
  • JPEG compression for efficiency
  • Multi-monitor support
  • Frame rate control (2-5 fps)

• Group Text Chat

  • Real-time text messaging
  • Chat history
  • User presence updates
  • Clean, intuitive interface
  • Username display

• File Sharing

  • Reliable file transfer via TCP
  • Progress tracking
  • Chunked uploads/downloads (64KB chunks)
  • File metadata management
  • Maximum file size: 100MB (configurable)

📋 Requirements

System Requirements

• OS: Windows 10/11, Linux, or macOS
• Python: 3.11 or higher
• RAM: Minimum 2GB, recommended 4GB+
• Network: All devices must be on the same LAN
• Storage: ~500MB for installation, additional for file storage

Hardware Requirements

• Server: Any machine on LAN (can be a client machine)
• Client:
  • Camera (optional, for video)
  • Microphone (optional, for audio)
  • Speakers/Headphones (for audio playback)
  • Adequate CPU for encoding/decoding

Python Dependencies

All dependencies are listed in requirements.txt. Key libraries include:

• PySide6 (>=6.6.0) - GUI framework
• PyAV (>=12.0.0) - Video encoding/decoding (H.264)
• Opuslib (>=3.0.1) - Audio encoding/decoding (Opus)
• OpenCV (>=4.8.0) - Video capture
• sounddevice (>=0.4.6) - Audio capture/playback
• MSS (>=9.0.1) - Screen capture
• NumPy (>=1.24.0) - Numerical operations
• Pillow (>=10.0.0) - Image processing
• structlog (>=23.2.0) - Structured logging
• PyYAML (>=6.0) - Configuration management

🚀 Quick Start

Installation

1. Clone or download the project

   cd lan-collab

2. Create a virtual environment (recommended)

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

   Note: This may take several minutes as it downloads large libraries.

Running the Server

Option 1: Direct Python

cd server
python main.py

Option 2: Using script

python scripts/start_server.py

The server will start listening on:

• TCP Control: 0.0.0.0:6000
• TCP File Transfer: 0.0.0.0:6001
• TCP Screen Sharing: 0.0.0.0:6002
• UDP Video: 0.0.0.0:7000
• UDP Audio: 0.0.0.0:7001

Running the Client

Option 1: Direct Python

cd client
python main.py

Option 2: Using script

python scripts/start_client.py

First Steps

1. Start the server on one machine (preferably a dedicated server machine)
2. Note the server IP address (e.g., 192.168.1.100)
   • Windows: ipconfig → Look for IPv4 Address
   • Linux/macOS: ifconfig or ip addr show → Look for inet address
3. Update client config (client/config.yaml) with the server IP:

   server:
     host: "192.168.1.100"  # Change to your server IP

4. Start clients on other machines
5. Enter username and click "Connect"
6. Start collaborating!

📁 Project Structure

lan-collab/
├── server/                 # Server application
│   ├── main.py            # Server entry point
│   ├── control.py         # TCP control server (login, chat, presence)
│   ├── video_udp.py       # UDP video relay
│   ├── audio_udp.py       # UDP audio mixing
│   ├── screen_tcp.py      # TCP screen relay
│   ├── files_tcp.py       # TCP file transfer
│   ├── mixing.py          # Audio mixing utilities
│   ├── models.py          # Data models (Session, User, FileInfo)
│   ├── config.py          # Configuration management
│   └── config.yaml        # Server configuration file
│
├── client/                 # Client application
│   ├── main.py            # Client entry point
│   ├── ui/                # User interface
│   │   ├── main_window.py # Main window (tabs, controls)
│   │   ├── video_grid.py  # Video grid widget
│   │   └── screen_view.py # Screen display widget
│   ├── net/               # Network clients
│   │   ├── client_manager.py  # Central coordinator
│   │   ├── control_client.py   # TCP control
│   │   ├── audio_udp.py       # UDP audio
│   │   ├── video_udp.py       # UDP video
│   │   ├── screen_tcp.py      # TCP screen
│   │   └── files_tcp.py        # TCP files
│   ├── media/             # Media processing
│   │   ├── capture_audio.py   # Audio capture
│   │   ├── capture_video.py   # Video capture
│   │   ├── capture_screen.py  # Screen capture
│   │   ├── encode_audio.py   # Opus encoding
│   │   ├── encode_video.py   # H.264 encoding
│   │   ├── decode_audio.py   # Opus decoding
│   │   ├── decode_video.py   # H.264 decoding
│   │   └── playback_audio.py # Audio playback
│   ├── util/              # Utilities
│   │   └── jitter_buffer.py  # Packet reordering
│   ├── config.py          # Configuration management
│   └── config.yaml        # Client configuration file
│
├── common/                 # Shared code
│   ├── constants.py       # Protocol constants
│   ├── schemas.py        # Message schemas (User, Message types)
│   └── protocol.py        # Protocol utilities (TCP framing, UDP headers)
│
├── docs/                   # Documentation
│   ├── ARCHITECTURE.md    # System architecture
│   ├── USER_GUIDE.md      # User manual
│   ├── SETUP.md           # Setup instructions
│   ├── BUILD.md           # Build guide
│   └── IMPLEMENTATION_PLAN.md  # Development phases
│
├── scripts/                # Utility scripts
│   ├── start_server.py    # Server launcher
│   ├── start_client.py    # Client launcher
│   └── build.py           # Build script for executables
│
├── requirements.txt        # Python dependencies
└── README.md              # This file

🔧 Configuration

Server Configuration (server/config.yaml)

server:
  host: "0.0.0.0"          # Listen on all interfaces
  control_port: 6000
  file_port: 6001
  screen_port: 6002
  video_udp_port: 7000
  audio_udp_port: 7001

session:
  room_id: "default"
  max_users: 50
  heartbeat_interval: 5.0
  connection_timeout: 30.0

media:
  video_bitrate: 1500000    # 1.5 Mbps
  audio_bitrate: 32000      # 32 kbps
  audio_sample_rate: 48000

files:
  storage_path: "./files"
  max_file_size: 104857600  # 100MB
  cleanup_interval: 3600     # 1 hour

Client Configuration (client/config.yaml)

server:
  host: "127.0.0.1"         # Server IP address (CHANGE THIS!)
  control_port: 6000
  file_port: 6001
  screen_port: 6002
  video_udp_port: 7000
  audio_udp_port: 7001

media:
  video_width: 1280
  video_height: 720
  video_fps: 24
  video_bitrate: 1500000
  audio_sample_rate: 48000
  audio_bitrate: 32000

📖 Usage Guide

Basic Usage

1. Start Server

   • Run the server on a machine accessible to all clients
   • Note the server's IP address

2. Connect Clients

   • Configure each client with the server IP
   • Enter a username
   • Click "Connect"

3. Enable Video/Audio

   • Click "Start Video" to enable webcam
   • Click "Unmute Audio" to enable microphone
   • Other participants will see/hear you

4. Screen Sharing

   • Click "Request Presenter" (first user becomes presenter)
   • Click "Start Presenting" to share screen
   • Other participants will see your screen

5. File Sharing

   • Click "Upload File" to share a file
   • Select file from dialog
   • Other participants can download from the Files tab

6. Chat

   • Type messages in the chat input
   • Press Enter to send
   • View chat history in the chat panel

Advanced Features

• Multiple Users: Supports up to 50 simultaneous users (configurable)
• Video Grid: Automatically adjusts layout based on number of participants
• Presenter Control: Only one presenter at a time; others can request presenter role
• File Management: Files are stored on server; available for download by all participants

🏗️ Architecture

Network Architecture

The system uses a client-server architecture with separate channels for different data types:

• TCP Control (Port 6000): Login, chat, presence, AV state
• TCP File Transfer (Port 6001): File uploads/downloads
• TCP Screen Sharing (Port 6002): Screen frame relay
• UDP Video (Port 7000): Video stream relay
• UDP Audio (Port 7001): Audio stream mixing and relay

Data Flow

Video Flow:

Client Capture → H.264 Encode → UDP Packetize → Server → UDP Relay → Client Decode → Display

Audio Flow:

Client Capture → Opus Encode → UDP Send → Server Decode → Mix All Streams → Re-encode → UDP Broadcast → Client Decode → Playback

Screen Sharing Flow:

Presenter Capture → JPEG Compress → TCP Send → Server → TCP Relay → Viewers Display

File Transfer Flow:

Uploader → Chunk File → TCP Send → Server Store → TCP Notify → Downloader → TCP Request → Server Stream → Save File

🔍 Troubleshooting

Common Issues

Server won't start:

• Check if ports are already in use
• Verify firewall settings
• Ensure Python 3.11+ is installed

Client can't connect:

• Verify server IP in client config
• Check network connectivity (ping server)
• Ensure firewall allows TCP/UDP ports
• Verify server is running

No video/audio:

• Check camera/microphone permissions
• Verify device selection in settings
• Check firewall allows UDP ports 7000-7001
• Ensure codecs are installed (PyAV, Opuslib)

Screen sharing not working:

• Verify presenter role is granted
• Check TCP port 6002 is accessible
• Ensure screen capture permissions (macOS)

File transfer fails:

• Check file size (max 100MB default)
• Verify disk space on server
• Check TCP port 6001 is accessible

Logs

Server logs are written to server.log (configurable in server/config.yaml).

Client logs are printed to console. Enable debug logging by modifying logging configuration.

📦 Building Executables

See docs/BUILD.md for detailed instructions on creating standalone executables using PyInstaller.

Quick example:

# Server
cd server
pyinstaller --onefile --name lan-collab-server main.py

# Client
cd client
pyinstaller --onefile --windowed --name lan-collab-client main.py

Or use the build script:

python scripts/build.py        # Build both
python scripts/build.py server # Build server only
python scripts/build.py client # Build client only

🛠️ Technical Details

Technologies Used

• Backend: Python 3.11+, asyncio
• GUI: PySide6 (Qt6)
• Video: OpenCV, PyAV (FFmpeg), H.264
• Audio: sounddevice, Opuslib, Opus codec
• Screen Capture: MSS (cross-platform)
• Networking: TCP/IP sockets, UDP datagrams
• Data Format: JSON for control, binary for media

Performance Targets

• Video: 720p @ 24fps, ~1.5 Mbps per stream
• Audio: 48kHz mono, 32 kbps, ~20ms latency
• Screen: 3-5 fps, JPEG compression (quality 85)
• Network: Optimized for LAN (low latency)

Security Considerations

• LAN-only: No internet connectivity required
• No encryption: Data transmitted in plaintext (LAN trusted)
• Future enhancement: TLS/DTLS support possible

📚 Documentation

• Architecture Documentation - Detailed system architecture
• User Guide - Complete user manual
• Setup Guide - Installation and configuration
• Build Guide - Creating executables
• Implementation Plan - Development phases

🎓 Use Cases

• Corporate Meetings: Internal team meetings without internet
• Educational Institutions: Classroom collaboration
• Workshops: Hands-on training sessions
• Secure Environments: Where internet access is restricted
• Development Teams: Local collaboration tools

⚠️ Known Limitations

• Single room only (no multi-room support)
• No encryption (LAN-only assumption)
• No recording capabilities
• Limited error recovery
• UDP address mapping simplified
• File transfer resume not implemented

🚧 Future Enhancements

• Multi-room support
• End-to-end encryption (TLS/DTLS)
• Recording capabilities
• Whiteboard/annotation tools
• Push-to-talk audio
• Bandwidth adaptation
• Hardware acceleration
• Mobile client support

📞 Support

For issues or questions:

1. Check troubleshooting section
2. Review logs
3. Verify configuration
4. Check network connectivity

🎉 Acknowledgments

Built with:

• Python and asyncio
• PySide6 (Qt6)
• PyAV (FFmpeg)
• Opuslib
• OpenCV
• MSS

📝 License

This project is provided as-is for educational and commercial use.

---

Version: 1.0.0
Status: Production Ready
Last Updated: 2024