@pie-players/pie-tool-tts-inline

Inline TTS (Text-to-Speech) tool component for PIE Players Assessment Toolkit.

Overview

pie-tool-tts-inline is a web component that renders a Material Design speaker icon button for triggering TTS playback. Unlike floating modal tools, this component renders inline at its natural position in the DOM (typically in headers).

Features

• Material Design speaker icon (🔊)
• Registers with ToolCoordinator for lifecycle management
• Integrates with TTSService for QTI 3.0 catalog-based TTS
• Size variants: sm, md, lg
• Visual feedback during speaking (pulse animation)
• Full accessibility support (ARIA labels, keyboard navigation)
• Coordinator-controlled visibility via CSS display property

Installation

bun add @pie-players/pie-tool-tts-inline

Usage

import '@pie-players/pie-tool-tts-inline';
import { TTSService, BrowserTTSProvider, ToolCoordinator } from '@pie-players/pie-assessment-toolkit';

// Initialize services
const ttsService = new TTSService();
await ttsService.initialize(new BrowserTTSProvider());
const toolCoordinator = new ToolCoordinator();

// Create element
const ttsButton = document.createElement('pie-tool-tts-inline');
ttsButton.setAttribute('tool-id', 'tts-passage-1');
ttsButton.setAttribute('catalog-id', 'passage-1');
ttsButton.setAttribute('size', 'md');

// Bind services as JavaScript properties (not HTML attributes)
ttsButton.ttsService = ttsService;
ttsButton.coordinator = toolCoordinator;

// Coordinator controls visibility
toolCoordinator.showTool('tts-passage-1');

With Svelte

<script>
  import '@pie-players/pie-tool-tts-inline';
  import { ZIndexLayer } from '@pie-players/pie-assessment-toolkit';

  let ttsToolElement;

  $effect(() => {
    if (ttsToolElement && toolCoordinator) {
      ttsToolElement.ttsService = ttsService;
      ttsToolElement.coordinator = toolCoordinator;

      if (ttsService) {
        toolCoordinator.showTool('tts-passage-1');
      }
    }
  });
</script>

<div class="header">
  <h3>Passage Title</h3>
  <pie-tool-tts-inline
    bind:this={ttsToolElement}
    tool-id="tts-passage-1"
    catalog-id="passage-1"
    size="md"
  ></pie-tool-tts-inline>
</div>

Props

HTML Attributes

• tool-id - Unique identifier for tool registration (default: 'tts-inline')
• catalog-id - QTI 3.0 accessibility catalog ID for SSML lookup (default: '')
• language - Language code for TTS (default: 'en-US')
• size - Icon size: 'sm' (1.5rem), 'md' (2rem), or 'lg' (2.5rem) (default: 'md')

JavaScript Properties

• ttsService - ITTSService instance (required)
• coordinator - IToolCoordinator instance (optional, for visibility management)

Behavior

1. Tool Registration: Registers with ToolCoordinator on mount using the provided tool-id
2. Text Extraction: Finds nearest .passage-content or .item-content container
3. TTS Trigger: Calls ttsService.speak(text, { catalogId, language })
4. Catalog Resolution: TTSService checks for SSML in accessibility catalogs (priority order):
   • Extracted catalogs (from embedded SSML) - auto-generated by section player
   • Item-level catalogs (manually authored)
   • Assessment-level catalogs (manually authored)
   • Plain text fallback (browser TTS)
5. Visual Feedback: Pulse animation while speaking, disabled state
6. Cleanup: Unregisters from coordinator on unmount

SSML Extraction Integration

When used with the section player, this tool automatically benefits from SSML extraction:

Author embeds SSML in content:

<div>
  <speak>Solve <prosody rate="slow">x squared plus two</prosody>.</speak>
  <p>Solve x² + 2 = 0</p>
</div>

Section player extracts SSML at runtime:

• Generates catalog with ID like auto-prompt-q1-0
• Adds data-catalog-id="auto-prompt-q1-0" to visual content
• Registers catalog with AccessibilityCatalogResolver

Tool uses extracted catalog:

• User clicks TTS button in header
• Tool calls ttsService.speak(text, { catalogId: 'auto-prompt-q1-0' })
• TTSService finds SSML in extracted catalogs
• Speaks with proper math pronunciation and pacing

Result: Authors get high-quality TTS without maintaining separate catalog files.

Styling

The component uses inline styles and doesn't require external CSS. The button is transparent by default with hover effects:

• Normal: Gray icon, transparent background
• Hover: Purple icon, light gray background
• Speaking: Purple icon, blue tinted background with pulse animation
• Disabled: Reduced opacity, no pointer

Architecture

This tool follows the PIE Assessment Toolkit tool pattern:

• Always rendered in DOM at natural position
• ToolCoordinator controls visibility via showTool()/hideTool() (CSS display property)
• Registers with ZIndexLayer.TOOL for proper layering
• Services passed as JavaScript properties (objects can't be HTML attributes)

Example

See the complete working demo at packages/section-player/demos/tts-integration-demo.html.

License

MIT