UGAI - Akan TTS, STT & Spellchecker API Wrapper

A comprehensive TypeScript/JavaScript package for interacting with Akan Text-to-Speech (TTS), Speech-to-Text (STT), and Spellchecker APIs. This package provides clean, modular classes with full type support for seamless integration.

Features

• 🎤 Text-to-Speech (TTS): Convert Akan text to natural speech
• 🔊 Speech-to-Text (STT): Transcribe Akan audio to text
• ✍️ Spellchecker: Check spelling and get suggestions for Akan text
• 🏥 Multiple Models: Support for standard and non-standard speech models
• 🔄 Robust Error Handling: Comprehensive error handling with retries
• 📝 TypeScript Support: Full type definitions included
• 🚀 ESM Compatible: Modern ES module support
• ⚡ Promise-based: Async/await friendly API

Installation

npm install ugai

Note: This package uses ES modules and requires Node.js 18+ or modern browsers with fetch support.

Quick Start

Text-to-Speech (TTS)

import { UGTTS } from "ugai/tts";
import fs from "fs/promises";

const tts = new UGTTS();

// Basic usage
const result = await tts.speak("Akwaaba! Yɛma wo akwaaba.");
await fs.writeFile("output.wav", result.audioData);

// With specific speaker
const customResult = await tts.speak("Me din de Kofi.", {
	modelType: "ss",
	speaker: "PT",
});

// Save directly to file
await tts.speakToFile("Ɛte sɛn?", "greeting.wav", { speaker: "IM" });

Speech-to-Text (STT)

import { UGSTT } from "ugai/stt";

// For standard speech
const sttStandard = new UGSTT({ model: "std" });
const transcription = await sttStandard.transcribe("audio.wav");
console.log(transcription.text);

// For non-standard speech (impaired speech)
const sttImpaired = new UGSTT({ model: "nss" });
const result = await sttImpaired.transcribe("impaired_audio.wav", {
	modelName: "stmm", // stammering model
});

// Using Buffer
import fs from "fs/promises";
const audioBuffer = await fs.readFile("speech.wav");
const transcription = await sttStandard.transcribeBuffer(audioBuffer);

Spellchecker

import { UGSpellcheck } from "ugai/spellcheck";

const spellcheck = new UGSpellcheck();

// Check spelling of text
const result = await spellcheck.spellcheckText("Akwaaba! Yɛma wo akwaaba.");
console.log("Spellcheck results:", result.results);

// Get suggestions for a misspelled word
const suggestions = await spellcheck.getSuggestions("akwaaba", "akan-twi", 5);
console.log("Suggestions:", suggestions.suggestions);

// Check if a single word is correct
const wordCheck = await spellcheck.checkWord("akwaaba");
console.log("Is correct:", wordCheck.correct);

// Get available models
const models = await spellcheck.getAvailableModels();
console.log("Available models:", models.models);

API Reference

UGTTS Class

Constructor

new UGTTS(config?: UGTTSConfig)

UGTTSConfig Options:

• apiUrl?: string - Custom API endpoint (optional)
• timeout?: number - Request timeout in milliseconds (default: 30000)
• retries?: number - Number of retry attempts (default: 3)

Methods

speak(text, options?): Promise<UGTTSResponse>

Convert text to speech.

Parameters:

• text: string - The text to convert to speech
• options?: UGTTSSpeakOptions
  • modelType?: 'ss' | 'ms' - Single speaker ('ss') or multi-speaker ('ms')
  • speaker?: 'PT' | 'IM' | 'AN' | string - Speaker identifier

Returns: Promise<UGTTSResponse>

• audioData: Buffer - Audio data as Buffer
• modelUsed: string - Model that was used
• speakerUsed: string - Speaker that was used

speakToFile(text, filePath, options?): Promise<void>

Convert text to speech and save to file.

getAvailableModels(): Promise<AvailableModelsResponse>

Get available TTS models and their capabilities.

UGSTT Class

Constructor

new UGSTT(config: UGSTTConfig)

UGSTTConfig Options:

• model: 'std' | 'nss' - Model type (required)
  • 'std' - Standard speech models
  • 'nss' - Non-standard speech models (for impaired speech)
• timeout?: number - Request timeout in milliseconds (default: 60000)
• retries?: number - Number of retry attempts (default: 3)

Methods

transcribe(audioInput, options?): Promise<UGSTTResponse>

Transcribe audio from file path or Buffer.

Parameters:

• audioInput: string | Buffer - File path or audio Buffer
• options?: UGSTTTranscribeOptions
  • modelName?: string - Specific model to use

Returns: Promise<UGSTTResponse>

