Developer's Guide to Voice-to-Text on Websites

Welcome to the Whisperbro developer's guide. We're excited to help you integrate real-time speech-to-text functionality into your website with just a few lines of code.

This guide will walk you through setting up the widget, from a simple "hello world" example to more advanced use cases. Let's get started!

✨ Features

• Real-Time Transcription: Get live feedback as you speak and a final, polished transcript when you're done.
• Easy Integration: The widget now renders its own controls. Just point it to a container element.
• Self-Contained UI: The widget injects its own CSS and creates the start, stop, and loading buttons for a consistent look and feel.
• Audio Visualization: An optional visualizer provides real-time feedback that the microphone is picking up audio.
• Flexible Control: Use our simple API to start and stop recordings programmatically, giving you complete control over the user experience.
• Customizable Callbacks: Hook into the recording lifecycle to trigger custom functionality when recording starts, stops, or a transcript is received.

🚀 Getting Started

Integrating the Whisperbro widget is a two-step process: add the script to your page and then initialize it.

1. Include the Script

First, add the whisperbro-widget.js script to your HTML file, preferably right before the closing </body> tag.

<!-- Your website's content -->

<script src="https://whisperbro.com/app/widgets/whisperbro-v1.js"></script>
</body>
</html>

2. Set Up Your HTML

Next, add a container element where the widget will render its buttons. You can also add optional elements for the visualizer and transcript.

<!-- 1. A container for the widget's buttons -->
<div id="recording-controls"></div>

<!-- 2. Optional: A place for the visualizer to render -->
<div id="audio-visualizer"></div>

<!-- 3. Optional: A place to show the final transcript -->
<h2>Transcript:</h2>
<p id="transcript-output"></p>

3. Initialize the Widget

Finally, initialize the widget by calling Whisperbro.init(). The only required option is containerId.

<script>
    document.addEventListener('DOMContentLoaded', () => {
        Whisperbro.init({
            containerId: 'recording-controls',
            visualizerId: 'audio-visualizer',
            apiKey: "<YOUR_API_KEY>",
            onTranscription: (text) => {
                // We got the final transcript! Let's display it.
                document.getElementById('transcript-output').textContent = text;
                console.log('Final Transcript:', text);
            }
        });
    });
</script>

And that's it! The widget will automatically render the recording controls inside the recording-controls div. When a user clicks the button, recording will start, the UI will update, the visualizer will appear, and the final transcript will be delivered to your callback.

⚙️ Configuration Options

You can customize the widget's behavior by passing an options object to Whisperbro.init().

Option	Type	Required	Description
containerId	string	No	The ID of the HTML element where the widget's controls will be rendered.
visualizerId	string	No	The ID of the container where the audio visualizer will be rendered.
onTranscription	func	No	Callback function that receives the final transcript as a string. (text) => {}
onRecordingStarted	func	No	Callback invoked when the recording starts successfully.
onRecordingFinished	func	No	Callback invoked when recording stops and transcription is in progress.
onPermissionDenied	func	No	Invoked when the user does not grant microphone permission.
onError	func	No	A callback to handle any errors that occur. (error) => {}

🕹️ Advanced Usage: Programmatic Control

While the built-in buttons are convenient, you might want more control. The programmatic API allows you to build custom UI, implement keyboard shortcuts, or create automated voice-driven workflows. The widget's own buttons will even update their state automatically when you use the API.

API Methods & Properties

• Whisperbro.startRecording(): Asynchronously starts the recording process.
• Whisperbro.stopRecording(): Asynchronously stops the recording and begins transcription. It also releases the microphone.
• Whisperbro.disconnect(): Asynchronously stops recording, releases the microphone, and disconnects from the server.
• Whisperbro.isRecording (getter): Returns true if recording is currently active, and false otherwise.

Example: Custom Controls and Keyboard Shortcuts

In this example, we'll add a keyboard shortcut (pressing the space bar) to toggle recording. The widget's buttons will automatically reflect the recording state.

<!-- The widget will render its buttons here -->
<div id="recording-controls"></div>

<p>Status: <span id="status">Idle</span> (or press Spacebar to record)</p>

document.addEventListener('DOMContentLoaded', () => {
    Whisperbro.init({
        containerId: 'recording-controls',
        onRecordingStarted: () => {
            document.getElementById('status').textContent = 'Recording...';
        },
        onRecordingFinished: () => {
            document.getElementById('status').textContent = 'Transcribing...';
        },
        onTranscription: (text) => {
            console.log("Got transcript:", text);
        }
    });

    // Keyboard shortcut (Spacebar)
    document.addEventListener('keydown', (event) => {
        if (event.code === 'Space' && !event.repeat) {
            // Prevent typing a space in a text field
            event.preventDefault();

            if (Whisperbro.isRecording) {
                Whisperbro.stopRecording();
            } else {
                Whisperbro.startRecording();
            }
        }
    });
});

This example shows the flexibility you have. You can trigger startRecording() and stopRecording() from anywhere in your code, giving you the power to build truly custom voice experiences.

Happy coding! We can't wait to see what you build with Whisperbro.

Please let us know if you have any feedback or need additional features.