Skip to main content

๐Ÿ“ฆ Installation

Add voice to your website in 2 minutes. Choose the method that works best for you.

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โ€‹

FeatureGtag-StyleNPM PackageReact Component
Setup Time30 seconds2 minutes3 minutes
Bundler NeededโŒ Noโœ… Yesโœ… Yes
TypeScriptโŒโœ…โœ…
Works OfflineโŒโœ…โœ…
Auto-Updatesโœ…โŒโŒ
Simplicityโญโญโญโญโญโญโญโญโญโญโญโญ

๐Ÿ”‘ Get Your API Keyโ€‹

  1. Visit https://www.tts.supernal.ai
  2. Sign up (free!)
  3. Copy your API key
  4. Add it to your code or .env file:
.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โ€‹


๐Ÿ†˜ Need Help?โ€‹