Skip to main content

🎨 Supernal TTS Widget Guide

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.