supernal-tts-widget
v1.1.1
Published
Embeddable TTS widget for blogs and websites
Maintainers
ianderringtonReadme
supernal-tts-widget
Embeddable Text-to-Speech widget for blogs and websites.
Installation
npm install supernal-tts-widgetQuick Start
React/Next.js
import { useEffect } from 'react';
import 'supernal-tts-widget/widget.css';
export default function MyComponent() {
useEffect(() => {
import('supernal-tts-widget/widget.js')
.then(({ SupernalTTS }) => {
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
provider: 'openai',
voice: 'alloy'
});
});
}, []);
return (
<div className="tts-widget" data-text="This text will be read aloud!">
<p>This text will be read aloud!</p>
</div>
);
}HTML/Static Sites
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/supernal-tts-widget/widget.css">
</head>
<body>
<div class="tts-widget" data-text="This content can be read aloud!">
<p>This content can be read aloud!</p>
</div>
<script type="module">
import { SupernalTTS } from 'https://unpkg.com/supernal-tts-widget/widget.js';
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai',
provider: 'openai',
voice: 'alloy'
});
</script>
</body>
</html>Configuration
SupernalTTS.init({
apiUrl: 'https://tts.supernal.ai', // Required: API endpoint
provider: 'openai', // Optional: TTS provider (default: 'openai')
voice: 'alloy', // Optional: Voice selection
speed: 1.0, // Optional: Playback speed (0.25-4.0)
apiKey: 'your-api-key', // Optional: For authenticated requests
devMode: false, // Optional: Enable dev mode features
clientSideSpeed: true // Optional: Use browser pitch-preserving time-stretching (default: true)
// Saves generation costs! Set to false for server-side regeneration
});Client-Side Speed Adjustment
By default (clientSideSpeed: true), the widget uses the browser's native preservesPitch feature with playbackRate to adjust speed instantly without regenerating audio. This:
- ✅ Saves significant costs - no need to generate audio at multiple speeds
- ✅ Instant speed changes - no loading/regeneration delay
- ✅ Maintains pitch quality - uses browser's time-stretching algorithm
- ✅ Works with already-cached audio
Set clientSideSpeed: false if you need server-side speed generation with provider-specific pitch correction (more expensive but may have slightly different quality characteristics for extreme speed changes).
Widget Data Attributes
<!-- Custom voice per widget -->
<div class="tts-widget"
data-text="Professional voice example"
data-voice="coral"
data-provider="openai">
Professional voice example
</div>
<!-- Custom speed -->
<div class="tts-widget"
data-text="Fast speech"
data-speed="1.5">
Fast speech
</div>Available Voices
OpenAI
alloy,echo,fable,onyx,nova,shimmer,coral,sage,verse
Mock (Testing)
mock-voice-1,mock-voice-2,mock-voice-3
Documentation
Full documentation: https://tts.supernal.ai
Development
This is the SOURCE OF TRUTH for the Supernal TTS widget. All changes should be made here.
Directory Structure
packages/supernal-tts-widget/
├── src/
│ ├── widget.ts # TypeScript source (EDIT THIS)
│ └── widget.css # Styles
├── dist/ # Built output (DO NOT EDIT)
│ ├── widget.js # Bundled JavaScript
│ ├── widget.css # Copied styles
│ └── widget.d.ts # TypeScript declarations
├── package.json
└── tsconfig.jsonBuild Process
Build the widget:
npm run buildThis runs:
tsc- Compiles TypeScript to JavaScriptesbuild- Bundles and minifies to a single IIFE filecp- Copies CSS to dist
From monorepo root:
npm run build:widgetDocs site automatically copies widget on build/start:
cd docs-site npm run copy-widget # or `npm start` / `npm run build`
Features
- TypeScript: Proper typing and IDE support
- Dev Mode Cache Clear: Red button in dev mode to clear local cache
- Absolute URLs: Handles both relative and absolute audio URLs
- Branding: Optional Supernal AI badge
- Responsive: Mobile-friendly design
- Dark Mode: Automatic dark mode support
Usage in Docs Site
The docs-site imports the widget from this package via:
- Build script:
copy-widgetindocs-site/package.jsoncopies built files tostatic/ - Component:
TTSWidgetindocs-site/src/components/TTSWidget/loads from/js/widget.js
DO NOT edit files in docs-site/static/js/ or docs-site/static/css/ directly!
Making Changes
- Edit
src/widget.tsorsrc/widget.css - Run
npm run build(ornpm run devfor watch mode) - Test in docs-site:
cd ../../../docs-site && npm start - The widget will be automatically copied and loaded
Publishing
When ready to publish to npm:
npm version patch|minor|major
npm publish