coursecode 0.1.0

package/framework/scripts/tts-providers/azure-provider.js

@@ -0,0 +1,178 @@
+/**
+ * Azure Cognitive Services TTS Provider
+ * 
+ * Microsoft's neural TTS with extensive language and voice support.
+ * 
+ * Environment variables:
+ *   AZURE_SPEECH_KEY      - Required: Your Azure Speech service key
+ *   AZURE_SPEECH_REGION   - Required: Azure region (e.g., eastus, westeurope)
+ *   AZURE_VOICE           - Optional: Default voice name (e.g., en-US-JennyNeural)
+ * 
+ * Voice settings (per-narration):
+ *   voice  - Full voice name (e.g., en-US-JennyNeural)
+ *   style  - Speaking style (e.g., cheerful, sad, angry) - neural voices only
+ *   rate   - Speaking rate (e.g., "+10%", "-20%", "1.2")
+ *   pitch  - Pitch adjustment (e.g., "+5%", "-10%")
+ */
+
+import { BaseTTSProvider } from './base-provider.js';
+
+// Default settings
+const DEFAULT_VOICE = 'en-US-JennyNeural';
+const DEFAULT_OUTPUT_FORMAT = 'audio-24khz-48kbitrate-mono-mp3';
+
+export class AzureProvider extends BaseTTSProvider {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'azure';
+        this.apiKey = config.apiKey || process.env.AZURE_SPEECH_KEY;
+        this.region = config.region || process.env.AZURE_SPEECH_REGION;
+    }
+
+    static getRequiredEnvVars() {
+        return [
+            { name: 'AZURE_SPEECH_KEY', required: true, description: 'Azure Speech service key' },
+            { name: 'AZURE_SPEECH_REGION', required: true, description: 'Azure region (e.g., eastus)' },
+            { name: 'AZURE_VOICE', required: false, description: 'Default voice (e.g., en-US-JennyNeural)' }
+        ];
+    }
+
+    validateConfig() {
+        if (!this.apiKey) {
+            throw new Error('AZURE_SPEECH_KEY not set in environment or .env file');
+        }
+        if (!this.region) {
+            throw new Error('AZURE_SPEECH_REGION not set in environment or .env file');
+        }
+    }
+
+    getDefaultVoiceId() {
+        return process.env.AZURE_VOICE || DEFAULT_VOICE;
+    }
+
+    getDefaultSettings() {
+        return {
+            voice: this.getDefaultVoiceId(),
+            style: null,
+            rate: null,
+            pitch: null
+        };
+    }
+
+    normalizeSettings(settings) {
+        const normalized = { ...settings };
+        
+        // Map 'voice_id' to 'voice'
+        if (settings.voice_id && !settings.voice) {
+            normalized.voice = settings.voice_id;
+            delete normalized.voice_id;
+        }
+        
+        // Map 'speed' to 'rate'
+        if (settings.speed && !settings.rate) {
+            // Convert numeric speed to percentage
+            const speed = parseFloat(settings.speed);
+            if (!isNaN(speed)) {
+                const percent = Math.round((speed - 1) * 100);
+                normalized.rate = percent >= 0 ? `+${percent}%` : `${percent}%`;
+            }
+            delete normalized.speed;
+        }
+        
+        return normalized;
+    }
+
+    async getVoices() {
+        this.validateConfig();
+        
+        const url = `https://${this.region}.tts.speech.microsoft.com/cognitiveservices/voices/list`;
+        
+        const response = await fetch(url, {
+            headers: {
+                'Ocp-Apim-Subscription-Key': this.apiKey
+            }
+        });
+        
+        if (!response.ok) {
+            throw new Error(`Failed to fetch voices: ${response.status}`);
+        }
+        
+        const voices = await response.json();
+        return voices.map(v => ({
+            id: v.ShortName,
+            name: v.DisplayName,
+            description: `${v.LocaleName} - ${v.VoiceType}`
+        }));
+    }
+
+    /**
+     * Build SSML for the request
+     */
+    _buildSSML(text, settings) {
+        const voice = settings.voice || this.getDefaultVoiceId();
+        
+        // Build prosody attributes
+        const prosodyAttrs = [];
+        if (settings.rate) prosodyAttrs.push(`rate="${settings.rate}"`);
+        if (settings.pitch) prosodyAttrs.push(`pitch="${settings.pitch}"`);
+        
+        // Build express-as for style (neural voices only)
+        let content = this._escapeXml(text);
+        
+        if (settings.style) {
+            content = `<mstts:express-as style="${settings.style}">${content}</mstts:express-as>`;
+        }
+        
+        if (prosodyAttrs.length > 0) {
+            content = `<prosody ${prosodyAttrs.join(' ')}>${content}</prosody>`;
+        }
+        
+        return `<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="en-US">
+    <voice name="${voice}">
+        ${content}
+    </voice>
+</speak>`;
+    }
+
+    _escapeXml(text) {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+
+    async generateAudio(text, settings = {}) {
+        this.validateConfig();
+        
+        const normalizedSettings = this.normalizeSettings(settings);
+        const ssml = this._buildSSML(text, normalizedSettings);
+        
+        const url = `https://${this.region}.tts.speech.microsoft.com/cognitiveservices/v1`;
+        
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Ocp-Apim-Subscription-Key': this.apiKey,
+                    'Content-Type': 'application/ssml+xml',
+                    'X-Microsoft-OutputFormat': DEFAULT_OUTPUT_FORMAT,
+                    'User-Agent': 'SCORMNarrationGenerator'
+                },
+                body: ssml
+            });
+        } catch (fetchError) {
+            const cause = fetchError.cause ? `: ${fetchError.cause.message || fetchError.cause.code}` : '';
+            throw new Error(`Network error connecting to Azure Speech API${cause}. Check your internet connection.`);
+        }
+        
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Azure Speech API error (${response.status}): ${errorText}`);
+        }
+        
+        return Buffer.from(await response.arrayBuffer());
+    }
+}

package/framework/scripts/tts-providers/base-provider.js

@@ -0,0 +1,81 @@
+/**
+ * Base TTS Provider Interface
+ * 
+ * All TTS providers must extend this class and implement the required methods.
+ * This enables easy swapping between providers (ElevenLabs, OpenAI, Azure, etc.)
+ */
+
+export class BaseTTSProvider {
+    constructor(config = {}) {
+        this.config = config;
+        this.name = 'base';
+    }
+
+    /**
+     * Get the provider name for logging/identification
+     * @returns {string}
+     */
+    getName() {
+        return this.name;
+    }
+
+    /**
+     * Validate that the provider is properly configured (API keys, etc.)
+     * @throws {Error} If configuration is invalid
+     */
+    validateConfig() {
+        throw new Error('validateConfig() must be implemented by provider');
+    }
+
+    /**
+     * Get the list of environment variables this provider requires
+     * @returns {Array<{name: string, required: boolean, description: string}>}
+     */
+    static getRequiredEnvVars() {
+        return [];
+    }
+
+    /**
+     * Get available voices for this provider
+     * @returns {Promise<Array<{id: string, name: string, description?: string}>>}
+     */
+    async getVoices() {
+        throw new Error('getVoices() must be implemented by provider');
+    }
+
+    /**
+     * Generate audio from text
+     * @param {string} text - The text to convert to speech
+     * @param {Object} options - Provider-specific options (voice, model, etc.)
+     * @returns {Promise<Buffer>} - Audio buffer (MP3 format preferred)
+     */
+    async generateAudio(text, _options = {}) {
+        throw new Error('generateAudio() must be implemented by provider');
+    }
+
+    /**
+     * Get the default voice ID for this provider
+     * @returns {string}
+     */
+    getDefaultVoiceId() {
+        throw new Error('getDefaultVoiceId() must be implemented by provider');
+    }
+
+    /**
+     * Get default settings for this provider
+     * @returns {Object}
+     */
+    getDefaultSettings() {
+        return {};
+    }
+
+    /**
+     * Normalize provider-specific settings to a common format
+     * This allows course authors to use consistent setting names across providers
+     * @param {Object} settings - Settings object (may have provider-specific keys)
+     * @returns {Object} - Normalized settings for this provider
+     */
+    normalizeSettings(settings) {
+        return settings;
+    }
+}

package/framework/scripts/tts-providers/deepgram-provider.js

@@ -0,0 +1,135 @@
+/**
+ * Deepgram TTS Provider (Aura)
+ * 
+ * Deepgram's Aura text-to-speech with fast, natural-sounding voices.
+ * 
+ * Environment variables:
+ *   DEEPGRAM_API_KEY  - Required: Your Deepgram API key
+ *   DEEPGRAM_VOICE    - Optional: Default voice (default: aura-2-orion-en)
+ * 
+ * Voice settings (per-narration):
+ *   voice  - Voice name (e.g., aura-2-orion-en, aura-2-luna-en)
+ * 
+ * Available Aura 2 voices:
+ *   aura-2-asteria-en  - Female, American, warm and conversational
+ *   aura-2-luna-en     - Female, American, soft and calm
+ *   aura-2-stella-en   - Female, American, confident and clear
+ *   aura-2-athena-en   - Female, British, refined and articulate
+ *   aura-2-hera-en     - Female, American, authoritative
+ *   aura-2-orion-en    - Male, American, deep and steady
+ *   aura-2-arcas-en    - Male, American, energetic and upbeat
+ *   aura-2-perseus-en  - Male, American, warm and friendly
+ *   aura-2-angus-en    - Male, Irish, warm and friendly
+ *   aura-2-orpheus-en  - Male, American, smooth and rich
+ *   aura-2-helios-en   - Male, British, refined
+ *   aura-2-zeus-en     - Male, American, authoritative
+ */
+
+import { BaseTTSProvider } from './base-provider.js';
+
+// Default settings
+const DEFAULT_VOICE = 'aura-2-hermes-en';
+
+// Available Aura 2 voices
+const AURA_VOICES = [
+    { id: 'aura-2-asteria-en', name: 'Asteria', description: 'Female, American - warm and conversational' },
+    { id: 'aura-2-luna-en', name: 'Luna', description: 'Female, American - soft and calm' },
+    { id: 'aura-2-stella-en', name: 'Stella', description: 'Female, American - confident and clear' },
+    { id: 'aura-2-athena-en', name: 'Athena', description: 'Female, British - refined and articulate' },
+    { id: 'aura-2-hera-en', name: 'Hera', description: 'Female, American - authoritative' },
+    { id: 'aura-2-orion-en', name: 'Orion', description: 'Male, American - deep and steady' },
+    { id: 'aura-2-arcas-en', name: 'Arcas', description: 'Male, American - energetic and upbeat' },
+    { id: 'aura-2-perseus-en', name: 'Perseus', description: 'Male, American - warm and friendly' },
+    { id: 'aura-2-angus-en', name: 'Angus', description: 'Male, Irish - warm and friendly' },
+    { id: 'aura-2-orpheus-en', name: 'Orpheus', description: 'Male, American - smooth and rich' },
+    { id: 'aura-2-helios-en', name: 'Helios', description: 'Male, British - refined' },
+    { id: 'aura-2-zeus-en', name: 'Zeus', description: 'Male, American - authoritative' }
+];
+
+export class DeepgramProvider extends BaseTTSProvider {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'deepgram';
+        this.apiKey = config.apiKey || process.env.DEEPGRAM_API_KEY;
+    }
+
+    static getRequiredEnvVars() {
+        return [
+            { name: 'DEEPGRAM_API_KEY', required: true, description: 'Deepgram API key' },
+            { name: 'DEEPGRAM_VOICE', required: false, description: 'Default voice (e.g., aura-asteria-en)' }
+        ];
+    }
+
+    validateConfig() {
+        if (!this.apiKey) {
+            throw new Error('DEEPGRAM_API_KEY not set in environment or .env file');
+        }
+        
+        const trimmedKey = this.apiKey.trim();
+        if (trimmedKey !== this.apiKey || !trimmedKey) {
+            throw new Error('DEEPGRAM_API_KEY contains invalid whitespace - check your .env file');
+        }
+    }
+
+    getDefaultVoiceId() {
+        return process.env.DEEPGRAM_VOICE || DEFAULT_VOICE;
+    }
+
+    getDefaultSettings() {
+        return {
+            voice: this.getDefaultVoiceId()
+        };
+    }
+
+    normalizeSettings(settings) {
+        const normalized = { ...settings };
+        
+        // Map 'voice_id' to 'voice'
+        if (settings.voice_id && !settings.voice) {
+            normalized.voice = settings.voice_id;
+            delete normalized.voice_id;
+        }
+        
+        return normalized;
+    }
+
+    async getVoices() {
+        // Deepgram voices are fixed, no API call needed
+        return AURA_VOICES;
+    }
+
+    async generateAudio(text, settings = {}) {
+        this.validateConfig();
+        
+        const normalizedSettings = this.normalizeSettings(settings);
+        const defaults = this.getDefaultSettings();
+        
+        const voice = normalizedSettings.voice || defaults.voice;
+        
+        // Deepgram TTS endpoint
+        const url = `https://api.deepgram.com/v1/speak?model=${voice}`;
+        
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Token ${this.apiKey.trim()}`,
+                    'Content-Type': 'text/plain'
+                },
+                body: text
+            });
+        } catch (fetchError) {
+            const cause = fetchError.cause ? `: ${fetchError.cause.message || fetchError.cause.code}` : '';
+            throw new Error(`Network error connecting to Deepgram API${cause}. Check your internet connection.`);
+        }
+        
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Deepgram API error (${response.status}): ${errorText}`);
+        }
+        
+        // Deepgram returns audio directly (not base64)
+        return Buffer.from(await response.arrayBuffer());
+    }
+}

