JSPM – supernal-tts-widget@1.0.4

Package Exports

supernal-tts-widget
supernal-tts-widget/dist/widget.css
supernal-tts-widget/dist/widget.js
supernal-tts-widget/widget.css
supernal-tts-widget/widget.js

Readme

Embeddable Text-to-Speech widget for blogs and websites.

Installation

npm install supernal-tts-widget

Quick 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
});

<!-- 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.json

Build Process

Build the widget:
```
npm run build
```
This runs:
- tsc - Compiles TypeScript to JavaScript
- esbuild - Bundles and minifies to a single IIFE file
- cp - Copies CSS to dist
From monorepo root:
```
npm run build:widget
```

Docs 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-widget in docs-site/package.json copies built files to static/
Component: TTSWidget in docs-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.ts or src/widget.css
Run npm run build (or npm run dev for 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

Integration

See the main README and docs-site for integration examples.

supernal-tts-widget