Skip to main content

๐ŸŽจ Supernal TTS Widget Guide

:::warning Development Status The Supernal TTS Widget is currently under active development. APIs, features, and integration methods may change. Please test thoroughly before using in production. :::

The Supernal TTS Widget provides an easy way to add text-to-speech functionality to any website with minimal setup.

๐Ÿš€ Quick Startโ€‹

1. Include the Widgetโ€‹

Add the widget script to your HTML:

<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<h1>Welcome to my blog</h1>
<p>This content can be read aloud!</p>

<!-- Supernal TTS Widget -->
<script src="https://tts.supernal.ai/widget.js"></script>
<script>
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
provider: 'mock' // Start with mock for testing
});
</script>
</body>
</html>

2. Test the Widgetโ€‹

Open your page and you should see:

  • A floating audio button
  • Click to hear the page content
  • Automatic text extraction and playback

โš™๏ธ Configuration Optionsโ€‹

SupernalTTS.init({
// Required
apiUrl: 'https://tts.supernal.ai',

// Provider settings
provider: 'openai', // openai, cartesia, azure, mock
voice: 'fable', // Provider-specific voice
speed: 1.0, // 0.25 to 4.0

// Widget appearance
position: 'bottom-right', // bottom-right, bottom-left, top-right, top-left
theme: 'light', // light, dark, auto
size: 'medium', // small, medium, large

// Content selection
selector: 'article, .content', // CSS selector for content
excludeSelector: '.no-audio', // Elements to exclude

// Behavior
autoPlay: false, // Start playing immediately
showProgress: true, // Show playback progress
enableKeyboard: true, // Keyboard shortcuts (space to play/pause)

// Caching
enableCache: true, // Use cached audio when available

// Events
onPlay: () => console.log('Started playing'),
onPause: () => console.log('Paused'),
onEnd: () => console.log('Finished playing'),
onError: (error) => console.error('Error:', error)
});

๐ŸŽฏ Content Selectionโ€‹

Automatic Detectionโ€‹

By default, the widget looks for common content containers:

// Default selectors (in priority order)
[
'article',
'.content',
'.post-content',
'.entry-content',
'main',
'body'
]

Custom Selectionโ€‹

Specify exactly what content to read:

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
selector: '.blog-post-content',
excludeSelector: '.sidebar, .comments, .ads'
});

Manual Contentโ€‹

Provide content directly:

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
content: 'This specific text will be read aloud.'
});

๐ŸŽจ Styling and Themesโ€‹

Built-in Themesโ€‹

// Light theme (default)
SupernalTTS.init({
theme: 'light'
});

// Dark theme
SupernalTTS.init({
theme: 'dark'
});

// Auto theme (matches system preference)
SupernalTTS.init({
theme: 'auto'
});

Custom Stylingโ€‹

Override widget styles with CSS:

/* Custom button styling */
.supernal-tts-button {
background: #your-brand-color !important;
border-radius: 50% !important;
}

/* Custom player styling */
.supernal-tts-player {
background: rgba(0, 0, 0, 0.9) !important;
backdrop-filter: blur(10px) !important;
}

/* Hide widget on mobile */
@media (max-width: 768px) {
.supernal-tts-widget {
display: none !important;
}
}

๐ŸŽฎ Interactive Controlsโ€‹

Player Controlsโ€‹

The widget provides a full audio player:

  • Play/Pause - Space bar or click button
  • Progress Bar - Click to seek to position
  • Speed Control - Adjust playback speed
  • Volume Control - Adjust audio volume
  • Close - Hide the player

Keyboard Shortcutsโ€‹

KeyAction
SpacePlay/Pause
โ†Rewind 10 seconds
โ†’Forward 10 seconds
โ†‘Increase speed
โ†“Decrease speed
EscClose player

๐Ÿ“ฑ Mobile Optimizationโ€‹

The widget is fully responsive and mobile-friendly:

SupernalTTS.init({
// Mobile-specific settings
position: 'bottom-center', // Better for mobile
size: 'large', // Easier to tap
showProgress: false, // Less clutter

// Mobile detection
mobileOnly: false, // Show on mobile only
desktopOnly: false, // Show on desktop only
});

๐Ÿ”ง Advanced Usageโ€‹

Multiple Widgetsโ€‹

Create multiple widgets for different content areas:

// Main content widget
const mainWidget = SupernalTTS.create({
apiUrl: 'https://tts.supernal.ai',
selector: '.main-content',
position: 'bottom-right'
});

// Sidebar widget
const sidebarWidget = SupernalTTS.create({
apiUrl: 'https://tts.supernal.ai',
selector: '.sidebar-content',
position: 'bottom-left',
voice: 'nova'
});

Dynamic Contentโ€‹

