🎙️ Supernal TTS Widget

Embeddable JavaScript widget for adding text-to-speech to any website with voice, speed, and provider controls.

✨ Features

• 🎭 Multiple Voices - Male, female, and neutral voice options
• ⚡ Speed Control - 0.5x to 2.0x playback speed
• 🔄 Provider Support - eSpeak (free), OpenAI, and more
• 💾 Smart Caching - Automatic audio caching for performance
• 🎯 Easy Integration - Drop-in widget for any website
• 📱 Responsive - Works on mobile and desktop
• ♿ Accessible - Screen reader friendly
• 🏷️ Built-in Branding - Powered by Supernal Intelligence attribution

🚀 Quick Start

CDN Usage (Recommended)

<!-- Include the widget script -->
<script src="https://unpkg.com/supernal-tts-widget@latest/dist/widget.js"></script>

<!-- Add TTS to any element -->
<div class="tts-widget" data-text="Hello world!">
  This text will be spoken when the play button is clicked.
</div>

<script>
  // Initialize the widget
  const tts = new SupernalTTS({
    apiUrl: 'https://tts.supernal.ai', // Your TTS API endpoint
    provider: 'espeak', // Default provider
    voice: 'en', // Default voice
    speed: 1.0 // Default speed
  });
</script>

NPM Installation

npm install supernal-tts-widget

import SupernalTTS from 'supernal-tts-widget';

const tts = new SupernalTTS({
  apiUrl: 'https://tts.supernal.ai',
  provider: 'espeak',
  voice: 'en',
  speed: 1.0
});

🎛️ Configuration Options

Constructor Options

const tts = new SupernalTTS({
  apiUrl: 'https://tts.supernal.ai',    // TTS API endpoint
  provider: 'espeak',                   // Default provider: 'espeak', 'openai', 'mock'
  voice: 'en',                          // Default voice
  speed: 1.0,                           // Default speed (0.5 - 2.0)
  apiKey: 'your-api-key',               // Optional API key
  cacheExpiry: 7 * 24 * 60 * 60 * 1000, // Cache expiry (7 days)
  showBranding: true                    // Show "Powered by Supernal Intelligence" badge (default: true)
});

HTML Data Attributes

<div class="tts-widget" 
     data-text="Custom text to speak"
     data-voice="en+f3"
     data-provider="espeak"
     data-speed="1.2">
  Display text here
</div>

🎭 Available Voices

eSpeak (Free)

• en - English (Default)
• en+m3 - English Male
• en+f3 - English Female
• en+m1 - English Male (Slow)
• en+f1 - English Female (Slow)

OpenAI (Premium)

• alloy - Neutral, balanced
• echo - Smooth, professional
• fable - Warm, engaging (British accent)
• onyx - Deep, authoritative
• nova - Energetic, youthful
• shimmer - Soft, friendly

⚡ Speed Options

• 0.5 - Very slow
• 0.75 - Slow
• 1.0 - Normal (default)
• 1.25 - Slightly fast
• 1.5 - Fast
• 2.0 - Very fast

🎨 Styling

The widget automatically adds CSS classes for styling:

.tts-widget {
  /* Container styling */
}

.tts-play {
  /* Play button styling */
}

.tts-playing {
  /* Button when audio is playing */
}

.tts-loading {
  /* Button when loading */
}

.tts-error {
  /* Button when error occurs */
}

.supernal-badge {
  /* Branding badge styling */
}

Branding

By default, all widgets display a compact Supernal Intelligence logo that links to www.supernal.ai. This badge:

• Appears adjacent to the play button
• Shows "Powered by Supernal Intelligence" tooltip on hover
• Uses the official Supernal logo from supernal.ai
• Supports dark mode automatically
• Is responsive and accessible

Customizing the branding:

// Show branding (default)
const tts = new SupernalTTS({
  apiUrl: 'https://tts.supernal.ai',
  showBranding: true // or omit this line
});

// Disable branding (paid tiers only)
const tts = new SupernalTTS({
  apiUrl: 'https://tts.supernal.ai',
  showBranding: false // Not recommended for free tier
});

Custom badge styling:

/* Adjust badge size */
.supernal-badge {
  width: 28px;
  height: 28px;
}

/* Change badge colors */
.supernal-badge {
  background: #your-color;
}

.supernal-badge:hover {
  background: #your-hover-color;
}

For more information about branding and watermarking, see BRANDING_AND_WATERMARKING.md.

🎨 Advanced Styling

Manual Widget Creation

// Add widget to specific element
tts.addWidget(document.getElementById('my-element'), 'Text to speak', {
  voice: 'en+f3',
  provider: 'espeak',
  speed: 1.2
});

// Generate audio programmatically
const response = await tts.generateAudio('Hello world', {
  provider: 'espeak',
  voice: 'en',
  speed: 1.0
});

// Play audio directly
await tts.playAudio(response.audioUrl, buttonElement);

Event Handling

// Listen for audio events
document.addEventListener('tts:playing', (event) => {
  console.log('Audio started playing:', event.detail);
});

document.addEventListener('tts:ended', (event) => {
  console.log('Audio finished playing:', event.detail);
});

document.addEventListener('tts:error', (event) => {
  console.error('TTS error:', event.detail);
});

🌐 React Integration

import { useEffect } from 'react';

function TTSComponent({ text, voice = 'en', speed = 1.0 }) {
  useEffect(() => {
    // Load widget script
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/supernal-tts-widget@latest/dist/widget.js';
    script.onload = () => {
      new SupernalTTS({
        apiUrl: 'https://tts.supernal.ai',
        provider: 'espeak',
        voice,
        speed
      });
    };
    document.head.appendChild(script);
    
    return () => {
      document.head.removeChild(script);
    };
  }, [voice, speed]);

  return (
    <div className="tts-widget" data-text={text}>
      {text}
    </div>
  );
}

🔒 API Authentication

For production use, you'll need an API key:

const tts = new SupernalTTS({
  apiUrl: 'https://tts.supernal.ai',
  apiKey: 'sk-tts-your-api-key-here'
});

📊 Providers Comparison

🐛 Troubleshooting

Common Issues

Widget not appearing:

• Ensure the script is loaded before initializing
• Check that elements have the tts-widget class
• Verify the API endpoint is accessible

Audio not playing:

• Check browser console for errors
• Verify API key and permissions
• Ensure HTTPS for production sites

Slow performance:

• Audio is cached automatically
• Consider using faster providers for real-time needs
• Check network connectivity

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📞 Support

• 📧 Email: support@supernal.ai
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

Made with ❤️ by the Supernal TTS Team