Skip to content

About

cough-test-voice-collector.vercel.app

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

CoughTestVoiceCollector: Enterprise Audio Research Platform

📋 Table of Contents

Overview

CoughTestVoiceCollector is a production-ready, enterprise-grade web application designed for systematic collection and analysis of cough audio data in academic research environments. Built with modern web technologies and optimized for performance, the platform implements IEEE-compliant software engineering standards while providing researchers with robust, scalable tools for audio data acquisition, validation, and export.

Key Domains: Academic Research • Audio Data Collection • Software Engineering • Data Science • Performance Engineering

🏆 Production Highlights

  • Live Deployment: Fully operational on Vercel + PythonAnywhere
  • Performance Optimized: Sub-second page loads with intelligent caching
  • Mobile First: Responsive design with 480px breakpoint optimization
  • Real-time Updates: Instant data refresh with cache invalidation
  • Enterprise Ready: Scalable architecture with comprehensive error handling

🌐 Application Access

🚀 Production Deployment (Ready to Use)

💻 Local Development

Performance Features

🚀 Speed Optimizations

  • Critical Path Loading: Home and Record pages preloaded for instant access
  • Skeleton Loaders: Animated placeholders during data fetching
  • Smart Caching: Multi-layer cache invalidation with real-time updates
  • API Optimization: 10s timeout for list requests, optimized queries
  • Bundle Splitting: Lazy loading for non-critical components

📱 Mobile Optimization

  • Responsive Breakpoints: 480px optimized for consistent mobile experience
  • Touch-Friendly UI: 44px minimum touch targets for accessibility
  • Auto-Close Navigation: Mobile navbar closes automatically after selection
  • Optimized Forms: Mobile-first form design with proper input types
  • Performance Scaling: Reduced animations and effects on mobile devices

🔄 Real-Time Features

  • Instant Updates: New recordings appear immediately without page refresh
  • Event-Driven Refresh: Cross-component communication for data synchronization
  • Cache Busting: Automatic browser cache invalidation after uploads
  • Live Analytics: Real-time statistics with 5-minute cache refresh

✨ Features at a Glance

🎙️ Audio Collection

  • Browser-based 10-second recording
  • Multi-format file upload support
  • Bulk import capabilities
  • Real-time quality validation

📊 Data Management

  • Comprehensive metadata capture
  • Multi-format export (CSV/HTML/ZIP)
  • Real-time analytics dashboard
  • Advanced search and filtering

🔒 Security & Privacy

  • Anonymous submission support
  • JWT authentication
  • Secure file storage
  • Research ethics compliance

📚 Academic Standards

  • IEEE-compliant documentation
  • Reproducible research framework
  • Complete testing strategy
  • Professional code quality

🎬 Features Showcase

Platform Interface

Home Page

Home Page Landing page with quick access to recording, browsing, and analytics features

Recording Interface

Recording Interface Intuitive browser-based audio capture with real-time feedback and quality validation

Analytics Dashboard

Analytics Dashboard Comprehensive statistics showing total recordings, users, data quality metrics, and usage patterns

Data Management

Browse Recordings Browse, filter, search, and export recordings with advanced data management tools

Admin Panel

Admin Panel Django admin interface for comprehensive data management and system configuration

Core Capabilities

Research Features

  • Standardized Data Collection: Browser-based 10-second audio recording with automated quality validation
  • Comprehensive Metadata Capture: Technical specifications, user context, and system information for each recording
  • Multi-Format Export: CSV for statistical analysis, HTML for review, ZIP for complete datasets
  • Real-Time Analytics: Platform statistics, data quality metrics, and usage patterns
  • Automated Validation: Quality checks ensuring research compliance and data integrity

Technical Architecture

  • Full-Stack Implementation: Django REST API backend with React single-page application frontend
  • Flexible Authentication: JWT-based user accounts with support for anonymous submissions
  • Audio Format Support: WAV, MP3, WebM, OGG, M4A file processing and storage
  • Responsive Design: Cross-platform compatibility for desktop and mobile devices
  • Performance Optimization: Caching strategies, pagination, and efficient data handling
  • Modern Development Practices: Clean architecture, modular design, and comprehensive error handling

Academic Compliance

  • IEEE Standards: Full compliance with IEEE 830-1998 (Requirements), IEEE 1016-2009 (Design), and IEEE 829-2008 (Testing)
  • Research Methodology: Systematic data collection framework with validation procedures
  • Professional Documentation: 14 comprehensive documents covering all system aspects
  • Quality Assurance: Complete testing strategy with validation and verification procedures

