In this tutorial, you'll learn how to respond to hotwords in voice data using AssemblyAI's Universal-Streaming Speech-to-Text API with direct WebSocket connections in Go.
If you've ever wanted to create a personal AI assistant like Siri or Alexa, the first step is to figure out how to trigger the AI using a specific word or phrase (also known as a hotword). All of the prevalent AI systems use a similar approach; for Alexa, the hotword is "Alexa," and for Siri, the hotword is "Hey Siri."
In this tutorial, you'll learn how to implement a hotword detection system using AssemblyAI's Universal-Streaming Speech-to-Text API with direct WebSocket connections. In homage to Iron Man, the assistant in the example is called Jarvis, but you're welcome to name it whatever you want.
Before you start
To complete this tutorial, you'll need:
- Go 1.19 or later installed on your system
- An AssemblyAI account with a valid API key
- A microphone connected to your computer
Set up your environment
You'll use the Go bindings of PortAudio to get raw audio data from your microphone and the Gorilla WebSocket library to connect directly to AssemblyAI's streaming API.
Let's start by creating a new Go project and setting up all of the required dependencies:
If the execution is successful, you should end up with the following directory structure:
Create an AssemblyAI account
To get an API key, you first need to create an AssemblyAI account. Go to the sign-up page and fill out the form to get started.
Next, go to the API Keys page of your Account Dashboard and take note of your API key, as you'll need it in the next step.
Record the raw audio data
With the dependencies set up and the API key in hand, you're ready to start implementing the core logic of your personal AI assistant. The first step is to figure out how to get raw audio data from the microphone.
Create a new recorder.go file in the jarvis directory, import the dependencies, and define a new recorder struct:
The recorder struct will hold a reference to the input stream and read data from that stream via the in field of the struct.
Use the following code to configure a newRecorder function to create and initialize a new recorder struct:
This function takes in the required sample rate and frames per buffer to configure PortAudio, opens the default audio input device attached to your computer, and returns a pointer to a new recorder struct.
Next, define a few methods on the recorder struct pointer that you'll use in the next step:
The Read method reads data from the input stream, writes it to a buffer, and then returns that buffer. The Start, Stop, and Close methods call similarly named methods on the stream.
Create a WebSocket client for AssemblyAI
We’ll now connect directly to AssemblyAI's WebSocket endpoint. Create a new client.go file:
Implement the main application logic
Now create the main application file main.go:
Run the application
Let's see the results of your work in action by running the code. Open up the terminal, cd into the project directory, and set up your AssemblyAI API key as an environment variable:
Note: Replace your_api_key_here with your actual AssemblyAI API key.
Finally, run this command:
This will set Jarvis as the hotword, and the code will output "🎯 Hotword detected! I am here!" whenever it detects "Jarvis" in the transcribed speech.
Understanding the code structure
Your final project should have the following structure:
How it works:
- Audio Recording: The recorder.go file handles capturing audio from your microphone using PortAudio
- WebSocket Client: The client.go file manages the direct WebSocket connection to AssemblyAI's streaming API
- Main Logic: The main.go file coordinates everything, sending audio data and processing transcript responses
- Hotword Detection: Simple string matching checks for your chosen hotword in the final transcripts
Key features:
- Real-time transcription: Audio is processed and transcribed in real-time
- Hotword detection: Automatically detects when your chosen word is spoken
- Graceful shutdown: Properly handles termination signals and cleans up resources
- Error handling: Comprehensive error handling for network issues and audio problems
Important considerations
Pricing
- Universal-Streaming: $0.15 per hour (newer model optimized for voice agents)
- Billing is based on total session duration (connection time), not just audio processing time
Language Support
AssemblyAI's Universal-Streaming Speech-to-Text currently supports English only. If you need multilingual support, consider using the pre-recorded transcription API instead.
Performance Tips
- Use audio chunks of ~50ms for optimal latency. Larger chunk sizes are workable, but may result in latency fluctuations.
- Monitor your connection for stability in production environments
- Consider implementing reconnection logic for robust applications
Next steps
Now that you have a working hotword detection system, you can extend it by:
- Adding custom responses: Implement different actions based on detected hotwords
- Adding wake word sensitivity: Implement confidence thresholds to reduce false positives
- Building voice commands: Extend beyond hotwords to full voice command recognition
Conclusion
In this tutorial, you learned how to create a hotword detection application using AssemblyAI's Universal-Streaming Speech-to-Text API with direct WebSocket connections. You saw how PortAudio makes it easy to capture audio from a microphone and how AssemblyAI's powerful speech recognition enables real-time voice interaction.
AssemblyAI's Universal-Streaming Speech-to-Text API provides the foundation for building sophisticated voice applications. Whether you're developing voice assistants, implementing voice commands, or creating accessibility solutions, AssemblyAI's speech recognition capabilities offer the accuracy and performance needed for production applications.
With its industry-leading accuracy and streaming capabilities, AssemblyAI empowers developers to create innovative voice-enabled experiences that feel natural and responsive.
