@pie-players/pie-tool-text-to-speech

Text-to-Speech Tool (<pie-tool-text-to-speech>)

A draggable, floating tool that reads selected text aloud with word-level highlighting for accessibility.

For the shared TTS architecture and provider model, see TTS Architecture. This README focuses on the floating tool custom element API.

Features

• ✅ Text Selection: Automatically detects selected text on the page
• ✅ Word Highlighting: Highlights each word as it's spoken (yellow background + underline)
• ✅ Speed Control: Adjustable speech rate from 0.5x (Slow) to 2.0x (Very Fast)
• ✅ Playback Controls: Play, Pause/Resume, and Stop buttons
• ✅ Visual Feedback: Status indicator shows speaking/paused state
• ✅ Draggable: Move the tool anywhere on screen
• ✅ Accessibility: Full keyboard support and screen reader compatible

Usage

As Web Component

<pie-tool-text-to-speech
  visible="true"
  tool-id="textToSpeech"
></pie-tool-text-to-speech>

As Svelte Component

<script>
  import '@pie-players/pie-tool-text-to-speech';
  import { toolCoordinator } from '@pie-players/pie-assessment-toolkit';

  let visible = $state(false);
</script>

<pie-tool-text-to-speech
  {visible}
  toolId="textToSpeech"
  coordinator={toolCoordinator}
/>

Via Tool Toolbar

The TTS tool is automatically included when using <pie-tool-toolbar>:

<pie-tool-toolbar tools="protractor,ruler,textToSpeech"></pie-tool-toolbar>

How It Works

• Select Text: User selects any text on the page
• Click Play: Tool reads the selected text aloud
• Word Highlighting: Each word is highlighted with yellow background and underline as it's spoken
• Adjust Speed: Use the slider to change speech rate (0.5x - 2.0x)
• Pause/Resume: Pause and resume playback at any time
• Stop: Stop playback and clear highlights

Props

Prop	Type	Default	Description
visible	Boolean	false	Show/hide the tool
toolId	String	'textToSpeech'	Unique identifier for the tool
coordinator	ToolCoordinator	Required	Tool coordination service

TTS Service Integration

The tool uses the shared TTSService from @pie-players/pie-assessment-toolkit:

import { ttsService } from '@pie-players/pie-assessment-toolkit';

// Initialize
await ttsService.initialize();

// Set root element for highlighting
ttsService.setRootElement(containerElement);

// Speak with options
await ttsService.speak(text, {
  rate: 1.0,
  highlightWords: true
}, {
  onEnd: () => { /* cleanup */ },
  onError: (error) => { /* handle error */ }
});

Browser Support

Text-to-Speech (Web Speech API)

• ✅ Chrome 33+
• ✅ Safari 7+
• ✅ Edge 14+
• ✅ Firefox 49+
• ✅ Mobile: iOS 7+, Android 4.4+
• Coverage: 97%+ of users

Word Highlighting (CSS Custom Highlight API)

• ✅ Chrome 105+
• ✅ Safari 17.2+
• ✅ Edge 105+
• ✅ Firefox 128+
• Coverage: 85-90% of users

The tool gracefully degrades: TTS works everywhere, highlighting only on modern browsers.

Accessibility

• Screen Reader Compatible: Uses Web Speech API which doesn't interfere with screen readers
• Keyboard Navigation: Tool can be moved with keyboard (when focused)
• High Contrast: Works with high contrast mode
• Reduced Motion: Respects prefers-reduced-motion setting
• ARIA Labels: All buttons have proper aria-label attributes

Speed Presets

Value	Label	Description
0.5x	Slow	Half speed
0.75x	Slower	3/4 speed
1.0x	Normal	Default speed
1.25x	Faster	1.25x speed
1.5x	Fast	1.5x speed
2.0x	Very Fast	Double speed

Visual Design

The tool features:

• Purple gradient header (matches other PIE tools)
• Clean, modern UI with rounded corners
• Responsive buttons with hover/disabled states
• Status indicators with animated pulse
• Color-coded feedback: Green (speaking), Yellow (paused), Red (error)

Error Handling

The tool handles these error scenarios:

• TTS Not Supported: Shows error message if browser doesn't support Web Speech API
• No Text Selected: Disables play button until text is selected
• Speech Errors: Shows error message and stops playback
• Network Issues: Gracefully handles offline scenarios (Web Speech API works offline)

Performance

• Lightweight: ~15KB minified
• No Dependencies: Uses browser-native APIs
• Efficient: Only highlights visible text, no DOM mutation
• Memory Safe: Cleans up event listeners on unmount

Example: Complete Integration

<script>
  import '@pie-players/pie-tool-text-to-speech';
  import { toolCoordinator } from '@pie-players/pie-assessment-toolkit';

  let showTTS = $derived(
    toolCoordinator.getToolState('textToSpeech')?.isVisible ?? false
  );

  $effect(() => {
    toolCoordinator.registerTool('textToSpeech', 'Text-to-Speech');
  });
</script>

<!-- Assessment content -->
<div class="question-prompt">
  <p>Read this question carefully and select the best answer.</p>
</div>

<!-- TTS button -->
<button onclick={() => toolCoordinator.toggleTool('textToSpeech')}>
  🔊 Text-to-Speech
</button>

<!-- TTS tool -->
<pie-tool-text-to-speech
  visible={showTTS}
  toolId="textToSpeech"
  coordinator={toolCoordinator}
/>

Future Enhancements

• Voice selection (male/female, language)
• Auto-detect language
• Save speed preference
• Read entire page/section
• Keyboard shortcuts
• Multiple language support
• AWS Polly integration (premium voices) — available via @pie-players/tts-server-polly

Related

• TTS Architecture - TTS system overview
• TTS Server Polly - AWS Polly server provider
• TTS Client Server - Server-backed client provider
• Assessment Toolkit - Toolbar and tool management