SoniScribe is a modern web-based audio transcription tool built with React, TypeScript, and advanced audio visualization libraries. The application enables users to upload, play, and annotate audio files with precision timing and waveform visualization.

• SoniScribe
  • Prerequisites
  • Installation
  • Scripts
    • Start Development Server
    • Start Https Tunnel
    • Build for Production
    • Lint the Codebase
    • Preview the Production Build
    • Run Tests
    • Generate Coverage Report
  • Testing
  • Project Structure

Before you begin, ensure you have met the following requirements:

• Node.js: Version 16 or higher. Download Node.js
• Git: Installed on your machine. Download Git
• Microsoft Dev Tunnels: Install Dev Tunnels

1. Clone the Repository

   git clone https://github.com/your-username/transcription-app.git
   cd transcription-app

2. Install Dependencies

   npm install

3. Start the Development Server

   npm run dev

4. Developing with HTTPS

• Usage of the File System API requires the app to be hosted on HTTPS. Go to Microsoft Dev Tunnels to install Dev Tunnels on your machine. Then start the tunnel using:

  npm run tunnel

The project includes several npm scripts to streamline development and deployment:

npm run dev

This script will start a https tunnel in order for the File System API to work locally.

npm run tunnel

npm run build

Run TypeScript type checking without building:

npm run type-check

Build with type checking (recommended for CI/CD):

npm run build:check

npm run lint

npm run preview

Run the test suite with Vitest:

npm test

Run tests in watch mode during development:

npm run test:watch

Open the interactive test UI:

npm run test:ui

Generate a comprehensive test coverage report:

npm run test:coverage

View the detailed HTML coverage report in your browser:

npm run test:coverage:serve

This serves the coverage report at http://localhost:8080 where you can:

• Browse file-by-file coverage details
• See highlighted uncovered lines
• Navigate through your codebase with coverage metrics
• View coverage statistics and charts

Generate coverage and immediately serve it locally:

npm run test:coverage:open

SonicScribe uses Vitest + React Testing Library for comprehensive testing:

• Unit Tests: Individual component and hook testing
• Integration Tests: Multi-component workflow testing
• Coverage Reports: Detailed code coverage analysis
• CI/CD Integration: Automated testing in GitHub Actions

src/
├── test/
│   ├── setup.ts              # Global test configuration
│   ├── utils.tsx              # Custom testing utilities
│   ├── integration/           # Integration tests
│   └── README.md              # Detailed testing docs
├── components/
│   └── **/*.test.tsx          # Component tests
└── hooks/
    └── **/*.test.tsx          # Hook tests

• Audio-specific mocking: AudioContext, MediaElement APIs
• Browser API mocks: matchMedia, ResizeObserver, IntersectionObserver
• Custom utilities: Audio file creation, waveform simulation
• Keyboard testing: Comprehensive shortcut testing
• Coverage thresholds: Enforced quality standards

# Run all tests once
npm test

# Watch mode for development  
npm run test:watch

# Interactive UI mode
npm run test:ui

# Coverage report
npm run test:coverage

# Serve coverage report locally at http://localhost:8080
npm run test:coverage:serve

# Generate and serve coverage in one command
npm run test:coverage:open

For detailed testing documentation, see src/test/README.md.

• Peaks.js Integration: Advanced waveform visualization with zoom, overview, and detailed views • Point & Segment Management: Create, edit, and manage audio markers and segments • Playback Controls: Full transport controls (play/pause, seek, speed adjustment) • Context Menus: Right-click functionality for audio elements • Keyboard Shortcuts: Comprehensive keyboard navigation and control

• File System Integration: Direct browser-based file system access using modern APIs • Project Persistence: Save and load transcription projects with all annotations • Drag & Drop Interface: Intuitive file upload with validation and error handling • Project List Management: Multiple project handling with rename/delete functionality

• Modal System: Centralized dialog management with responsive design • Theme Support: Dynamic theme system with light/dark mode capabilities • Responsive Design: Mobile-friendly interface with touch support • Context Menus: Custom right-click menus for workflow efficiency

• Subdivision Controls: Configurable audio segment divisions (quarters, eighths, etc.) • Multi-tap Interface: Touch-friendly controls for mobile devices • Segment Annotation: Name and color-code audio segments • Point Navigation: Quick jumping between marked positions

🛠️ Technical Highlights

• Zustand Stores: Lightweight state management for settings, dialogs, context menus, and segments • Persistent Storage: Local storage integration for user preferences • Context Management: Centralized state for complex UI interactions

• usePeaks: Core audio waveform management • useProjects: Project file system operations • useKeyPress: Keyboard shortcut handling • useEventListener: Efficient event management with cleanup • useMediaQuery: Responsive design support

• Modern File APIs: Utilizes cutting-edge browser file system access • HTTPS Requirement: Configured with dev tunnels for secure local development • Error Handling: Comprehensive file operation error management