vue-transcribe

🎙️ vue-transcribe

A lightweight Vue 2 & Vue 3 compatible directive + service bundle for real-time Speech-to-Text via WebSocket — ideal for integrating AWS Transcribe WebSocket service.

✨ Features

• 🎛️ Vue directive for controlling microphone input on text fields
• ⚙️ WebSocket-powered transcription service integration
• 📑 Command vs. Text Generation modes
• 📜 Customizable UI styles and icons
• 🛰️ Global CommandProcessor instance for mapping voice commands to tasks
• 🔐 Directive only activates if service is configured

📦 Installation

npm install vue-transcribe

📖 Exports Overview

Export	Description
TranscribeDirective	Vue directive for attaching transcription behavior to inputs or textareas
TranscribeService	Singleton service managing WebSocket connection and configuration state
CommandProcessor	Global processor for handling custom voice commands mapped to tasks

🚀 Integration Guide

1️⃣ Register the Directive

Vue 3

import { TranscribeDirective } from 'vue-transcribe';
app.directive('transcribe', TranscribeDirective);

Vue 2

import Vue from 'vue';
import { TranscribeDirective } from 'vue-transcribe';
Vue.directive('transcribe', TranscribeDirective);

2️⃣ Configure and Fetch WebSocket URL

The directive will only activate if TranscribeService.getInstance().configured is true. You must set a presigned WebSocket URL before using the directive.

Presigned URLs (like from AWS Transcribe) usually expire every 5 minutes, so you'll need to refresh it periodically. It is up to you to set up the endpoint that will return the presigned URLS using proper AWS credentials.

Example: Fetch URL via Axios from your backend

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

function fetchAndSetWebSocketURL() {
  axios.get('/api/transcribe-url')
    .then(response => {
      const url = response.data.url;
      TranscribeService.getInstance().setURL(url);
    })
    .catch(err => console.error('Failed to fetch WebSocket URL:', err));
}

// Set initial URL
fetchAndSetWebSocketURL();

// Refresh URL every 5 minutes
setInterval(fetchAndSetWebSocketURL, 5 * 60 * 1000);

3️⃣ Setup CommandProcessor (if using Command Mode)

For command mode, configure the global command map:

import { CommandProcessor } from 'vue-transcribe';

CommandProcessor.commandMap = [
  {
    command: 'say Hello',
    task: () => alert('Hello!')
  },
  {
    command: 'clear Input',
    task: () => document.querySelector('#myInput').value = ''
  }
];

Note: Command map must be an array of objects with exactly:

• command (string)
• task (function)

4️⃣ Apply the Directive

Apply v-transcribe to the parent element of your target input or textarea.

// Example options

const directiveOptions = {
  style: {
    mic: { backgroundColor: 'red' },
    spinner: { color: 'blue' },
    vector: { margin: '0 auto' },
    container: { padding: '8px' }
  },
  languageCode: 'en-US',
  type: 'generate',
  maxRecordingTime: 60,
  append: true,
  micIconClass: ['fa', 'fa-microphone'],
  listeningSVG: 'https://cdn.com/listening.svg'
};

<div v-transcribe="directiveOptions">
  <input type="text" id="myInput" />
</div>

🎛️ Directive Binding Options

Option	Type	Description
style	Object	Styling options for mic, spinner, vector, and container elements
languageCode	String	BCP-47 language code (e.g. en-US)
type	String (generate | command)	generate transcribes to text, command runs a mapped command
maxRecordingTime	Number (milliseconds)	Max allowed recording time per session. Auto-stops.
append	Boolean	Whether to append to or replace existing text in inputs
micIconClass	Array of Strings	CSS class names for the mic button
listeningSVG	String (absolute URL)	URL to an SVG animation shown while listening

🎨 Styling Object Structure

The style binding expects an object with the following structure:

{
  mic: { backgroundColor: 'red', borderRadius: '50%' },
  spinner: { color: 'blue' },
  vector: { width: '20px', height: '20px' },
  container: { padding: '10px', display: 'flex' }
}

Each sub-property is a style object applied to its respective control element.

🎙️ Transcription Modes

Type	Behavior
generate	Converts spoken input to text and injects it into the input/textarea
command	Matches spoken phrases against CommandProcessor.commandMap and runs associated tasks

✅ Notes & Requirements

• WebSocket URL must be refreshed every 5 minutes when using AWS Transcribe presigned URLs. Read more.
• TranscribeService.getInstance().configured must be true for the directive to be visible and functional.
• The CommandProcessor.commandMap must be an array of { command: string, task: function } objects.
• The directive should be attached to the container element wrapping your input/textarea.
• The TranscribeService follows a singleton pattern, accessible via TranscribeService.getInstance().

📦 Example Full Usage

import { TranscribeDirective, TranscribeService, CommandProcessor } from 'vue-transcribe';
import axios from 'axios';
import Vue from 'vue';

Vue.directive('transcribe', TranscribeDirective);

// Configure CommandProcessor
CommandProcessor.commandMap = [
  { command: 'hello', task: () => console.log('Hi!') },
  ...
];

// Set and refresh WebSocket URL
function setTranscribeURL() {
  axios.get('/api/transcribe-url').then(res => {
    TranscribeService.getInstance().setURL(res.data.url);
  });
}
setTranscribeURL();
setInterval(setTranscribeURL, 5 * 60 * 1000);

TranscribeService.getInstance().configured = process.env.NODE_ENV !== 'development';

📦 References for constructing an AWS presigned URL

• Javascript
• Python

📑 License

ISC

🙌 Contributing

MRs welcome — please follow existing code conventions and document any new features.

👤 Author

Charles Ugbana