Getting Started

System Requirements

  • Python 3.9 or higher
  • Node.js 18.0 or higher
  • Git version control
  • 2GB available disk space
  • Modern web browser (Chrome, Firefox, Safari, Edge)

Installation Instructions

Windows:

git clone https://github.com/alphapie77/CoughTestVoiceCollector.git
cd CoughTestVoiceCollector
scripts\setup.bat
scripts\start_servers.bat

macOS/Linux:

git clone https://github.com/alphapie77/CoughTestVoiceCollector.git
cd CoughTestVoiceCollector
chmod +x scripts/*.sh
./scripts/setup.sh
./scripts/start_servers.sh

Quick Setup

Try it now (No installation required):

For local development:

Data Collection Framework

Metadata Schema

Each recording captures comprehensive metadata for research analysis:

  • Audio Technical Specifications: Duration, sample rate, bit rate, channel configuration, file size
  • User Attribution: Authenticated username or anonymous identifier
  • Recording Context: Collection method (browser/upload), timestamp, file format
  • System Telemetry: IP address, user agent (for research purposes only)

Export Data Structure

CSV exports include the following fields for statistical analysis:

Recording ID, User Type, User Name, File Name, File Size (MB),
File Format, Duration (seconds), Recording Method, Created At,
Sample Rate, Bit Rate, Channels, IP Address, User Agent

Project Architecture

CoughTestVoiceCollector/
├── 📁 backend/              # Django REST API
│   ├── accounts/            # User authentication
│   ├── recordings/          # Audio recording management
│   ├── coughtest_backend/   # Django project settings
│   └── requirements.txt     # Python dependencies
├── 📁 frontend/             # React application
│   ├── src/                 # Source code
│   │   ├── components/      # Reusable UI components
│   │   ├── pages/           # Page components
│   │   ├── contexts/        # React contexts
│   │   └── services/        # API communication
│   └── package.json         # Node.js dependencies
├── 📁 scripts/              # Automation scripts
│   ├── setup.bat/.sh        # Project setup
│   ├── start_servers.bat/.sh # Development servers
│   └── build_production.bat # Production build
├── 📁 docs/                 # Documentation
└── README.md               # This file

Development Scripts

Script Windows macOS/Linux Description
Setup scripts\setup.bat ./scripts/setup.sh Install dependencies, create admin user
Start scripts\start_servers.bat ./scripts/start_servers.sh Run development servers
Build scripts\build_production.bat Manual commands Build for production
Test scripts\test_application.bat Manual commands Test application

Bulk Data Import

The platform supports importing existing audio datasets through a Django management command:

cd backend
python manage.py import_cough_data "path/to/audio/files" --anonymous-prefix "Study2024"

Supported Audio Formats: WAV, MP3, WebM, M4A, OGG

Refer to the Bulk Import Guide for detailed instructions and best practices.

Platform Compatibility

  • Web Browsers: Chrome, Firefox, Safari, Edge (latest versions)
  • Operating Systems: Windows 10/11, macOS 10.15+, Linux (Ubuntu 20.04+)
  • Database Systems: SQLite (development), PostgreSQL, MySQL (production)
  • Deployment Options: AWS, Azure, Google Cloud, self-hosted servers, Docker containers

Documentation

Comprehensive documentation suite covering all aspects of the platform:

Academic & Technical Standards

User & Operations Guides

Testing & Quality Assurance

Use Cases

Research Applications

  • Data Collection: Systematic audio sampling with standardized protocols and quality controls
  • Statistical Analysis: Export capabilities for R, Python, SPSS, and other analysis tools
  • Quality Assurance: Automated validation ensuring data integrity and research compliance
  • Longitudinal Studies: Comprehensive audit trails for tracking contributions over time
  • Multi-Site Research: Standardized collection protocols across distributed research locations

Academic Validation

  • Thesis Research: Complete platform demonstrating professional software engineering principles
  • Peer Review: IEEE-compliant documentation suitable for academic review and publication
  • Reproducible Research: Full methodology documentation enabling research replication
  • Educational Resource: Reference implementation of modern full-stack development practices

Participant Experience

  • Streamlined Contribution: Browser-based recording or file upload with minimal friction
  • Flexible Authentication: Optional user accounts with JWT security or anonymous submission
  • Quality Feedback: Real-time validation and recording quality assessment
  • Contribution Tracking: Personal dashboard for registered users to monitor their submissions

Technical Integration

  • Architecture Reference: Modern full-stack implementation with clean separation of concerns
  • API Integration: RESTful API with comprehensive documentation and examples
  • Quality Standards: IEEE-compliant requirements, design, and testing documentation
  • Testing Framework: Complete testing strategy with unit, integration, and system tests

Security & Privacy

  • Anonymous Submissions: Platform supports data collection without personal information requirements
  • Secure Storage: Audio files stored with UUID identifiers, isolated from user data
  • JWT Authentication: Industry-standard token-based authentication for registered users
  • Research Metadata: IP addresses and user agents collected solely for academic research purposes
  • Data Protection: Compliance with research ethics and data protection best practices

📈 Research Data & Academic Integrity

Dataset Information

This repository contains authentic research data collected for academic validation purposes:

Data Components:

  • Database: backend/db.sqlite3 (metadata, user information, system logs)
  • Audio Files: backend/media/cough_recordings/ (research audio samples)
  • Documentation: Complete methodology and validation procedures
  • Export Tools: Multi-format data export capabilities for statistical analysis

Research Standards:

  • Data Integrity: Complete preservation for academic validation and peer review
  • Reproducibility: Comprehensive methodology documentation enabling research replication
  • Quality Assurance: Systematic validation procedures ensuring data reliability
  • Ethical Compliance: Privacy protection and informed consent management

Academic Contributions

  • Software Engineering: Professional development practices and architectural patterns
  • Research Methodology: Systematic data collection and validation framework
  • Quality Assurance: IEEE-compliant testing and documentation standards
  • Data Science: End-to-end pipeline from collection to analysis-ready export

Research Integrity Notice: All data is preserved in its original form for academic validation, peer review, and reproducibility verification.

🔧 Technical Specifications

Standards Compliance

  • IEEE 830-1998: Software Requirements Specification
  • IEEE 1016-2009: Software Design Descriptions
  • IEEE 829-2008: Software Test Documentation
  • Academic research methodology standards

Documentation Metrics

  • 14 comprehensive technical documents
  • 3,200+ lines of professional documentation
  • Multi-audience approach (engineers, researchers, end-users)
  • Complete technical specifications and validation procedures

Software Quality Attributes

  • Full-stack web application architecture (Django REST + React SPA)
  • RESTful API with comprehensive endpoint documentation
  • Responsive design with cross-platform browser support
  • Comprehensive testing strategy with automated validation
  • Modern development practices and clean code architecture

Research Capabilities

  • Standardized data collection protocols with quality validation
  • Multi-format export (CSV, HTML, ZIP) for various analysis tools
  • Real-time analytics dashboard with quality metrics
  • Bulk import utilities for existing audio datasets
  • Automated metadata extraction and validation

📞 Support & Resources

Academic Inquiries

Technical Support

🛠️ Troubleshooting

Production Platform Issues

Problem: Upload timeout on bulk files

  • Solution: Files are likely still processing. Check the Browse page after a few minutes.
  • The platform handles large uploads but may show timeout messages.

Problem: Mobile navbar doesn't close

  • Solution: This has been fixed. The mobile menu now closes automatically when clicking navigation links.

Problem: Page refresh shows 404

  • Solution: This has been resolved with proper URL rewrite rules for client-side routing.

Problem: New recordings don't appear immediately

  • Solution: This has been fixed with cache invalidation. New recordings now appear instantly.

Local Development Issues

Problem: Recording upload fails

# Solution: Ensure media directories exist
cd backend
mkdir media\cough_recordings  # Windows
mkdir -p media/cough_recordings  # Linux/macOS

Problem: Cannot fetch recordings

# Solution: Check if backend server is running
cd backend
python manage.py runserver

Problem: Frontend not connecting to backend

  • Verify backend is running on http://localhost:8000
  • Check CORS settings in backend/coughtest_backend/settings.py
  • Ensure frontend .env has correct REACT_APP_API_URL

Problem: Database migration errors

cd backend
python manage.py migrate --run-syncdb

Problem: Development and production look different

  • Solution: Mobile responsive breakpoint has been adjusted to 480px for consistency.

For more issues, see Windows Setup Guide or Cross-Platform Guide.

❓ FAQ

Q: Can I use this for commercial purposes?
A: This is released under an Academic Research License. Contact the author for commercial licensing.

Q: How do I contribute audio samples?
A: Simply visit the platform, click "Record Cough", and follow the instructions. No account required!

Q: Is my data secure and anonymous?
A: Yes! The platform supports fully anonymous submissions with secure UUID-based file storage.

Q: What audio formats are supported?
A: WAV, MP3, WebM, OGG, and M4A formats are fully supported.

Q: Can I export data for analysis?
A: Yes! Export in CSV (for statistical analysis), HTML (for review), or ZIP (complete dataset).

Q: How do I cite this platform in my research?
A: See the Citation section below.

🗺️ Roadmap

Version 2.0.0 (Current) ✅

  • ✅ Browser-based audio recording
  • ✅ Multi-format file upload with bulk support
  • ✅ Real-time analytics dashboard
  • ✅ Multi-format data export (CSV, HTML, ZIP)
  • ✅ IEEE-compliant documentation
  • ✅ Production deployment on Vercel + PythonAnywhere
  • ✅ Mobile-responsive design with professional UX
  • ✅ Performance optimizations with caching
  • ✅ Real-time updates with cache invalidation
  • ✅ Skeleton loaders for better UX

Version 2.1.0 (Planned)

  • 🔄 Advanced audio analysis features
  • 🔄 Machine learning integration
  • 🔄 Enhanced visualization tools
  • 🔄 Mobile application support

Version 3.0.0 (Future)

  • 📋 Multi-language support
  • 📋 Cloud deployment templates
  • 📋 Advanced collaboration features
  • 📋 API rate limiting dashboard

See CHANGELOG.md for detailed version history.

🤝 Contributing

For Research Participants

Contribute audio samples to advance scientific research:

Production Platform:

  1. Visit https://cough-test-voice-collector.vercel.app/
  2. Click "Record Cough" or "Upload File"
  3. Follow the on-screen instructions
  4. Submit your recording

Local Development:

  1. Visit the platform at http://localhost:3000
  2. Follow the same steps as above

For Developers

We welcome technical contributions! Please follow these steps:

  1. Fork the repository

    git clone https://github.com/alphapie77/CoughTestVoiceCollector.git

  2. Create a feature branch

    git checkout -b feature/your-feature-name

  3. Make your changes

    • Follow the existing code style
    • Add tests for new features
    • Update documentation as needed

  4. Test your changes

    cd backend
python manage.py test

  5. Submit a pull request

    • Provide a clear description of changes
    • Reference any related issues
    • Ensure all tests pass

Development Guidelines

  • Follow PEP 8 for Python code
  • Use ESLint for JavaScript code
  • Write meaningful commit messages
  • Add comments for complex logic
  • Update documentation for new features

For detailed guidelines, see System Design Document and Testing Strategy.

📖 Citation

If you use this platform in your research, please cite:

@software{coughtestvoicecollector2025,
  author = {alphapie77},
  title = {CoughTestVoiceCollector: Enterprise Audio Research Platform},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/alphapie77/CoughTestVoiceCollector},
  version = {2.0.0}
}

APA Format:

alphapie77. (2025). CoughTestVoiceCollector: Enterprise Audio Research Platform 
(Version 2.0.0) [Computer software]. GitHub. 
https://github.com/alphapie77/CoughTestVoiceCollector

📄 License

This software is released under an Academic Research License. The platform was developed for thesis research and audio data collection purposes.

Key Points:

  • ✅ Free for academic and research use
  • ✅ Modification and distribution allowed with attribution
  • ✅ Commercial use requires separate licensing
  • ✅ No warranty provided

See LICENSE for complete terms and conditions.

🙏 Acknowledgments

Technologies & Frameworks

  • Django - High-level Python web framework
  • React - JavaScript library for building user interfaces
  • Bootstrap - CSS framework for responsive design
  • Django REST Framework - Powerful toolkit for building Web APIs

Standards & Compliance

  • IEEE 830-1998 - Software Requirements Specification
  • IEEE 1016-2009 - Software Design Descriptions
  • IEEE 829-2008 - Software Test Documentation

Special Thanks

  • Academic advisors and reviewers
  • Research participants who contributed audio samples
  • Open-source community for excellent tools and libraries

📞 Contact & Support

Project Maintainer

Get Help

🎓 Academic Research Platform for Cough Audio Analysis

Advancing scientific research through systematic audio data collection and analysis

Research Validated IEEE Compliant Professional Quality GitHub Stars

🚀 Live Demo • 📖 Documentation • 🔧 API Reference • 🐛 Report Issue

About

cough-test-voice-collector.vercel.app

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages