๐ฆ Installation
Add voice to your website in 2 minutes. Choose the method that works best for you.
โก Method 1: Gtag-Style (Recommended)โ
Perfect for: Everyone! Works with plain HTML, React, Vue, Next.js, anything.
Why this way?
- โ No bundler needed
- โ No npm install required
- โ Always gets latest version from CDN
- โ Works everywhere
- โ Setup in 60 seconds
HTML / Plain Sitesโ
index.html
<!DOCTYPE html>
<html>
<head>
<!-- TTS Widget CSS -->
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css">
</head>
<body>
<!-- Your content -->
<article class="supernal-tts-widget" data-text="This text will have voice!">
<h1>My Article</h1>
<p>This text will have voice!</p>
</article>
<!-- Load Widget -->
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"></script>
<script>
window.SupernalTTS.init({
apiKey: 'YOUR_API_KEY' // Get free key at tts.supernal.ai
});
</script>
</body>
</html>
Next.js / Reactโ
app/layout.tsx
import Script from 'next/script';
export default function RootLayout({ children }) {
return (
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css" />
</head>
<body>
{children}
<Script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js" strategy="afterInteractive" />
<Script id="tts-init" strategy="afterInteractive">
{`
window.SupernalTTS && window.SupernalTTS.init({
apiKey: '${process.env.NEXT_PUBLIC_TTS_API_KEY}'
});
`}
</Script>
</body>
</html>
);
}
Then in any component:
components/BlogPost.tsx
export default function BlogPost({ content }) {
return (
<article className="supernal-tts-widget" data-text={content}>
{content}
</article>
);
}
Done! ๐ The widget automatically finds all .supernal-tts-widget elements.
๐ฆ Method 2: NPM Packageโ
Perfect for: Projects with build tools, TypeScript projects
Why this way?
- โ Version locked in package.json
- โ Works offline
- โ Full TypeScript support
- โ No external CDN dependency
Installโ
npm install @supernal/tts-widget
Useโ
app/layout.tsx
import { SupernalTTS } from '@supernal/tts-widget';
import '@supernal/tts-widget/widget.css';
// Initialize once
useEffect(() => {
SupernalTTS.init({
apiKey: process.env.NEXT_PUBLIC_TTS_API_KEY
});
}, []);
Then use the same className approach:
<div className="supernal-tts-widget" data-text="Content">
Content
</div>
โ๏ธ Method 3: React Componentโ
Perfect for: React purists who prefer component-based APIs
npm install @supernal/tts-widget
app/layout.tsx
import { TTSInitializer } from '@supernal/tts-widget/react';
import '@supernal/tts-widget/widget.css';
export default function App() {
return (
<>
<TTSInitializer
apiKey={process.env.NEXT_PUBLIC_TTS_API_KEY}
mode="bundled"
/>
<YourContent />
</>
);
}
๐ฏ Quick Comparisonโ
| Feature | Gtag-Style | NPM Package | React Component |
|---|---|---|---|
| Setup Time | 30 seconds | 2 minutes | 3 minutes |
| Bundler Needed | โ No | โ Yes | โ Yes |
| TypeScript | โ | โ | โ |
| Works Offline | โ | โ | โ |
| Auto-Updates | โ | โ | โ |
| Simplicity | โญโญโญโญโญ | โญโญโญโญ | โญโญโญ |
๐ Get Your API Keyโ
- Visit https://www.tts.supernal.ai
- Sign up (free!)
- Copy your API key
- Add it to your code or
.envfile:
.env.local
NEXT_PUBLIC_TTS_API_KEY=your_key_here
โ๏ธ Configuration Optionsโ
All methods support the same options:
window.SupernalTTS.init({
// Required
apiKey: 'YOUR_KEY',
// Optional (smart defaults)
apiUrl: 'https://www.tts.supernal.ai', // API endpoint
provider: 'openai', // TTS provider
voice: 'alloy', // Default voice
speed: 1.0, // Speed (0.25-4.0)
clientSideSpeed: true, // Browser speed (saves $$!)
showBranding: true, // "Powered by Supernal"
devMode: false // Debug logging
});
Per-Widget Optionsโ
<div class="supernal-tts-widget"
data-text="Article content"
data-voice="nova" <!-- Custom voice -->
data-voices="alloy,echo,fable" <!-- Voice selector -->
data-enable-speed="true" <!-- Speed control -->
data-enable-progress="true"> <!-- Progress bar -->
Article content
</div>
๐จ Available Voicesโ
OpenAIโ
- alloy - Neutral, balanced
- echo - Clear, friendly
- fable - Warm, storytelling
- nova - Professional
- shimmer - Bright, energetic
- onyx - Deep, resonant
๐ฐ Cost Savings Tipโ
Use clientSideSpeed: true (default) to let the browser adjust playback speed. This saves you from regenerating audio at different speeds!
window.SupernalTTS.init({
apiKey: 'YOUR_KEY',
clientSideSpeed: true // โ
FREE speed adjustment
});
๐ Next Stepsโ
- Widget Guide - Advanced usage
- API Reference - Complete API docs
- Examples - Code examples
- Live Demo - Try it now
๐ Need Help?โ
- Issues: GitHub
- Email: support@supernal.ai
- Docs: tts.supernal.ai