Skip to content

README.md

Latest commit

 

History

History
369 lines (252 loc) · 11.9 KB

README.md

File metadata and controls

369 lines (252 loc) · 11.9 KB
Raw

🗣️ SpeakEZ - Giving Voice to the Voiceless

SpeakEZ Logo

Empowering Communication Through Technology 💬✨

A mobile-first, accessible web application designed to empower non-verbal users to communicate effectively using Text-to-Speech (TTS), intelligent suggestions, and contextual phrase buttons.

Next.js React TypeScript Tailwind CSS Vercel

License Version Mobile First Accessibility

🌐 United Nations SDGs Achieved

The SpeakEZ project supports the following United Nations Sustainable Development Goals (SDGs):

  • UN SDG 3 (Good Health and Well-being)
  • UN SDG 4 (Quality Education)
  • UN SDG 9 (Industry, Innovation and Infrastructure)
  • UN SDG 10 (Reduced Inequalities) by enabling inclusive communication for individuals with speech disabilities through AI-powered assistive technology

✨ Features

🎯 Core Functionality

  • 🗣️ Text-to-Speech (TTS) - Convert text to natural speech using Web Speech API
  • 🧠 Smart Suggestions - AI-powered contextual phrase recommendations
  • 📱 Mobile-First Design - Optimized for touch devices and mobile screens
  • ♿ Accessibility Ready - WCAG compliant with proper contrast and touch targets
  • 💾 Offline Support - LocalStorage for favorites and custom phrases
  • 🚨 Emergency Button - Always accessible emergency communication

🎨 User Experience

  • 🌈 Customizable Interface - Adjustable font sizes and contrast settings
  • ⭐ Favorites System - Save frequently used phrases for quick access
  • 🔄 Smart Context - Contextual phrase suggestions based on usage patterns
  • 📝 Custom Phrases - Create and manage personalized communication sets

🚀 Getting Started

📦 Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v18 or higher) 🟢
  • npm or yarn package manager 📦

🛠️ Installation & Setup

  1. Clone the repository

    git clone https://github.com/jishanahmed-shaikh/Speak-EZ.git
cd Speak-EZ

  2. Install dependencies

    npm install
# or
yarn install

  3. Run the development server

    npm run dev
# or
yarn dev

  4. Open your browser

    Navigate to http://localhost:3000 🌐

    💡 Pro Tip: For the best experience, use mobile device emulation in your browser's dev tools or test on an actual mobile device!

📱 Mobile-First Testing

🔧 Development Testing

  • DevTools Emulation: Use Ctrl+Shift+M (Chrome/Edge/Firefox) to toggle device toolbar 📲
  • Touch Targets: All interactive elements are minimum 44x44px for optimal touch accessibility 👆
  • TTS Testing: Test speech functionality by typing text or tapping phrase buttons 🎵
  • Responsive Design: Verify layouts work across different screen sizes (320px - 1200px+) 📐

📋 Testing Checklist

  • TTS functionality works on target devices 🔊
  • All buttons are easily tappable on mobile 📱
  • Emergency button is always accessible 🚨
  • Favorites save and load correctly 💾
  • Smart suggestions appear contextually 🧠
  • Offline functionality works without internet 🌐

🧠 AI Integration & Voice Models

🎤 Default TTS Engine

The application uses the browser's built-in Web Speech API for Text-to-Speech functionality by default - no additional setup required! 🎯

🤖 AI-Powered Smart Suggestions

Currently integrated with Groq SDK for intelligent phrase suggestions. The app supports multiple AI providers:

  • 🟢 Groq (Current) - Fast inference for real-time suggestions
  • 🔵 OpenAI GPT-4 - Advanced language understanding
  • 🟡 Google Gemini - Multimodal AI capabilities
  • 🟣 Custom Models - Bring your own AI endpoint

⚙️ Configuration Guide

Smart Suggestions Setup:

// src/components/SmartSuggestions.tsx
// Replace the placeholder with your preferred AI service
const suggestions = await yourAIService.generateSuggestions(context);

Custom TTS Engine:

// src/components/TTSInput.tsx  
// Swap out Web Speech API with your preferred TTS service
const speak = (text: string) => {
  // Your custom TTS implementation here
};

🔑 Environment Variables

Create a .env.local file for API keys:

GROQ_API_KEY=your_groq_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_AI_KEY=your_google_ai_key_here

🛠️ Customization & Development

📁 Project Structure

src/
├── app/
│   ├── page.tsx          # 🏠 Main application layout
│   ├── globals.css       # 🎨 Global styles & Tailwind imports
│   └── layout.tsx        # 📱 Root layout configuration
├── components/           # 🧩 Reusable UI components
│   ├── TTSInput.tsx     # 🎤 Text-to-Speech input component
│   ├── SmartSuggestions.tsx # 🧠 AI-powered suggestions
│   └── ...              # 📦 Other modular components
├── hooks/               # 🪝 Custom React hooks
├── types/               # 📝 TypeScript type definitions
├── data/                # 📊 Static data and configurations
└── assets/              # 🖼️ Images, icons, and media files