Update widget content dynamically:

const widget = SupernalTTS.create({
apiUrl: 'https://tts.supernal.ai'
});

// Update content when page changes
function updateContent(newContent) {
widget.updateContent(newContent);
}

// Refresh content from DOM
function refreshContent() {
widget.refresh();
}

Event Handlingโ€‹

Listen to widget events:

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',

onReady: () => {
console.log('Widget is ready');
},

onContentLoaded: (text) => {
console.log('Content loaded:', text.length, 'characters');
},

onAudioGenerated: (audioUrl, metadata) => {
console.log('Audio generated:', audioUrl);
console.log('Duration:', metadata.duration, 'seconds');
},

onPlay: (position) => {
console.log('Playing from position:', position);
},

onProgress: (position, duration) => {
console.log('Progress:', position, '/', duration);
},

onEnd: () => {
console.log('Playback finished');
},

onError: (error) => {
console.error('Widget error:', error);
}
});

๐Ÿ”’ Security Considerationsโ€‹

CORS Configurationโ€‹

Ensure your API allows requests from your domain:

# In your .env file
ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

Content Security Policyโ€‹

If using CSP, allow the widget resources:

<meta http-equiv="Content-Security-Policy"
content="script-src 'self' https://tts.supernal.ai;
media-src 'self' https://tts.supernal.ai;">

API Key Securityโ€‹

Never expose API keys in client-side code:

// โŒ DON'T DO THIS
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
apiKey: 'sk-tts-your-secret-key' // Exposed to users!
});

// โœ… DO THIS - Use server-side proxy
SupernalTTS.init({
apiUrl: 'https://yourdomain.com/api/tts-proxy' // Your secure endpoint
});

๐Ÿš€ Production Deploymentโ€‹

CDN Hostingโ€‹

Host the widget on a CDN for better performance:

<script src="https://cdn.yourdomain.com/supernal-tts-widget.min.js"></script>

Lazy Loadingโ€‹

Load the widget only when needed:

// Load widget when user interacts
document.addEventListener('click', loadWidget, { once: true });

function loadWidget() {
const script = document.createElement('script');
script.src = 'https://tts.supernal.ai/widget.js';
script.onload = () => {
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai'
});
};
document.head.appendChild(script);
}

Performance Optimizationโ€‹

SupernalTTS.init({
// Optimize for performance
enableCache: true, // Use cached audio
preload: 'metadata', // Preload audio metadata only
quality: 'standard', // Use standard quality for faster generation

// Reduce network requests
batchRequests: true, // Batch multiple requests
debounceMs: 300, // Debounce content changes
});

๐Ÿ› Troubleshootingโ€‹

Common Issuesโ€‹

Widget not appearing:

// Check console for errors
console.log('SupernalTTS available:', typeof SupernalTTS !== 'undefined');

// Verify API connection
fetch('https://tts.supernal.ai/health')
.then(r => r.json())
.then(console.log);

Audio not playing:

// Check browser audio permissions
navigator.permissions.query({name: 'microphone'})
.then(result => console.log('Audio permission:', result.state));

// Test with mock provider
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
provider: 'mock' // Should always work
});

Content not detected:

// Debug content selection
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
debug: true, // Enable debug logging
onContentLoaded: (text) => {
console.log('Detected content:', text);
}
});

Debug Modeโ€‹

Enable detailed logging:

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
debug: true,
logLevel: 'verbose' // verbose, info, warn, error
});

๐Ÿ“š Examplesโ€‹

Blog Integrationโ€‹

<!DOCTYPE html>
<html>
<head>
<title>My Blog</title>
</head>
<body>
<article class="blog-post">
<h1>My Blog Post Title</h1>
<div class="post-content">
<p>This is the content that will be read aloud...</p>
</div>
<aside class="sidebar no-audio">
This sidebar content will be excluded.
</aside>
</article>

<script src="https://tts.supernal.ai/widget.js"></script>
<script>
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
selector: '.post-content',
excludeSelector: '.no-audio',
provider: 'openai',
voice: 'fable'
});
</script>
</body>
</html>

E-learning Platformโ€‹

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
selector: '.lesson-content',
provider: 'cartesia', // Low latency for interactive content
voice: 'confident-british-man',
speed: 0.9, // Slightly slower for learning

onEnd: () => {
// Mark lesson as completed
markLessonComplete();
}
});

Accessibility Enhancementโ€‹

SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',

// Accessibility features
enableKeyboard: true,
showProgress: true,
highContrast: true,

// Screen reader friendly
ariaLabels: {
playButton: 'Play article audio',
pauseButton: 'Pause article audio',
progressBar: 'Audio playback progress'
}
});

For more examples and advanced configurations, see the Examples section.