TranscriptionBar

A modern, customizable voice transcription component for React with Web Speech API integration. Built with TypeScript, Tailwind CSS, and Framer Motion for smooth animations.

Quick Start

Installation

npm install transcription-bar
# or
yarn add transcription-bar
# or
pnpm add transcription-bar

Basic Usage

import { TranscriptionBar } from 'transcription-bar';

export function App() {
  return (
    <TranscriptionBar
      heading="Voice Transcription"
      hint="Click start to begin recording..."
      onTranscriptionComplete={(transcript) => {
        console.log('Transcription:', transcript);
      }}
    />
  );
}

With Custom Theme

import { TranscriptionBar, ThemeProvider } from 'transcription-bar';

export function App() {
  return (
    <ThemeProvider theme={{ colors: { primary: { 500: '#007bff' } } }}>
      <TranscriptionBar
        heading="Voice Transcription"
        hint="Click start to begin recording..."
      />
    </ThemeProvider>
  );
}

With Custom Components

import { TranscriptionBar } from 'transcription-bar';

export function App() {
  return (
    <TranscriptionBar heading="Voice Transcription">
      <TranscriptionBar.Header>
        <TranscriptionBar.HeaderLeft />
        <TranscriptionBar.HeaderRight>
          <CustomActionButton />
        </TranscriptionBar.HeaderRight>
      </TranscriptionBar.Header>
      <TranscriptionBar.Content>
        <TranscriptionBar.ErrorDisplay />
        <CustomTranscriptDisplay />
      </TranscriptionBar.Content>
    </TranscriptionBar>
  );
}

Table of Contents

1. Overview
2. Architecture
3. Features
4. Installation
5. Quick Start
6. API Reference
7. Theme Customization
8. Component Customization
9. Best Practices
10. Browser Support
11. Contributing
12. License

Overview

TranscriptionBar is a production-ready React component that provides voice-to-text transcription capabilities using the Web Speech API. It features:

• Zero Configuration: Works out of the box with sensible defaults
• Fully Customizable: Theme system and compound component pattern for complete control
• TypeScript Support: Full type safety with comprehensive type definitions
• Accessible: Built with accessibility best practices
• Responsive: Works seamlessly on desktop and mobile devices
• Smooth Animations: Powered by Framer Motion for delightful UX
• Internationalization: Built-in support for multiple languages

Architecture

Component Structure

TranscriptionBar uses a compound component pattern for maximum flexibility:

TranscriptionBar (root)
├── Header (container)
│   ├── HeaderLeft (left section)
│   └── HeaderRight (right section)
│       └── ActionButton (default)
├── Content (container)
│   ├── ErrorDisplay (default)
│   └── TranscriptContent (default)

State Management

The component uses React Context (TranscriptionBarContext) to manage state and provide access to:

• Current transcription state (idle, recording, processing, finished)
• Transcript data (final and interim)
• Error information
• Theme configuration
• Control handlers (start, stop, reset)

Theme System

A comprehensive theming system allows customization of:

• Colors (primary, neutral, semantic)
• Typography (fonts, sizes, weights)
• Spacing and sizing
• Border radius and transitions
• Component-specific tokens

Features

• ✅ Real-time voice transcription using Web Speech API
• ✅ Support for multiple languages
• ✅ Customizable theme system
• ✅ Compound component pattern for flexible composition
• ✅ Error handling and recovery
• ✅ Recording indicators and visual feedback
• ✅ Smooth animations with Framer Motion
• ✅ Full TypeScript support
• ✅ Accessible UI components
• ✅ Responsive design
• ✅ Zero external dependencies (except React)

Installation

Prerequisites

• React 18.0 or higher
• React DOM 18.0 or higher

Package Installation

npm install transcription-bar

CSS Import

The component includes styles. Import them in your application:

import 'transcription-bar/styles';

Or if using CSS modules:

import styles from 'transcription-bar/styles';

Quick Start

1. Basic Setup

import { TranscriptionBar } from 'transcription-bar';
import 'transcription-bar/styles';

export function App() {
  return (
    <TranscriptionBar
      heading="My Transcription App"
      hint="Click the button to start recording..."
    />
  );
}

2. Handle Transcription Results

import { TranscriptionBar } from 'transcription-bar';

export function App() {
  const handleComplete = (transcript: string) => {
    console.log('Final transcript:', transcript);
    // Send to API, save to database, etc.
  };

  return (
    <TranscriptionBar
      heading="Voice Transcription"
      onTranscriptionComplete={handleComplete}
    />
  );
}

3. Apply Custom Theme

import { TranscriptionBar, ThemeProvider } from 'transcription-bar';