🎨 Styling & Theming

  • Global Styles: src/app/globals.css - Base styles and Tailwind imports
  • Component Styles: Tailwind CSS classes for responsive design
  • Custom Themes: Modify CSS variables for color schemes and typography
  • Responsive Design: Mobile-first approach with Tailwind breakpoints

🔧 Key Customization Points

  • 🏠 Layout Changes: src/app/page.tsx - Main app structure and features
  • 🧩 UI Components: src/components/ - Modular, reusable interface elements
  • 🎨 Visual Design: Tailwind config and CSS variables for branding
  • 📱 Mobile Optimization: Touch targets, gestures, and mobile-specific features

🧪 Testing & Quality Assurance

🔍 Manual Testing

  • 🖱️ Desktop Testing: Verify all functionality works with mouse and keyboard
  • 📱 Mobile Testing: Test on actual devices or browser emulation
  • ♿ Accessibility Testing: Screen readers, keyboard navigation, color contrast
  • 🔊 Audio Testing: TTS functionality across different browsers and devices

🤖 Automated Testing (Recommended Setup)

# Install testing dependencies
npm install --save-dev @testing-library/react @testing-library/jest-dom jest

# Run tests
npm test

Suggested Testing Libraries:

  • Jest - Unit testing framework 🧪
  • React Testing Library - Component testing utilities 🔬
  • Cypress - End-to-end testing 🎯
  • Axe - Accessibility testing 🦮

📊 Performance Testing

  • Lighthouse - Performance, accessibility, and SEO audits 🚀
  • Web Vitals - Core web performance metrics 📈
  • Mobile Performance - Test on slower devices and networks 📶

🚀 Deployment

☁️ Deploy on Vercel (Recommended)

Quick Deploy: Deploy with Vercel

Manual Deployment:

  1. 📤 Push to Repository

    git add .
git commit -m "Ready for deployment"
git push origin main

  2. 🔗 Connect to Vercel

    • Visit vercel.com/new
    • Import your GitHub/GitLab repository
    • Vercel will auto-detect Next.js configuration

  3. ⚙️ Environment Variables

    GROQ_API_KEY=your_groq_api_key
OPENAI_API_KEY=your_openai_api_key
NEXT_PUBLIC_APP_URL=https://your-app.vercel.app

  4. 🎉 Deploy

    • Click Deploy button
    • Your app will be live in minutes!

🌐 Alternative Deployment Options

  • Netlify - Static site hosting with serverless functions 🟢
  • Railway - Full-stack deployment platform 🚂
  • AWS Amplify - Scalable cloud hosting ☁️
  • Docker - Containerized deployment 🐳

📈 Production Checklist

  • Environment variables configured 🔑
  • Custom domain setup (optional) 🌐
  • Analytics integration 📊
  • Error monitoring (Sentry, LogRocket) 🐛
  • Performance monitoring 🚀

� Technical Notes & Architecture

💾 Data Storage

  • LocalStorage: Favorites and custom phrases persist offline 🔄
  • Session Management: User preferences maintained across browser sessions
  • Data Privacy: All user data stays on device - no external storage 🔒

♿ Accessibility Features

  • WCAG 2.1 AA Compliant: Meets international accessibility standards ✅
  • Screen Reader Support: Semantic HTML and ARIA labels 🔊
  • Keyboard Navigation: Full functionality without mouse 🎹
  • High Contrast Mode: Enhanced visibility options 🌓
  • Touch Accessibility: 44px minimum touch targets 👆

🏗️ Architecture Highlights

  • React 19: Latest React features with concurrent rendering ⚛️
  • Next.js 15: App Router with server components 🏃‍♂️
  • TypeScript: Type-safe development experience 📝
  • Tailwind CSS 4: Utility-first styling with modern features 🎨
  • Web Speech API: Native browser TTS integration 🗣️

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

🐛 Bug Reports

Found a bug? Please open an issue with:

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Browser/device information

✨ Feature Requests

Have an idea? Create a feature request with:

  • Detailed description of the feature
  • Use case and benefits
  • Mockups or examples (if applicable)

🔧 Pull Requests

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

📄 License

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

🙏 Acknowledgments

  • Web Speech API - For native browser TTS support 🎤
  • Tailwind CSS - For beautiful, responsive styling 🎨
  • Next.js Team - For the amazing React framework 🚀
  • Accessibility Community - For guidance on inclusive design ♿
  • Contributors - Thank you to everyone who helps improve SpeakEZ! 👥

Made with ❤️ for the Specially-Abled Community

🌟 Star this repo • 🐛 Report Bug • 💡 Request Feature

Empowering Communication, One voice at a time 🗣️✨