vue-transcribe

vue-transcribe

A lightweight Vue 2 & Vue 3 compatible directive + service bundle for adding a near real-time speech-to-text transcription and voice command execution using WebSocket-based services like Amazon Transcribe.

You can:

• Use a drop-in <VoiceButton /> for command-style or text-generation mic capture
• Control everything via a lightweight API

📦 Installation

npm install vue-transcribe

Requirements

This package requires material design icons to function properly. It is expected that you have this setup in the consuming project. If you don't have it setup yet, do the following:

• Install @mdi/font:

npm install @mdi/font

• Import the css as a global style. (typically within main.js):

import '@mdi/font/css/materialdesignicons.css';

// or

import '@mdi/font/css/materialdesignicons.min.css';

🔧 Setup

Step 1 – Provide the Presigned URL

You must generate and provide a presigned WebSocket URL to start any transcription. Example (using AWS Transcribe):

import { TranscribeAPI } from 'vue-transcribe';
import axios from 'axios';

async function configure() {
  const { data } = await axios.get('/api/transcribe-url'); // Replace with the presignedURL generation endpoint in your setup
  TranscribeAPI.setURL(data.url);
  TranscribeAPI.setConfigured(true); // ✅ Don't forget this
}

// AWS Transcribe presigned URLs expire every 5 minutes
configure();
setInterval(configure, 5 * 60 * 1000);

⚠️ setConfigured(true) is required to indicate that a valid transcription URL is available. Without this, the component will not render. This can be used to filter envs as well. e.g TranscribeAPI.setConfigured(process.env.NODE_ENV !== 'development)

Step 2 - Use <VoiceButton /> Component

This button provides a quick way to interact with the API, and can be used in 2 modes - generate and command

Text Generation Mode

Text generation mode is all about speech to text generation. This means that there has to be an input or textarea field you wish to populate with texts when you speak. The VoiceButton component relies on an enclosing parent HTMLElement to be able to find the input element of interest. With that, you should have the input or textarea of interest, together with the <VoiceButton />, enclosed within any parent HTMLElement. The order and styling is up to you:

<template>
  <div class="input-voice-container">
    <textarea class="input"></textarea>

    <VoiceButton
      :mode="generate"
      :disabled="isDisabled"
      language-code="en-US"
      theme="primary-transparent"
      microphone="solid"
      max-recording-time="10000"
    />
  </div>
</template>

<script>
import { VoiceButton } from 'vue-transcribe';

export default {
  components: {
    VoiceButton
  },

  data() {
    return {
      isDisabled: false
    }
  }
};
</script>

Command Mode

In command mode, your app can execute tasks based on matched phrases. You have to setup the command mapping first of all:

TranscribeAPI.setCommandMap([
  {
    command: 'clear input',
    task: () => {
      const el = document.querySelector('input');
      if (el) el.value = '';
    }
  },
  {
    command: 'submit form',
    task: () => {
      document.querySelector('form')?.submit();
    }
  },
  {
    command: 'shut down app',
    task: () => {
      this.application.shutdown(); // assumption
    }
  }
]);

Once the command mapping is configured, use the component in your templates like so:

<template>
  <VoiceButton
    :mode="command"
    :disabled="isDisabled"
    language-code="en-US"
    theme="primary"
    microphone="solid"
    max-recording-time="10000"
  />
</template>

<script>
import { VoiceButton } from 'vue-transcribe';

export default {
  components: {
    VoiceButton
  },

  data() {
    return {
      isDisabled: false
    }
  }
};
</script>

VoiceButton Props

Prop	Type	Required	Description
mode	string	✅	Transcription mode - text-generation or custom commands. generate / command
language-code	string	❌	BCP-47 language code (default en-US)
max-recording-time	number	❌	Max mic capture time in ms (default: 5000)
microphone	string	❌	Microphone's style (solid or outline). default solid
disabled	boolean	❌	If button should be disabled. default false
theme	string	❌	Predefined themes that can be applied - primary (default), secondary, danger. Append -transparent to any of the themes to get a button with transparent background
expanded	boolean	❌	To show or hide label. default is false.
append	boolean	❌	Whether to replace or append to existing text input. For generate mode
trim-punctuation	boolean	❌	Whether to remove trailing punctuations from transcript. For generate mode

TranscribeAPI

Method	Description
setURL(url: string)	Sets the active transcription WebSocket URL
setConfigured(boolean)	Enables/disables voice capture
isConfigured()	Returns current config state
setCommandMap(array)	Registers global voice commands
on(event, callback)	Subscribe to 'error' event
off(event, callback)	Unsubscribe from events

Example: Handling Errors

TranscribeAPI.on('error', (error) => {
  console.error('Transcribe error:', error);
});


// Error event structure
{
  code: ErrorCodes,
  message: String,
  details?: ErrorEvent
}

// enum ErrorCodes {
//     WS_CONNECTION_FAILED: 'WS_CONNECTION_FAILED',
//     AUDIO_CAPTURE_ERROR: 'AUDIO_CAPTURE_ERROR',
//     NO_MATCHING_COMMAND: 'NO_MATCHING_COMMAND'
// };


// To unsubscribe
TranscribeAPI.off('error', callback);

Example Setup (Vue 2)

import Vue from 'vue';
import {
  VoiceButton
  TranscribeAPI
} from 'vue-transcribe';
import axios from 'axios';

TranscribeAPI.setCommandMap([
  {
    command: 'clear input',
    task: () => {
      const el = document.querySelector('input');
      if (el) el.value = '';
    }
  },
]);

function setURL() {
  axios.get('/api/transcribe-url') // You are to set up this endpoint
    .then(res => TranscribeAPI.setURL(res.data.url));
}

setURL();
setInterval(setURL, 5 * 60 * 1000);


TranscribeAPI.on('error', err => {
  console.error('Transcription error:', err);
  // You can trigger a toast, log or do anything of choice here
});

TranscribeAPI.setConfigured(true)

Vue.component('VoiceButton', VoiceButton); // Global registration

Requirements & Notes

• You must manually refresh AWS presigned URLs every 5 minutes
• VoiceButton only renders when: TranscribeAPI.isConfigured() is true
• Command Map must be an array of { command, task }
• Use TranscribeAPI.on('error', cb) to listen for transcription/command errors

References

• AWS Presigned URL Guide (JavaScript)
• AWS Presigned URL Guide (Python)
• AWS Transcribe Streaming Docs

License

ISC

Contributing

Merge Requests welcome! Please follow existing code style and include docs for any new features or events.

Author

Charles Ugbana