Welcome to the Djelia JavaScript SDK! This powerful library enables seamless integration with Djelia's AI services for African languages, featuring translation, transcription, and text-to-speech capabilities. Built with modern JavaScript/Node.js, it offers both Promise-based and streaming APIs for maximum flexibility. can't be fun, right? Let's dive in!
- Installation
- Client Initialization
- 2.1 API Key Loading
- 2.2 Client Setup
- Operations
- 3.1 Translation
- 3.1.1 Get Supported Languages
- 3.1.2 Translate Text
- 3.2 Transcription
- 3.2.1 Basic Transcription
- 3.2.2 Streaming Transcription
- 3.2.3 French Translation
- 3.3 Text-to-Speech (TTS)
- 3.3.1 TTS v1 with Speaker ID
- 3.3.2 TTS v2 with Natural Descriptions
- 3.3.3 Streaming TTS
- 3.4 Version Management
- 3.5 Parallel Operations
- 3.1 Translation
- Error Handling
- Explore the Djelia SDK Cookbook
Let's kick things off by installing the SDK
npm install djeliaOr using yarn:
yarn add djeliaInstall the Djelia JavaScript SDK directly from GitHub:
npm install git+https://github.com/djelia-org/djelia-javascript-sdk.gitAlternatively, use pnpm for faster dependency resolution:
pnpm install djeliapnpm install git+https://github.com/djelia-org/djelia-javascript-sdk.gitBefore we can do anything fancy, we need to set up our client. This involves loading our API key and initializing the client. Here's how:
First, grab your API key from a .env file - it's the safest way to keep your secrets, well, secret! If you don't have one yet, head to the Djelia dashboard and conjure one up.
require('dotenv').config();
const apiKey = process.env.DJELIA_API_KEY;
// Alternatively: const apiKey = "your_api_key_here" (but shh, that's not safe!)
// Specify your audio file for transcription tests
const audioFilePath = process.env.TEST_AUDIO_FILE || "audio.wav";Note: Ensure your audio file (e.g.,
audio.wav) exists at the specified path. SetTEST_AUDIO_FILEin your.envfile if using a custom path:echo "TEST_AUDIO_FILE=/path/to/your/audio.wav" >> .envWithout a valid audio file, transcription operations will fail. That's not what you want right 😂
For those who like to keep things simple and powerful, here's how to set up the client:
const { Djelia } = require('djelia');
const djeliaClient = new Djelia(apiKey);
// if DJELIA_API_KEY is already set you can just do : (yes I know I'm making your life easy 😂)
const djeliaClient = new Djelia();Now for the fun part - let's do stuff with the Djelia API! We'll cover translating between African languages, transcribing audio (with streaming!), and generating natural speech with beautiful JavaScript async/await patterns. Yes, yes, let's do it ❤️🔥!
Let's unlock the power of multilingual communication!
First, let's see what languages we can work with.
Simple and straightforward - get your supported languages and print them:
const languages = await djeliaClient.translation.getSupportedLanguages();
languages.forEach(lang => {
console.log(`${lang.name}: ${lang.code}`);
});Let's translate some text between beautiful 🇲🇱 languages and others. Feel free to try different language combinations!
const { TranslationRequest, Language, Versions } = require('djelia');
const request = new TranslationRequest(
"Hello, how are you today?",
Language.ENGLISH,
Language.BAMBARA
);Create that translation and see what you get:
const { TranslationResponse } = require('djelia');
try {
const response = await djeliaClient.translation.translate(request, Versions.v1);
console.log(`Original: ${request.text}`);
console.log(`Translation: ${response.text}`);
} catch (error) {
console.log(`Translation error: ${error.message}`);
}Time to turn audio into text with timestamps and everything!
Let's transcribe some audio files. Make sure you have an audio file ready - check audioFilePath.
const { Versions } = require('djelia');
try {
const transcription = await djeliaClient.transcription.transcribe(
audioFilePath,
false, // translateToFrench
false, // stream
Versions.v2
);
console.log(`Transcribed ${transcription.length} segments:`);
transcription.forEach(segment => {
console.log(`[${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s]: ${segment.text}`);
});
} catch (error) {
console.log(`Transcription error: ${error.message}`);
}Want realtime results? Let's stream that transcription! This is really important for live applications
console.log("Streaming transcription (showing first 3 segments)...");
let segmentCount = 0;
try {
const stream = await djeliaClient.transcription.transcribe(
audioFilePath,
false, // translateToFrench
true, // stream
Versions.v2
);
for await (const segment of stream) {
segmentCount++;
console.log(`Segment ${segmentCount}: [${segment.start.toFixed(2)}s]: ${segment.text}`);
if (segmentCount >= 3) { // Just showing first 3 for demo
console.log("...and more segments!");
break;
}
}
} catch (error) {
console.log(`Streaming transcription error: ${error.message}`);
}Want to transcribe and translate to French in one go? We've got you covered!
try {
const frenchTranscription = await djeliaClient.transcription.transcribe(
audioFilePath,
true, // translateToFrench
false, // stream
Versions.v2
);
console.log(`French translation: ${frenchTranscription.text}`);
} catch (error) {
console.log(`French transcription error: ${error.message}`);
}Let's make some beautiful voices! Choose between numbered speakers or describe exactly how you want it to sound.
Classic approach with speaker IDs (0-4). Simple and effective!
const { TTSRequest } = require('djelia');
const ttsRequestV1 = new TTSRequest(
"Aw ni ce, i ka kɛnɛ wa?", // "Hello, how are you?" in Bambara
1 // Choose from 0, 1, 2, 3, or 4
);Generate that audio and save it:
try {
const audioFileV1 = await djeliaClient.tts.textToSpeech(
ttsRequestV1,
"hello_v1.wav",
false, // stream
Versions.v1
);
console.log(`Audio saved to: ${audioFileV1}`);
} catch (error) {
console.log(`TTS v1 error: ${error.message}`);
}This is where it gets fun! Describe exactly how you want the voice to sound, but make sure to include one of the supported speakers: Moussa, Sekou, or Seydou.
const { TTSRequestV2 } = require('djelia');
const ttsRequestV2 = new TTSRequestV2(
"Aw ni ce, i ka kɛnɛ wa?",
"Seydou speaks with a warm, welcoming tone", // Must include Moussa, Sekou, or Seydou
1.0 // Control speech pacing (0.1 - 2.0)
);Note: The description field must include one of the supported speakers. For example, "Moussa speaks with a warm tone" is valid, but "Natural tone" will raise an error.
Create natural sounding speech:
try {
const audioFileV2 = await djeliaClient.tts.textToSpeech(
ttsRequestV2,
"hello_v2.wav",
false, // stream
Versions.v2
);
console.log(`Natural audio saved to: ${audioFileV2}`);
} catch (error) {
console.log(`TTS v2 error: ${error.message}`);
}Realtime audio generation! Get chunks as they're created (v2 only).
const streamingTtsRequest = new TTSRequestV2(
"An filɛ ni ye yɔrɔ minna ni an ye an sigi ka a layɛ yala an bɛ ka baara min kɛ ɛsike a kɛlen don ka Ɲɛ wa, ...............", // a very long text
"Seydou speaks clearly and naturally",
1.0
);Note: By default, the SDK may process multiple chunks (e.g., up to 5 in some configurations). This example limits to 5 chunks for consistency, but you can adjust the limit based on your application needs.
Stream that audio generation: (this is handsome)
console.log("Streaming TTS generation...");
let chunkCount = 0;
let totalBytes = 0;
const maxChunks = 5;
try {
const stream = await djeliaClient.tts.textToSpeech(
streamingTtsRequest,
"streamed_audio.wav",
true, // stream
Versions.v2
);
for await (const chunk of stream) {
chunkCount++;
totalBytes += chunk.length;
console.log(`Chunk ${chunkCount}: ${chunk.length} bytes`);
if (chunkCount >= maxChunks) {
console.log(`...and more chunks! (Total so far: ${totalBytes} bytes)`);
break;
}
}
} catch (error) {
console.log(`Streaming TTS error: ${error.message}`);
}The SDK supports multiple API versions (v1, v2) via the Versions enum. Use Versions.latest() to get the latest version or Versions.allVersions() to list available versions.
const { Versions } = require('djelia');
console.log(`Latest version: ${Versions.latest()}`);
console.log(`Available versions: ${Versions.allVersions().map(v => `v${v}`)}`);
// Use specific version
try {
const transcription = await djeliaClient.transcription.transcribe(
audioFilePath,
false, // translateToFrench
false, // stream
Versions.v2
);
console.log(`Transcribed ${transcription.length} segments`);
} catch (error) {
console.log(`Transcription error: ${error.message}`);
}Run multiple API operations concurrently using Promise.allSettled(). This is great for performance in applications needing simultaneous translations, transcriptions, or TTS generation.
const { TranslationRequest, Language, TTSRequestV2, Versions } = require('djelia');
async function parallelOperations() {
try {
const translationRequest = new TranslationRequest(
"Hello",
Language.ENGLISH,
Language.BAMBARA
);
const ttsRequest = new TTSRequestV2(
"Aw ni ce, i ka kɛnɛ wa?",
"Moussa speaks with a clear tone",
1.0
);
const results = await Promise.allSettled([
djeliaClient.translation.translate(translationRequest, Versions.v1),
djeliaClient.transcription.transcribe(audioFilePath, false, false, Versions.v2),
djeliaClient.tts.textToSpeech(ttsRequest, "parallel_tts.wav", false, Versions.v2)
]);
results.forEach((result, i) => {
if (result.status === 'fulfilled') {
console.log(`Operation ${i+1} succeeded: ${result.value.constructor.name}`);
} else {
console.log(`Operation ${i+1} failed: ${result.reason.message}`);
}
});
} catch (error) {
console.log(`Parallel operations error: ${error.message}`);
}
}
// Run it
parallelOperations();The Djelia SDK provides specific exception classes to handle errors gracefully. Use these to catch and respond to issues like invalid API keys, unsupported languages, or incorrect speaker descriptions.
const {
AuthenticationError,
APIError,
ValidationError,
LanguageError,
SpeakerError
} = require('djelia');
try {
const response = await djeliaClient.translation.translate(request, Versions.v1);
console.log(`Translation: ${response.text}`);
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Authentication error (check API key):', error.message);
} else if (error instanceof LanguageError) {
console.error('Invalid or unsupported language:', error.message);
} else if (error instanceof ValidationError) {
console.error('Validation error (e.g., invalid input):', error.message);
} else if (error instanceof APIError) {
console.error(`API error (status ${error.statusCode}): ${error.message}`);
} else {
console.error('Unexpected error:', error.message);
}
}- AuthenticationError: Invalid or expired API key (HTTP 401).
- APIError: General API issues, including forbidden access (403) or resource not found (404).
- ValidationError: Invalid inputs, such as missing audio files or incorrect parameters (422).
- LanguageError: Unsupported source or target language.
- SpeakerError: Invalid speaker ID (TTS v1) or description missing a supported speaker (TTS v2).
Check logs for detailed errors, and ensure your .env file includes a valid DJELIA_API_KEY and TEST_AUDIO_FILE.
Want to take your Djelia SDK skills to the next level? Check out the Djelia SDK Cookbook for a comprehensive example that puts it all together! The cookbook demonstrates:
- Full Test Suite: Run comprehensive tests for translation, transcription, and TTS, with detailed summaries.
- Error Handling: Robust try-catch blocks and logging to catch and debug issues.
- Configuration Management: Load API keys and audio paths from a
.envfile with validation. - Advanced Features: Parallel API operations, version management, and streaming capabilities.
- Modular Design: Organized code structure for easy customization.
To run the cookbook, clone the repository, install dependencies, and execute:
git clone https://github.com/djelia-org/djelia-javascript-sdk.git
npm install
cd djelia-javascript-sdk
npm run exampleOr run it directly:
node examples/cookbook.jsMake sure your .env file includes DJELIA_API_KEY and TEST_AUDIO_FILE. The cookbook is perfect for developers who want a ready-to-use template for building real-world applications with the Djelia SDK.
And there you have it - a full workshop on using the Djelia JavaScript SDK! You've installed it, set up the client, and mastered translation, transcription, and text-to-speech with beautiful async/await patterns. Pretty cool, right? Feel free to tweak the code, explore different languages and voices, and check out the Djelia SDK Cookbook for a deeper dive.
Pro tip: The async/await patterns are perfect for applications that need to handle multiple operations efficiently. The streaming features are fantastic for realtime applications. And remember, Bambara is just one of the beautiful African languages you can work with!
IMPORTANT: If you encounter any issues, please create an issue in the repository, explain the problem you encountered (include logs if possible), and tag @sudoping01.
Great job, bro 🫂! This is a fantastic integration guide built with ❤️ for 🇲🇱 and beyond!