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 into Vue apps.

✨ Features

• 🗣️ Vue directive for microphone control on inputs and textareas
• 🔌 WebSocket-powered transcription using presigned URLs (e.g., AWS Transcribe)
• 🧠 Two modes: freeform text (generate) or mapped voice commands (command)
• 🎨 Customizable UI for mic buttons, spinners, and animations
• 🔁 Auto-refresh support for expiring presigned URLs (e.g., every 5 mins for AWS)
• 📡 Event emitter (TranscribeEmitter) for handling errors externally
• 🔐 Only activates when properly configured

📦 Installation

npm install vue-transcribe

📤 Exports

Export	Description
TranscribeDirective	Vue directive for adding speech-to-text behavior to input containers
TranscribeService	Singleton managing WebSocket and configuration
CommandProcessor	Global processor for mapping voice commands to app-defined tasks
TranscribeEmitter	Emitter that emits error events for custom handling in the host app

🚀 Getting Started

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️⃣ Import Styles

import 'vue-transcribe/css';

3️⃣ Set WebSocket URL

You must assign a valid presigned WebSocket URL before using the directive.

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

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

// Initial setup
updateWebSocketURL();

// Refresh every 5 minutes (AWS presigned URLs expire after 5 minutes)
setInterval(updateWebSocketURL, 5 * 60 * 1000);

Set TranscribeService.getInstance().configured = true to activate the directive.

4️⃣ Set Up Command Mode (optional)

If using type: 'command', configure the CommandProcessor globally:

import { CommandProcessor } from 'vue-transcribe';

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

5️⃣ Handle Transcription Errors (optional)

Use the TranscribeEmitter to listen for errors:

import { TranscribeEmitter } from 'vue-transcribe';

TranscribeEmitter.on('error', (err) => {
  console.error('Transcription error:', err);
  // You could show a toast, log it, etc.
});

6️⃣ Apply the Directive

Wrap your input or textarea inside a container and apply v-transcribe with options:

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

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

🧩 Directive Options

Option	Type	Description
style	Object	Style overrides for mic, spinner, vector, container
languageCode	String	BCP-47 language code (e.g. en-US)
type	"generate" | "command"	generate inserts text; command matches and executes mapped commands
maxRecordingTime	Number (ms)	Max allowed recording duration
append	Boolean	If true, appends to input content; else, replaces
micIconClass	Array<String>	CSS class names for mic icon button
listeningSVG	String (URL)	Path to animation shown while listening

⚙️ Defaults

Option	Default Value
type	'generate'
maxRecordingTime	5000
append	false
micIconClass	['mdi', 'mdi-microphone']
listeningSVG	https://bposeats-downloads-test.s3.us-east-1.amazonaws.com/listening.svg

🎨 Style Object Example

style: {
  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 and is optional.

🔄 Transcription Modes

Mode	Description
generate	Converts speech to freeform text, injected into the input
command	Matches speech to a registered command and executes the mapped task (function)

✅ Requirements & Notes

• You must manually refresh AWS presigned URLs every 5 minutes
• Directive only activates when: TranscribeService.getInstance().configured === true
• CommandProcessor.commandMap must be an array of { command, task }
• Attach the directive to the container element (not directly on the input)
• Use TranscribeEmitter.on('error', cb) to listen for transcription errors

💡 Example Setup (Vue 2)

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

Vue.directive('transcribe', TranscribeDirective);

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

function setURL() {
  axios.get('/api/transcribe-url')
    .then(res => TranscribeService.getInstance().setURL(res.data.url));
}

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

TranscribeService.getInstance().configured = true;

TranscribeEmitter.on('error', err => {
  console.error('Transcription error:', err);
});

📚 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