const customTheme = {
  colors: {
    primary: {
      500: '#007bff',
      600: '#0056b3',
    },
  },
  transcriptionBar: {
    header: {
      background: '#ffffff',
      text: '#000000',
    },
  },
};

export function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <TranscriptionBar heading="Voice Transcription" />
    </ThemeProvider>
  );
}

4. Customize Components

import { TranscriptionBar, useTranscriptionBarContext } from 'transcription-bar';

function CustomButton() {
  const { state, onStart, onStop } = useTranscriptionBarContext();
  const isRecording = state === 'recording';

  return (
    <button onClick={isRecording ? onStop : onStart}>
      {isRecording ? 'Stop' : 'Start'}
    </button>
  );
}

export function App() {
  return (
    <TranscriptionBar>
      <TranscriptionBar.Header>
        <TranscriptionBar.HeaderRight>
          <CustomButton />
        </TranscriptionBar.HeaderRight>
      </TranscriptionBar.Header>
      <TranscriptionBar.Content>
        <TranscriptionBar.TranscriptContent />
      </TranscriptionBar.Content>
    </TranscriptionBar>
  );
}

API Reference

TranscriptionBar Component

Main component that wraps all transcription functionality.

<TranscriptionBar
  heading="Voice Transcription"
  hint="Click to start recording"
  onTranscriptionComplete={(transcript) => {}}
  onError={(error) => {}}
>
  {/* Optional: Custom compound components */}
</TranscriptionBar>

Props:

• heading?: string - Header text displayed in the component
• hint?: string - Hint text shown to users
• onTranscriptionComplete?: (transcript: string) => void - Callback when transcription finishes
• onError?: (error: string) => void - Callback when an error occurs
• children?: ReactNode - Optional custom component composition

useTranscriptionBarContext Hook

Access component state and handlers from any nested component.

const {
  state,              // Current state: 'idle' | 'recording' | 'processing' | 'finished'
  transcript,         // Final transcript text
  interimTranscript,  // Live transcript while recording
  error,              // Error message if any
  onStart,            // Start recording
  onStop,             // Stop recording
  onReset,            // Reset to idle state
  theme,              // Current theme object
  heading,            // Component heading
  hint,               // Component hint text
} = useTranscriptionBarContext();

useTheme Hook

Access the current theme from any component.

const theme = useTheme();
// Use theme.colors, theme.spacing, theme.typography, etc.

useWebSpeech Hook

Low-level hook for direct Web Speech API access.

const {
  transcript,
  interimTranscript,
  isListening,
  error,
  startListening,
  stopListening,
  resetTranscript,
} = useWebSpeech({
  language: 'en-US',
  continuous: true,
  interimResults: true,
});

ThemeProvider Component

Provides custom theme to all nested components.

<ThemeProvider theme={customTheme}>
  <TranscriptionBar />
</ThemeProvider>

Compound Components

• TranscriptionBar.Header - Header container
• TranscriptionBar.HeaderLeft - Left section of header
• TranscriptionBar.HeaderRight - Right section of header
• TranscriptionBar.ActionButton - Default action button
• TranscriptionBar.Content - Content container
• TranscriptionBar.ErrorDisplay - Error message display
• TranscriptionBar.TranscriptContent - Transcript display
• TranscriptionBar.RecordingIndicator - Recording visual indicator

Theme Customization

Theme Structure

The theme object is organized into logical sections:

{
  colors: {
    primary: { 50: '...', 100: '...', ..., 900: '...' },
    neutral: { 0: '...', 50: '...', ..., 950: '...' },
    success: '#10b981',
    warning: '#f59e0b',
    error: '#ef4444',
    info: '#29b6f6',
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
    '2xl': '2.5rem',
    '3xl': '3rem',
  },
  sizing: {
    maxHeight: { sm: '200px', md: '300px', lg: '400px', xl: '420px' },
    icon: { sm: '1rem', md: '1.25rem', lg: '1.5rem' },
    button: { sm: '2rem', md: '2.5rem', lg: '3rem' },
  },
  typography: {
    fontFamily: { sans: '...', serif: '...', mono: '...' },
    fontSize: { xs: '0.75rem', sm: '0.875rem', base: '1rem', ... },
    fontWeight: { normal: 400, medium: 500, semibold: 600, bold: 700 },
    lineHeight: { tight: 1.2, normal: 1.5, relaxed: 1.8 },
  },
  borderRadius: {
    none: '0',
    sm: '0.25rem',
    md: '0.5rem',
    lg: '0.75rem',
    xl: '1rem',
    '2xl': '1.5rem',
    '3xl': '2rem',
    full: '9999px',
  },
  transitions: {
    fast: '150ms ease-in-out',
    base: '200ms ease-in-out',
    slow: '300ms ease-in-out',
  },
  transcriptionBar: {
    header: { background: '...', text: '...', ... },
    content: { background: '...', border: '...' },
    button: { primary: { ... }, secondary: { ... } },
    recording: { active: '...', inactive: '...', ... },
    transcript: { text: '...', textInterim: '...', ... },
    chat: { userMessage: { ... }, assistantMessage: { ... }, ... },
    overlay: { light: '...', dark: '...' },
    shadow: { container: '...', card: '...', ... },
    processing: { ... },
  },
}

