@supernal/tts-widget 1.0.3 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GETTING_STARTED.md +256 -0
- package/MIGRATION.md +92 -9
- package/QUICKSTART.md +108 -0
- package/README.md +125 -121
- package/dist/loader.js +21 -21
- package/dist/loader.js.map +3 -3
- package/dist/widget.d.ts.map +1 -1
- package/dist/widget.js +2 -2
- package/dist/widget.js.map +3 -3
- package/examples/blog-post-component.tsx +77 -0
- package/examples/gtag-style-nextjs.tsx +51 -0
- package/examples/vanilla-html.html +72 -0
- package/package.json +5 -2
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# Getting Started with Supernal TTS Widget
|
|
2
|
+
|
|
3
|
+
Add voice to your website in 2 minutes. Works like Google Analytics - just drop in a script tag.
|
|
4
|
+
|
|
5
|
+
## 🚀 Quick Start
|
|
6
|
+
|
|
7
|
+
### Step 1: Get Your API Key
|
|
8
|
+
|
|
9
|
+
Sign up at [https://www.tts.supernal.ai](https://www.tts.supernal.ai) to get your free API key.
|
|
10
|
+
|
|
11
|
+
### Step 2: Add the Scripts
|
|
12
|
+
|
|
13
|
+
#### For Next.js / React
|
|
14
|
+
|
|
15
|
+
In your root `layout.tsx`:
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import Script from 'next/script';
|
|
19
|
+
|
|
20
|
+
export default function RootLayout({ children }) {
|
|
21
|
+
return (
|
|
22
|
+
<html>
|
|
23
|
+
<head>
|
|
24
|
+
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css" />
|
|
25
|
+
</head>
|
|
26
|
+
<body>
|
|
27
|
+
{children}
|
|
28
|
+
<Script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js" strategy="afterInteractive" />
|
|
29
|
+
<Script id="tts-init" strategy="afterInteractive">
|
|
30
|
+
{`
|
|
31
|
+
window.SupernalTTS && window.SupernalTTS.init({
|
|
32
|
+
apiKey: '${process.env.NEXT_PUBLIC_TTS_API_KEY}'
|
|
33
|
+
});
|
|
34
|
+
`}
|
|
35
|
+
</Script>
|
|
36
|
+
</body>
|
|
37
|
+
</html>
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
#### For Plain HTML
|
|
43
|
+
|
|
44
|
+
In your `index.html` or base template:
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<!DOCTYPE html>
|
|
48
|
+
<html>
|
|
49
|
+
<head>
|
|
50
|
+
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css">
|
|
51
|
+
</head>
|
|
52
|
+
<body>
|
|
53
|
+
<!-- Your content -->
|
|
54
|
+
|
|
55
|
+
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"></script>
|
|
56
|
+
<script>
|
|
57
|
+
window.SupernalTTS.init({
|
|
58
|
+
apiKey: 'YOUR_API_KEY'
|
|
59
|
+
});
|
|
60
|
+
</script>
|
|
61
|
+
</body>
|
|
62
|
+
</html>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Step 3: Add TTS to Your Content
|
|
66
|
+
|
|
67
|
+
Just add `class="supernal-tts-widget"` and `data-text="..."` to any element:
|
|
68
|
+
|
|
69
|
+
```html
|
|
70
|
+
<article class="supernal-tts-widget" data-text="This text will be spoken aloud!">
|
|
71
|
+
<h1>My Article</h1>
|
|
72
|
+
<p>This text will be spoken aloud!</p>
|
|
73
|
+
</article>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**That's it!** 🎉
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 📖 Examples
|
|
81
|
+
|
|
82
|
+
### Blog Post Component (React/Next.js)
|
|
83
|
+
|
|
84
|
+
```tsx
|
|
85
|
+
export default function BlogPost({ title, content }) {
|
|
86
|
+
return (
|
|
87
|
+
<article className="supernal-tts-widget" data-text={content}>
|
|
88
|
+
<h1>{title}</h1>
|
|
89
|
+
<div dangerouslySetInnerHTML={{ __html: content }} />
|
|
90
|
+
</article>
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Multiple Articles (HTML)
|
|
96
|
+
|
|
97
|
+
```html
|
|
98
|
+
<!-- Article 1 -->
|
|
99
|
+
<article class="supernal-tts-widget" data-text="First article content">
|
|
100
|
+
<h2>Article 1</h2>
|
|
101
|
+
<p>First article content</p>
|
|
102
|
+
</article>
|
|
103
|
+
|
|
104
|
+
<!-- Article 2 with custom voice -->
|
|
105
|
+
<article class="supernal-tts-widget"
|
|
106
|
+
data-text="Second article content"
|
|
107
|
+
data-voice="nova">
|
|
108
|
+
<h2>Article 2</h2>
|
|
109
|
+
<p>Second article content</p>
|
|
110
|
+
</article>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### With Voice Selection
|
|
114
|
+
|
|
115
|
+
```html
|
|
116
|
+
<article class="supernal-tts-widget"
|
|
117
|
+
data-text="Content here"
|
|
118
|
+
data-voices="alloy,echo,fable,nova,shimmer"
|
|
119
|
+
data-enable-speed="true"
|
|
120
|
+
data-enable-progress="true">
|
|
121
|
+
<p>Content here</p>
|
|
122
|
+
</article>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## ⚙️ Configuration
|
|
128
|
+
|
|
129
|
+
### Global Options (in init)
|
|
130
|
+
|
|
131
|
+
```javascript
|
|
132
|
+
window.SupernalTTS.init({
|
|
133
|
+
// Required
|
|
134
|
+
apiKey: 'YOUR_API_KEY',
|
|
135
|
+
|
|
136
|
+
// Optional (all have smart defaults)
|
|
137
|
+
apiUrl: 'https://www.tts.supernal.ai', // Custom API endpoint
|
|
138
|
+
provider: 'openai', // TTS provider
|
|
139
|
+
voice: 'alloy', // Default voice
|
|
140
|
+
speed: 1.0, // Default speed (0.25-4.0)
|
|
141
|
+
clientSideSpeed: true, // Browser speed adjustment (saves $$)
|
|
142
|
+
showBranding: true, // Show "Powered by Supernal"
|
|
143
|
+
devMode: false // Debug logging
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Per-Widget Options (data attributes)
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<div class="supernal-tts-widget"
|
|
151
|
+
data-text="Text to speak"
|
|
152
|
+
data-voice="nova" <!-- Override default voice -->
|
|
153
|
+
data-provider="openai" <!-- Override provider -->
|
|
154
|
+
data-speed="1.2" <!-- Override speed -->
|
|
155
|
+
data-voices="alloy,echo,nova" <!-- Voice selector -->
|
|
156
|
+
data-enable-speed="true" <!-- Speed slider -->
|
|
157
|
+
data-enable-progress="true"> <!-- Progress bar -->
|
|
158
|
+
Text to speak
|
|
159
|
+
</div>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## 🎨 Available Voices
|
|
165
|
+
|
|
166
|
+
### OpenAI Voices
|
|
167
|
+
- **alloy** - Neutral, balanced
|
|
168
|
+
- **echo** - Clear, friendly
|
|
169
|
+
- **fable** - Warm, storytelling
|
|
170
|
+
- **nova** - Professional, authoritative
|
|
171
|
+
- **shimmer** - Bright, energetic
|
|
172
|
+
- **onyx** - Deep, resonant
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## 🔧 Advanced Usage
|
|
177
|
+
|
|
178
|
+
### Programmatic Control
|
|
179
|
+
|
|
180
|
+
```javascript
|
|
181
|
+
// Get the instance
|
|
182
|
+
const tts = window.SupernalTTS.getInstance();
|
|
183
|
+
|
|
184
|
+
// Add widget to element dynamically
|
|
185
|
+
tts.addWidget(
|
|
186
|
+
document.querySelector('#my-element'),
|
|
187
|
+
'Text to speak',
|
|
188
|
+
{ voice: 'nova', provider: 'openai' }
|
|
189
|
+
);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Zero-Config Auto-Init
|
|
193
|
+
|
|
194
|
+
```html
|
|
195
|
+
<!-- Widget auto-initializes with this config -->
|
|
196
|
+
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"
|
|
197
|
+
data-supernal-tts-auto-init='{"apiKey":"YOUR_KEY"}'></script>
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## 💰 Cost Savings Tip
|
|
203
|
+
|
|
204
|
+
Set `clientSideSpeed: true` (default) to let the browser handle speed adjustments. This saves you from regenerating audio at different speeds!
|
|
205
|
+
|
|
206
|
+
```javascript
|
|
207
|
+
window.SupernalTTS.init({
|
|
208
|
+
apiKey: 'YOUR_KEY',
|
|
209
|
+
clientSideSpeed: true // ✅ Browser adjusts speed (FREE)
|
|
210
|
+
// vs
|
|
211
|
+
// clientSideSpeed: false // ❌ Server regenerates audio (costs $$)
|
|
212
|
+
});
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## 🐛 Troubleshooting
|
|
218
|
+
|
|
219
|
+
### Widget not appearing?
|
|
220
|
+
|
|
221
|
+
1. Check browser console for errors
|
|
222
|
+
2. Verify API key is correct
|
|
223
|
+
3. Make sure `data-text` attribute is set
|
|
224
|
+
4. Ensure widget CSS is loaded
|
|
225
|
+
|
|
226
|
+
### Voice not playing?
|
|
227
|
+
|
|
228
|
+
1. Check API key has credits
|
|
229
|
+
2. Verify API endpoint is reachable
|
|
230
|
+
3. Check browser console for errors
|
|
231
|
+
4. Try a different voice
|
|
232
|
+
|
|
233
|
+
### In Next.js, getting "window is not defined"?
|
|
234
|
+
|
|
235
|
+
Make sure scripts are in `<body>`, not `<head>`, and use `strategy="afterInteractive"`.
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 📚 More Resources
|
|
240
|
+
|
|
241
|
+
- **Examples**: See `examples/` folder for complete examples
|
|
242
|
+
- **Migration Guide**: See `MIGRATION.md` for upgrading from older versions
|
|
243
|
+
- **API Docs**: Visit [https://docs.tts.supernal.ai](https://docs.tts.supernal.ai)
|
|
244
|
+
- **GitHub**: [https://github.com/supernalintelligence/supernal-nova](https://github.com/supernalintelligence/supernal-nova)
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 🆘 Support
|
|
249
|
+
|
|
250
|
+
- **Issues**: [GitHub Issues](https://github.com/supernalintelligence/supernal-nova/issues)
|
|
251
|
+
- **Email**: support@supernal.ai
|
|
252
|
+
- **Docs**: [https://docs.tts.supernal.ai](https://docs.tts.supernal.ai)
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
Happy voice-enabling! 🎙️
|
package/MIGRATION.md
CHANGED
|
@@ -1,15 +1,18 @@
|
|
|
1
|
-
# Migration Guide: v1.
|
|
1
|
+
# Migration Guide: v1.0.x → v1.0.4+
|
|
2
2
|
|
|
3
|
-
## What
|
|
3
|
+
## What's New in v1.0.4?
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
🎯 **Gtag-Style Auto-Scan** - The widget now works like Google Analytics!
|
|
6
|
+
|
|
7
|
+
Just load the script and it automatically finds `.supernal-tts-widget` elements on your page. No React components, no loaders, no bundlers needed.
|
|
6
8
|
|
|
7
9
|
### Key Benefits
|
|
8
10
|
|
|
9
|
-
✅ **
|
|
10
|
-
✅ **
|
|
11
|
-
✅ **
|
|
12
|
-
✅ **
|
|
11
|
+
✅ **Zero JavaScript** - Works with plain HTML, no npm required
|
|
12
|
+
✅ **Auto-discovery** - Automatically scans for TTS elements on page load
|
|
13
|
+
✅ **Framework agnostic** - Works with React, Vue, vanilla HTML, anything
|
|
14
|
+
✅ **Smart defaults** - API URL hardcoded, just provide your API key
|
|
15
|
+
✅ **Backward compatible** - All old approaches still work
|
|
13
16
|
|
|
14
17
|
---
|
|
15
18
|
|
|
@@ -17,11 +20,91 @@ Version 1.3.0 introduces a **Smart Loader** that gives you automatic updates via
|
|
|
17
20
|
|
|
18
21
|
**None!** 🎉
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
All existing code continues to work. The gtag-style approach is just a new, simpler option.
|
|
21
24
|
|
|
22
25
|
---
|
|
23
26
|
|
|
24
|
-
## Recommended
|
|
27
|
+
## Recommended: Migrate to Gtag-Style
|
|
28
|
+
|
|
29
|
+
### Before (Any approach)
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
// React Component
|
|
33
|
+
import { TTSInitializer } from '@supernal/tts-widget/react';
|
|
34
|
+
<TTSInitializer apiUrl="https://www.tts.supernal.ai" apiKey="..." />
|
|
35
|
+
|
|
36
|
+
// OR Vanilla JS
|
|
37
|
+
import { SupernalTTS } from '@supernal/tts-widget';
|
|
38
|
+
SupernalTTS.init({ apiUrl: 'https://www.tts.supernal.ai', apiKey: '...' });
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### After (Gtag-Style - Recommended)
|
|
42
|
+
|
|
43
|
+
**In your root layout (Next.js):**
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
import Script from 'next/script';
|
|
47
|
+
|
|
48
|
+
export default function RootLayout({ children }) {
|
|
49
|
+
return (
|
|
50
|
+
<html>
|
|
51
|
+
<head>
|
|
52
|
+
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css" />
|
|
53
|
+
</head>
|
|
54
|
+
<body>
|
|
55
|
+
{children}
|
|
56
|
+
<Script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js" strategy="afterInteractive" />
|
|
57
|
+
<Script id="tts-init" strategy="afterInteractive">
|
|
58
|
+
{`
|
|
59
|
+
window.SupernalTTS && window.SupernalTTS.init({
|
|
60
|
+
apiKey: '${process.env.NEXT_PUBLIC_TTS_API_KEY}'
|
|
61
|
+
});
|
|
62
|
+
`}
|
|
63
|
+
</Script>
|
|
64
|
+
</body>
|
|
65
|
+
</html>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**In your components:**
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
// Before: Complex React component
|
|
74
|
+
<TTSInitializer ... />
|
|
75
|
+
|
|
76
|
+
// After: Simple className
|
|
77
|
+
<article className="supernal-tts-widget" data-text={content}>
|
|
78
|
+
{content}
|
|
79
|
+
</article>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**For plain HTML:**
|
|
83
|
+
|
|
84
|
+
```html
|
|
85
|
+
<!-- Load once -->
|
|
86
|
+
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"></script>
|
|
87
|
+
<script>
|
|
88
|
+
window.SupernalTTS.init({ apiKey: 'YOUR_KEY' });
|
|
89
|
+
</script>
|
|
90
|
+
|
|
91
|
+
<!-- Use anywhere -->
|
|
92
|
+
<div class="supernal-tts-widget" data-text="Content">Content</div>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Benefits of Gtag-Style
|
|
96
|
+
|
|
97
|
+
- ✅ No CDN loader errors (loads directly from unpkg)
|
|
98
|
+
- ✅ No React component overhead
|
|
99
|
+
- ✅ Works in any environment
|
|
100
|
+
- ✅ Simpler, cleaner code
|
|
101
|
+
- ✅ Same as users are familiar with (gtag pattern)
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Legacy Migration (v1.2.x → v1.3.0)
|
|
106
|
+
|
|
107
|
+
### Smart Loader (Old Approach)
|
|
25
108
|
|
|
26
109
|
### Before (v1.2.x)
|
|
27
110
|
|
package/QUICKSTART.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Supernal TTS Widget - Quick Start
|
|
2
|
+
|
|
3
|
+
## Gtag-Style Usage (Recommended)
|
|
4
|
+
|
|
5
|
+
The simplest way to add TTS to your site - just like Google Analytics:
|
|
6
|
+
|
|
7
|
+
### 1. Add to your HTML/Layout
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<!-- CSS in <head> -->
|
|
11
|
+
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css">
|
|
12
|
+
|
|
13
|
+
<!-- Scripts before </body> -->
|
|
14
|
+
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"></script>
|
|
15
|
+
<script>
|
|
16
|
+
window.SupernalTTS.init({
|
|
17
|
+
apiKey: 'YOUR_API_KEY'
|
|
18
|
+
});
|
|
19
|
+
</script>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### 2. Add TTS to any element
|
|
23
|
+
|
|
24
|
+
```html
|
|
25
|
+
<div class="supernal-tts-widget" data-text="This text will have TTS">
|
|
26
|
+
This text will have TTS
|
|
27
|
+
</div>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**That's it!** The widget automatically scans for `.supernal-tts-widget` elements on page load.
|
|
31
|
+
|
|
32
|
+
## Next.js / React
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import Script from 'next/script';
|
|
36
|
+
|
|
37
|
+
export default function RootLayout({ children }) {
|
|
38
|
+
return (
|
|
39
|
+
<html>
|
|
40
|
+
<head>
|
|
41
|
+
<link rel="stylesheet" href="https://unpkg.com/@supernal/tts-widget@1/dist/widget.css" />
|
|
42
|
+
</head>
|
|
43
|
+
<body>
|
|
44
|
+
{children}
|
|
45
|
+
<Script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js" strategy="afterInteractive" />
|
|
46
|
+
<Script id="tts-init" strategy="afterInteractive">
|
|
47
|
+
{`
|
|
48
|
+
window.SupernalTTS && window.SupernalTTS.init({
|
|
49
|
+
apiKey: '${process.env.NEXT_PUBLIC_TTS_API_KEY}'
|
|
50
|
+
});
|
|
51
|
+
`}
|
|
52
|
+
</Script>
|
|
53
|
+
</body>
|
|
54
|
+
</html>
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Options
|
|
60
|
+
|
|
61
|
+
```javascript
|
|
62
|
+
window.SupernalTTS.init({
|
|
63
|
+
apiKey: 'YOUR_API_KEY', // Required (or use apiUrl for self-hosted)
|
|
64
|
+
apiUrl: 'https://your-api.com', // Optional: custom API endpoint
|
|
65
|
+
provider: 'openai', // Default provider
|
|
66
|
+
voice: 'alloy', // Default voice
|
|
67
|
+
speed: 1.0, // Default speed
|
|
68
|
+
clientSideSpeed: true, // Use browser playback speed (recommended)
|
|
69
|
+
showBranding: true // Show "Powered by Supernal"
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Advanced Usage
|
|
74
|
+
|
|
75
|
+
### Custom voice per widget
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<div class="supernal-tts-widget"
|
|
79
|
+
data-text="Professional narration"
|
|
80
|
+
data-voice="nova"
|
|
81
|
+
data-provider="openai">
|
|
82
|
+
Professional narration
|
|
83
|
+
</div>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Programmatic control
|
|
87
|
+
|
|
88
|
+
```javascript
|
|
89
|
+
// Get instance
|
|
90
|
+
const tts = window.SupernalTTS.getInstance();
|
|
91
|
+
|
|
92
|
+
// Add widget dynamically
|
|
93
|
+
tts.addWidget(element, 'Text to speak', {
|
|
94
|
+
voice: 'alloy',
|
|
95
|
+
provider: 'openai'
|
|
96
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Zero JavaScript Required
|
|
100
|
+
|
|
101
|
+
For static sites, you don't even need to write JavaScript:
|
|
102
|
+
|
|
103
|
+
```html
|
|
104
|
+
<script src="https://unpkg.com/@supernal/tts-widget@1/dist/widget.js"
|
|
105
|
+
data-supernal-tts-auto-init='{"apiKey":"YOUR_KEY"}'></script>
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The widget automatically initializes with the config from the `data-supernal-tts-auto-init` attribute!
|