Voice-Activation Tutorial
Learn how to build an MentraOS App that:- Listens for live speech transcriptions provided by the system.
- Detects a custom activation phrase (for example “computer”).
- Executes an action—in this guide we’ll simply display a text overlay.
Looking for a broader introduction? Start with the Quickstart guide. This page focuses specifically on the app code that handles transcriptions.
Prerequisites
- MentraOS SDK ≥
0.13.0installed in your project. - A local development environment configured as described in Getting Started.
- MICROPHONE permission added to your App in the Developer Console so the transcription stream is available. See Permissions.
1 - Set up the Project
Create a new project—or reuse an existing one—and install the SDK:src/index.ts.
2 - Write the App Code
The full source code is shown first, followed by a step-by-step explanation.src/index.ts
What Does Each Part Do?
| # | Code | Purpose |
|---|---|---|
| 1️⃣ | session.events.onTranscription | Subscribes to real-time speech data. The callback fires many times per utterance—both interim and final chunks. |
| 2️⃣ | if (!data.isFinal) return; | Filters out interim chunks so we only process complete sentences. |
| 3️⃣ | spokenText.toLowerCase().trim() | Normalizes the text to improve keyword matching. |
| 4️⃣ | if (spokenText.includes(...)) | Simple string containment check for the activation phrase. |
| 5️⃣ | session.layouts.showTextWall(...) | Shows a full-screen text overlay on the glasses. Replace with your own logic. |
| 6️⃣ | this.addCleanupHandler(unsubscribe) | Ensures the transcription listener is removed when the session disconnects, preventing memory leaks. |
3 - Run the App
-
Add the required environment variables in
.env: -
Start the development server:
- Expose the port with ngrok (or your tunnel of choice) so MentraOS on your phone can reach it, then restart the App inside MentraOS.
Best Practices
- Keep the activation phrase natural – Short, memorable words work best.
- Provide user feedback – After detecting the phrase, give immediate visual or auditory confirmation.
- Avoid hard-coding – Store configurable keywords in Settings so users can change them.
- Review permissions – Request only the data your App genuinely needs. See Permissions.

