HushLink

HushLink is an AI-powered silent communication system that enables real-time audio monitoring, transcription, and intelligent alert detection.

🎯 Features

🎤 Real-Time Audio Processing

• Speech Recognition - Browser's native Speech Recognition API with MediaRecorder fallback
• Live Transcription - Real-time text conversion
• Low Latency - 4-second processing chunks
• Noise Filtering - Smart audio cleanup

🚨 Intelligent Alert Detection

• Semantic Analysis - Context-aware alert detection
• Priority Levels - Emergency, Warning, Info, Success
• Pattern Recognition - Keywords and phrases
• Customizable Rules - Configurable alert triggers
• Push Notifications - Browser notifications for detected alerts

🌐 Dashboard Features

• Real-time Monitoring - Live status updates
• Alert Management - History and notifications
• Map View - Spatial awareness and location tracking
• User Preferences - Customizable settings

🔐 Security

• Clerk Authentication - Secure user management
• Protected Routes - Role-based access
• Encrypted Data - Secure communication
• Session Control - Active session management

🛠️ Tech Stack

• Frontend: Next.js 14, React, TypeScript
• Styling: Tailwind CSS, CSS Variables
• Auth: Clerk Authentication
• Database: Prisma with Neon (PostgreSQL)
• APIs:
  • Web Speech API
  • MediaRecorder API
  • AssemblyAI (optional)
• UI: Shadcn/ui Components

📦 Prerequisites

• Node.js 18+
• npm/yarn/pnpm/bun
• Python 3.8+ (for Whisper service)
• FFmpeg (for audio processing)

🚀 Getting Started

1. Clone and Install

# Clone the repository
git clone https://github.com/awindsr/hushlink.git
cd hushlink

# Install dependencies
npm install

2. Configure Environment

# Copy example config
cp .env.example .env.local

Required variables:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
CLERK_SECRET_KEY=your_clerk_secret
DATABASE_URL=your_neon_postgres_url
ASSEMBLYAI_API_KEY=optional_assembly_key

3. Initialize Database

npx prisma migrate dev

4. Start Development Server

npm run dev

5. Optional: Start Whisper Service

cd python-services/whisper-service
pip install -r requirements.txt
python main.py

�️ Project Structure

hushlink/
├── app/                    # Next.js app directory
│   ├── (dashboard)/       # Dashboard routes
│   ├── api/               # API routes
│   └── signin/            # Auth pages
├── components/            # Reusable components
│   ├── dashboard/         # Dashboard components
│   ├── map/              # Map components
│   └── ui/               # UI components
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions
├── prisma/              # Database schema
├── python-services/     # Python microservices
└── types/              # TypeScript types

⚙️ Configuration

Notification Permissions

HushLink requests browser notification permissions on first load to enable:

• Push Notifications - Desktop/mobile notifications when alerts are detected
• Haptic Feedback - Device vibration on alert detection (supported devices)

To enable notifications:

1. Allow notification permission when prompted
2. Ensure browser notifications are not blocked
3. For mobile devices, enable vibration permissions

Vibration Pattern: [200ms, 100ms, 200ms, 100ms, 200ms] - Creates an urgent alert pulse

Audio Processing

Adjust settings in app/(dashboard)/dashboard/ActiveListening.tsx:

• Language preferences
• Continuous listening mode
• Noise reduction settings

Alert Detection

Customize rules in app/api/analyze/route.ts:

• Keyword patterns
• Severity thresholds
• Alert categories

Map Features

Configure in components/map/AlertMap.tsx:

• Default coordinates
• Zoom levels
• Marker settings

🤝 Contributing

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

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Next.js - React Framework
• Clerk - Authentication
• Shadcn/ui - UI Components
• AssemblyAI - Speech Recognition API

# Terminal 1: Python AI Service
.\scripts\start-whisper-service.ps1

# Terminal 2: Next.js Frontend
bun dev

3. Use It!

1. Open http://localhost:3000/dashboard
2. Toggle "Active Listening"
3. Grant microphone permission
4. Start speaking!

Test alert detection: Say "Fire emergency evacuate now" 🚨

---

🏗️ Architecture

┌──────────────────┐
│   Browser        │
│   MediaRecorder  │ ← Captures audio
└────────┬─────────┘
         │ 4-second chunks
         ↓
┌──────────────────┐
│   Next.js API    │
│   SSE Streaming  │ ← Real-time updates
└────────┬─────────┘
         │ Forward audio
         ↓
┌──────────────────┐
│   Python Service │
│   Port 8000      │
├──────────────────┤
│ Whisper v3       │ ← Transcription
│ Translation      │ ← To English
│ Sentence Trans.  │ ← Semantic AI
└────────┬─────────┘
         │ Results
         ↓
    JSON Response

---

🧪 Testing

Automated Tests

# Run complete test suite
.\scripts\test-semantic-detection.ps1

# Expected: ✓ All tests passed! (7/7)

Manual Tests

# Health check
curl http://localhost:8000/health

# Test alert detection
curl -X POST http://localhost:8000/detect-alert `
  -d "text=Fire emergency evacuate now"

Frontend Test

1. Start services
2. Open dashboard
3. Toggle "Active Listening"
4. Speak: "Fire emergency evacuate now"
5. Verify: 🚨 Alert appears with toast

---

⚙️ Configuration

Alert Threshold

Edit python-services/whisper-service/.env:

# More sensitive (catches more alerts)
ALERT_THRESHOLD=0.5

# Balanced (recommended)
ALERT_THRESHOLD=0.6

# Conservative (only obvious alerts)
ALERT_THRESHOLD=0.7

Whisper Model

# Best accuracy (slower)
WHISPER_MODEL_SIZE=large-v3

# Balanced
WHISPER_MODEL_SIZE=medium

# Fastest
WHISPER_MODEL_SIZE=small

GPU Support

# Use GPU (faster)
DEVICE=cuda
COMPUTE_TYPE=float16

# Use CPU
DEVICE=cpu
COMPUTE_TYPE=int8

---

📊 Performance

Configuration	Latency	Accuracy	Memory
GPU + Large-v3	5-7s	95%	2GB
GPU + Medium	3-5s	90%	1.5GB
CPU + Medium	15-18s	90%	1.5GB

---

🛠️ Tech Stack

Frontend

• Next.js 14 - React framework
• TypeScript - Type safety
• Server-Sent Events - Real-time streaming
• MediaRecorder API - Audio capture
• Clerk - Authentication
• Tailwind CSS - Styling

Backend AI Service

• Python 3.9+ - Runtime
• FastAPI - Web framework
• faster-whisper - Whisper v3 implementation
• sentence-transformers - Semantic similarity
• PyTorch - ML framework
• scikit-learn - ML utilities

---

🎯 Use Cases

• 🏢 Office Buildings - Fire alarm announcements
• 🚆 Transportation - Train/flight announcements
• 🏥 Healthcare - Emergency alerts
• 🏭 Manufacturing - Safety warnings
• 🎓 Education - PA system alerts
• 🏬 Retail - Store announcements

---

Built with ❤️ using Next.js, Whisper v3, and Sentence Transformers

Status: ✅ Production Ready
Version: 2.0 (Semantic Detection)
Last Updated: October 11, 2025