package/framework/scripts/tts-providers/elevenlabs-provider.js

@@ -0,0 +1,148 @@
+/**
+ * ElevenLabs TTS Provider
+ * 
+ * High-quality AI voice synthesis with customizable voice settings.
+ * 
+ * Environment variables:
+ *   ELEVENLABS_API_KEY    - Required: Your ElevenLabs API key
+ *   ELEVENLABS_VOICE_ID   - Optional: Default voice ID (default: Rachel)
+ *   ELEVENLABS_MODEL_ID   - Optional: Model to use (default: eleven_v3)
+ * 
+ * Voice settings (per-narration):
+ *   voice_id         - Voice to use
+ *   model_id         - Model to use
+ *   stability        - Voice stability (0-1, default: 0.5)
+ *   similarity_boost - Voice similarity (0-1, default: 0.75)
+ */
+
+import { BaseTTSProvider } from './base-provider.js';
+
+// Default voice settings
+const DEFAULT_VOICE_ID = 'S9UjcNYIwfBOtZiDnIQT';
+const DEFAULT_MODEL_ID = 'eleven_v3';
+const DEFAULT_STABILITY = 0.5;
+const DEFAULT_SIMILARITY_BOOST = 0.75;
+
+export class ElevenLabsProvider extends BaseTTSProvider {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'elevenlabs';
+        this.apiKey = config.apiKey || process.env.ELEVENLABS_API_KEY;
+    }
+
+    static getRequiredEnvVars() {
+        return [
+            { name: 'ELEVENLABS_API_KEY', required: true, description: 'ElevenLabs API key' },
+            { name: 'ELEVENLABS_VOICE_ID', required: false, description: 'Default voice ID (default: Rachel)' },
+            { name: 'ELEVENLABS_MODEL_ID', required: false, description: 'Model ID (default: eleven_v3)' }
+        ];
+    }
+
+    validateConfig() {
+        if (!this.apiKey) {
+            throw new Error('ELEVENLABS_API_KEY not set in environment or .env file');
+        }
+        
+        const trimmedKey = this.apiKey.trim();
+        if (trimmedKey !== this.apiKey || !trimmedKey) {
+            throw new Error('ELEVENLABS_API_KEY contains invalid whitespace - check your .env file');
+        }
+    }
+
+    getDefaultVoiceId() {
+        return process.env.ELEVENLABS_VOICE_ID || DEFAULT_VOICE_ID;
+    }
+
+    getDefaultSettings() {
+        return {
+            voice_id: this.getDefaultVoiceId(),
+            model_id: process.env.ELEVENLABS_MODEL_ID || DEFAULT_MODEL_ID,
+            stability: DEFAULT_STABILITY,
+            similarity_boost: DEFAULT_SIMILARITY_BOOST
+        };
+    }
+
+    normalizeSettings(settings) {
+        // ElevenLabs uses its own naming convention, map common names
+        const normalized = { ...settings };
+        
+        // Map common 'voice' to 'voice_id'
+        if (settings.voice && !settings.voice_id) {
+            normalized.voice_id = settings.voice;
+            delete normalized.voice;
+        }
+        
+        // Map common 'model' to 'model_id'
+        if (settings.model && !settings.model_id) {
+            normalized.model_id = settings.model;
+            delete normalized.model;
+        }
+        
+        return normalized;
+    }
+
+    async getVoices() {
+        this.validateConfig();
+        
+        const response = await fetch('https://api.elevenlabs.io/v1/voices', {
+            headers: {
+                'xi-api-key': this.apiKey.trim()
+            }
+        });
+        
+        if (!response.ok) {
+            throw new Error(`Failed to fetch voices: ${response.status}`);
+        }
+        
+        const data = await response.json();
+        return data.voices.map(v => ({
+            id: v.voice_id,
+            name: v.name,
+            description: v.description || v.labels?.description
+        }));
+    }
+
+    async generateAudio(text, settings = {}) {
+        this.validateConfig();
+        
+        const normalizedSettings = this.normalizeSettings(settings);
+        const defaults = this.getDefaultSettings();
+        
+        const voiceId = normalizedSettings.voice_id || defaults.voice_id;
+        const modelId = normalizedSettings.model_id || defaults.model_id;
+        const stability = parseFloat(normalizedSettings.stability) || defaults.stability;
+        const similarityBoost = parseFloat(normalizedSettings.similarity_boost) || defaults.similarity_boost;
+        
+        const url = `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`;
+        
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Accept': 'audio/mpeg',
+                    'Content-Type': 'application/json',
+                    'xi-api-key': this.apiKey.trim()
+                },
+                body: JSON.stringify({
+                    text,
+                    model_id: modelId,
+                    voice_settings: {
+                        stability,
+                        similarity_boost: similarityBoost
+                    }
+                })
+            });
+        } catch (fetchError) {
+            const cause = fetchError.cause ? `: ${fetchError.cause.message || fetchError.cause.code}` : '';
+            throw new Error(`Network error connecting to ElevenLabs API${cause}. Check your internet connection and proxy settings.`);
+        }
+        
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`ElevenLabs API error (${response.status}): ${errorText}`);
+        }
+        
+        return Buffer.from(await response.arrayBuffer());
+    }
+}