• text: string - Transcribed text
• language: string - Detected language
• modelUsed: string - Model that was used

transcribeFile(filePath, options?): Promise<UGSTTResponse>

Transcribe audio from file path.

transcribeBuffer(buffer, options?): Promise<UGSTTResponse>

Transcribe audio from Buffer.

getAvailableModels(): Promise<AvailableModelsResponse>

Get available STT models.

UGSpellcheck Class

Constructor

new UGSpellcheck(config?: UGSpellcheckConfig)

UGSpellcheckConfig Options:

• apiUrl?: string - Custom API endpoint (optional)
• timeout?: number - Request timeout in milliseconds (default: 30000)
• retries?: number - Number of retry attempts (default: 3)

Methods

spellcheckText(text, modelName?): Promise<SpellCheckResponse>

Check spelling of text and return suggestions for misspelled words.

Parameters:

• text: string - The text to spellcheck
• modelName?: string - Spellchecker model to use (default: "akan-twi")

Returns: Promise<SpellCheckResponse>

• results: SpellCheckResult[] - Array of spellcheck results for each word

getSuggestions(word, modelName?, maxSuggestions?): Promise<SuggestionResponse>

Get spelling suggestions for a single word.

Parameters:

• word: string - The word to get suggestions for
• modelName?: string - Spellchecker model to use (default: "akan-twi")
• maxSuggestions?: number - Maximum number of suggestions to return

Returns: Promise<SuggestionResponse>

• word: string - The original word
• suggestions: string[] - Array of suggested corrections

checkWord(word, modelName?): Promise<WordCheckResponse>

Check if a single word is spelled correctly.

Parameters:

• word: string - The word to check
• modelName?: string - Spellchecker model to use (default: "akan-twi")

Returns: Promise<WordCheckResponse>

• word: string - The original word
• correct: boolean - Whether the word is spelled correctly

getAvailableModels(): Promise<AvailableModelsResponse>

Get available spellchecker models and their capabilities.

healthCheck(): Promise<{ status: string; service: string }>

Check health status of the spellchecker service.

Available Models

TTS Models

• Single Speaker (ss)

  • PT - Speaker PT
  • IM - Speaker IM
  • AN - Speaker AN

• Multi Speaker (ms)

  • Supports all three speakers in one model

STT Models

Standard Speech (std)

• sm - Small model for standard speech
• lg - Large model for standard speech

Non-Standard Speech (nss)

• stmm - Specialized for stammering
• clpsy - Specialized for cerebral palsy
• clft - Specialized for cleft palate
• gen-sm - Generalized small model
• gen-lg - Generalized large model

Spellchecker Models

• akan-twi - Akan/Twi spellchecker model with phonetic-based suggestions

Error Handling

Both classes provide comprehensive error handling with custom error types:

import { UGTTS, UGTTSError } from "ugai/tts";
import { UGSTT, UGSTTError } from "ugai/stt";
import { UGSpellcheck, UGSpellcheckError } from "ugai/spellcheck";

try {
	const result = await tts.speak("Hello");
} catch (error) {
	if (error instanceof UGTTSError) {
		console.error(`TTS Error: ${error.message}`);
		console.error(`Status Code: ${error.statusCode}`);
	}
}

try {
	const spellcheckResult = await spellcheck.spellcheckText("Akwaaba");
} catch (error) {
	if (error instanceof UGSpellcheckError) {
		console.error(`Spellcheck Error: ${error.message}`);
		console.error(`Status Code: ${error.statusCode}`);
	}
}

Advanced Usage

Custom Configuration

const tts = new UGTTS({
	timeout: 45000,
	retries: 5,
});

const stt = new UGSTT({
	model: "nss",
	timeout: 120000,
	retries: 2,
});

Model Information

// Get available TTS models
const ttsModels = await tts.getAvailableModels();
console.log("Available TTS models:", ttsModels.models);

// Get available STT models
const sttModels = await stt.getAvailableModels();
console.log("Available STT models:", sttModels.models);

// Get available spellchecker models
const spellcheckModels = await spellcheck.getAvailableModels();
console.log("Available spellchecker models:", spellcheckModels.models);

Working with Different Audio Formats

The STT service supports multiple audio formats:

// Supported formats: .wav, .mp3, .ogg, .flac, .m4a, .aac, .wma
await stt.transcribe("audio.mp3");
await stt.transcribe("recording.flac");

Requirements

• Node.js >= 18.0.0
• Modern browsers with fetch support

Dependencies

This package has no external dependencies and uses native Node.js APIs.

TypeScript Support

This package is written in TypeScript and includes full type definitions. All classes, interfaces, and methods are properly typed for the best development experience.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please create an issue on the GitHub repository.