Creating Custom Themes

Method 1: Partial Theme

<ThemeProvider theme={{ colors: { primary: { 500: '#ff0000' } } }}>
  <TranscriptionBar />
</ThemeProvider>

Method 2: Using createTheme

import { createTheme } from 'transcription-bar';

const customTheme = createTheme({
  colors: { primary: { 500: '#ff0000' } },
  spacing: { md: '1.5rem' },
});

<ThemeProvider theme={customTheme}>
  <TranscriptionBar />
</ThemeProvider>

Method 3: Complete Theme Override

import { DEFAULT_THEME, createTheme } from 'transcription-bar';

const completeTheme = createTheme({
  colors: { /* all colors */ },
  spacing: { /* all spacing */ },
  // ... all other properties
});

Theme Examples

See THEME_GUIDELINE.md for:

• Light theme example
• High contrast theme example
• Brand-specific theme example
• Dynamic theme switching
• Using theme in custom components

Component Customization

Using Compound Components

Replace or reorder components as needed:

<TranscriptionBar>
  <TranscriptionBar.Header>
    <TranscriptionBar.HeaderLeft />
    <TranscriptionBar.HeaderRight>
      <CustomActionButton />
    </TranscriptionBar.HeaderRight>
  </TranscriptionBar.Header>
  <TranscriptionBar.Content>
    <CustomTranscriptDisplay />
  </TranscriptionBar.Content>
</TranscriptionBar>

Creating Custom Components

Access component state using useTranscriptionBarContext:

import { useTranscriptionBarContext } from 'transcription-bar';

function CustomTranscriptDisplay() {
  const { transcript, interimTranscript, theme } = useTranscriptionBarContext();

  return (
    <div style={{ color: theme.colors.primary[500] }}>
      <p>{transcript}</p>
      {interimTranscript && <p>{interimTranscript}</p>}
    </div>
  );
}

Styling Custom Components

Use theme values for consistent styling:

function StyledComponent() {
  const { theme } = useTranscriptionBarContext();

  return (
    <div
      style={{
        color: theme.colors.primary[500],
        padding: theme.spacing.lg,
        borderRadius: theme.borderRadius.md,
        fontSize: theme.typography.fontSize.base,
        fontWeight: theme.typography.fontWeight.semibold,
        transition: theme.transitions.base,
      }}
    >
      Content
    </div>
  );
}

Common Customization Patterns

See COMPONENT_CUSTOMIZATION_GUIDELINE.md for:

• Wrapping existing components
• Extending component behavior
• Creating custom headers and transcripts
• Custom error displays
• Custom action buttons
• Adding metadata display
• Adding action buttons
• Adding loading states
• Copy to clipboard functionality
• Keyboard shortcuts

Best Practices

Theme Customization

1. Use createTheme for complex customizations
2. Keep theme objects at the top level to avoid recreating on every render
3. Use semantic color names when possible
4. Test color contrast for accessibility
5. Document custom themes for team consistency

Component Customization

1. Always use useTranscriptionBarContext to access state
2. Leverage theme values for consistent styling
3. Keep components focused with single responsibility
4. Use compound components for flexible composition
5. Check state before rendering conditional content
6. Use provided helper functions for state checks
7. Maintain accessibility in custom components
8. Test custom components with different themes

Performance

1. Memoize custom components if they receive props
2. Avoid recreating theme objects on every render
3. Use useCallback for event handlers in custom components
4. Consider lazy loading for heavy custom components

Accessibility

1. Ensure custom buttons have proper ARIA labels
2. Maintain keyboard navigation support
3. Use semantic HTML elements
4. Test with screen readers
5. Maintain sufficient color contrast ratios

Browser Support

TranscriptionBar uses the Web Speech API, which is supported in:

• Chrome/Edge 25+
• Firefox 25+
• Safari 14.1+
• Opera 27+

Note: Web Speech API support varies by browser. Always provide fallback UI for unsupported browsers.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Code style and standards
• Submitting pull requests
• Reporting issues
• Feature requests

License

ISC License - see LICENSE file for details

Resources

• Theme Customization Guide
• Component Customization Guide
• GitHub Repository
• Issue Tracker

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing documentation and guides
• Review examples in the example directory