coursecode 0.1.0

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

@@ -0,0 +1,272 @@
+/**
+ * Google Cloud TTS Provider (Chirp)
+ * 
+ * Google's neural TTS with Chirp voices for natural speech synthesis.
+ * 
+ * Authentication:
+ *   GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+ * 
+ * Setup:
+ *   1. Go to: https://console.cloud.google.com/iam-admin/serviceaccounts
+ *   2. Create a service account with "Cloud Text-to-Speech API User" role
+ *   3. Create a JSON key and download it
+ *   4. Set GOOGLE_APPLICATION_CREDENTIALS to the path
+ * 
+ * Environment variables:
+ *   GOOGLE_APPLICATION_CREDENTIALS   - Path to service account JSON (required)
+ *   GOOGLE_VOICE                     - Optional: Default voice (e.g., en-US-Chirp3-HD-Achernar)
+ *   GOOGLE_LANGUAGE                  - Optional: Language code (default: en-US)
+ * 
+ * Voice settings (per-narration):
+ *   voice     - Voice name (e.g., en-US-Chirp3-HD-Achernar, en-US-Neural2-F)
+ *   language  - Language code (e.g., en-US, en-GB)
+ *   speed     - Speaking rate (0.25-4.0, default: 1.0)
+ *   pitch     - Pitch adjustment (-20.0 to 20.0 semitones, default: 0)
+ * 
+ * Chirp 3 HD voices (highest quality):
+ *   en-US-Chirp3-HD-Achernar, en-US-Chirp3-HD-Aoede, en-US-Chirp3-HD-Charon,
+ *   en-US-Chirp3-HD-Fenrir, en-US-Chirp3-HD-Kore, en-US-Chirp3-HD-Leda,
+ *   en-US-Chirp3-HD-Orus, en-US-Chirp3-HD-Puck, en-US-Chirp3-HD-Schedar
+ */
+
+import { BaseTTSProvider } from './base-provider.js';
+import fs from 'fs';
+import crypto from 'crypto';
+
+// Default settings
+const DEFAULT_VOICE = 'en-US-Neural2-J';
+const DEFAULT_LANGUAGE = 'en-US';
+const DEFAULT_SPEED = 1.0;
+const DEFAULT_PITCH = 0;
+
+// Popular Chirp 3 HD voices (reference for documentation)
+const _CHIRP_VOICES = [
+    { id: 'en-US-Chirp3-HD-Achernar', name: 'Achernar', description: 'Chirp 3 HD - Warm and steady' },
+    { id: 'en-US-Chirp3-HD-Aoede', name: 'Aoede', description: 'Chirp 3 HD - Bright and clear' },
+    { id: 'en-US-Chirp3-HD-Charon', name: 'Charon', description: 'Chirp 3 HD - Deep and calm' },
+    { id: 'en-US-Chirp3-HD-Fenrir', name: 'Fenrir', description: 'Chirp 3 HD - Strong and confident' },
+    { id: 'en-US-Chirp3-HD-Kore', name: 'Kore', description: 'Chirp 3 HD - Soft and gentle' },
+    { id: 'en-US-Chirp3-HD-Leda', name: 'Leda', description: 'Chirp 3 HD - Professional and friendly' },
+    { id: 'en-US-Chirp3-HD-Orus', name: 'Orus', description: 'Chirp 3 HD - Authoritative' },
+    { id: 'en-US-Chirp3-HD-Puck', name: 'Puck', description: 'Chirp 3 HD - Energetic and upbeat' },
+    { id: 'en-US-Chirp3-HD-Schedar', name: 'Schedar', description: 'Chirp 3 HD - Smooth and reassuring' }
+];
+
+export class GoogleProvider extends BaseTTSProvider {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'google';
+        this.serviceAccountPath = config.serviceAccountPath || process.env.GOOGLE_APPLICATION_CREDENTIALS;
+        this._accessToken = null;
+        this._tokenExpiry = null;
+    }
+
+    static getRequiredEnvVars() {
+        return [
+            { name: 'GOOGLE_APPLICATION_CREDENTIALS', required: true, description: 'Path to service account JSON' },
+            { name: 'GOOGLE_VOICE', required: false, description: 'Default voice (e.g., en-US-Chirp3-HD-Leda)' },
+            { name: 'GOOGLE_LANGUAGE', required: false, description: 'Language code (default: en-US)' }
+        ];
+    }
+
+    validateConfig() {
+        if (!this.serviceAccountPath) {
+            throw new Error('GOOGLE_APPLICATION_CREDENTIALS must be set to the path of your service account JSON file');
+        }
+        
+        if (!fs.existsSync(this.serviceAccountPath)) {
+            throw new Error(`Service account file not found: ${this.serviceAccountPath}`);
+        }
+    }
+
+    /**
+     * Get OAuth2 access token from service account
+     */
+    async _getAccessToken() {
+        // Return cached token if still valid
+        if (this._accessToken && this._tokenExpiry && Date.now() < this._tokenExpiry) {
+            return this._accessToken;
+        }
+
+        const serviceAccount = JSON.parse(fs.readFileSync(this.serviceAccountPath, 'utf-8'));
+        
+        // Create JWT
+        const now = Math.floor(Date.now() / 1000);
+        const header = { alg: 'RS256', typ: 'JWT' };
+        const payload = {
+            iss: serviceAccount.client_email,
+            scope: 'https://www.googleapis.com/auth/cloud-platform',
+            aud: 'https://oauth2.googleapis.com/token',
+            iat: now,
+            exp: now + 3600
+        };
+
+        const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
+        const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const signatureInput = `${encodedHeader}.${encodedPayload}`;
+        
+        const sign = crypto.createSign('RSA-SHA256');
+        sign.update(signatureInput);
+        const signature = sign.sign(serviceAccount.private_key, 'base64url');
+        
+        const jwt = `${signatureInput}.${signature}`;
+
+        // Exchange JWT for access token
+        const response = await fetch('https://oauth2.googleapis.com/token', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${jwt}`
+        });
+
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to get access token: ${error}`);
+        }
+
+        const data = await response.json();
+        this._accessToken = data.access_token;
+        this._tokenExpiry = Date.now() + (data.expires_in - 60) * 1000; // Refresh 1 min early
+        
+        return this._accessToken;
+    }
+
+    getDefaultVoiceId() {
+        return process.env.GOOGLE_VOICE || DEFAULT_VOICE;
+    }
+
+    getDefaultSettings() {
+        return {
+            voice: this.getDefaultVoiceId(),
+            language: process.env.GOOGLE_LANGUAGE || DEFAULT_LANGUAGE,
+            speed: DEFAULT_SPEED,
+            pitch: DEFAULT_PITCH
+        };
+    }
+
+    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 'rate' to 'speed'
+        if (settings.rate && !settings.speed) {
+            // Convert percentage to multiplier if needed
+            const rate = settings.rate;
+            if (typeof rate === 'string' && rate.includes('%')) {
+                const percent = parseFloat(rate.replace('%', '').replace('+', ''));
+                normalized.speed = 1 + (percent / 100);
+            } else {
+                normalized.speed = parseFloat(rate);
+            }
+            delete normalized.rate;
+        }
+        
+        return normalized;
+    }
+
+    async getVoices() {
+        this.validateConfig();
+        
+        const token = await this._getAccessToken();
+        
+        const response = await fetch('https://texttospeech.googleapis.com/v1/voices', {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json'
+            }
+        });
+        
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({ error: { message: 'Unknown error' } }));
+            throw new Error(`Failed to fetch voices (${response.status}): ${errorData.error?.message || JSON.stringify(errorData)}`);
+        }
+        
+        const data = await response.json();
+        return data.voices
+            .filter(v => v.languageCodes.some(lc => lc.startsWith('en')))
+            .map(v => ({
+                id: v.name,
+                name: v.name.split('-').pop(),
+                description: `${v.ssmlGender} - ${v.languageCodes.join(', ')}`
+            }));
+    }
+
+    /**
+     * Extract language code from voice name if not specified
+     */
+    _getLanguageFromVoice(voice) {
+        // Voice names like "en-US-Chirp3-HD-Leda" start with language code
+        const match = voice.match(/^([a-z]{2}-[A-Z]{2})/);
+        return match ? match[1] : DEFAULT_LANGUAGE;
+    }
+
+    async generateAudio(text, settings = {}) {
+        this.validateConfig();
+        
+        const normalizedSettings = this.normalizeSettings(settings);
+        const defaults = this.getDefaultSettings();
+        
+        const voice = normalizedSettings.voice || defaults.voice;
+        const language = normalizedSettings.language || this._getLanguageFromVoice(voice);
+        const speed = parseFloat(normalizedSettings.speed) || defaults.speed;
+        const pitch = parseFloat(normalizedSettings.pitch) || defaults.pitch;
+        
+        // Validate speed
+        if (speed < 0.25 || speed > 4.0) {
+            throw new Error(`Speed must be between 0.25 and 4.0, got ${speed}`);
+        }
+        
+        // Validate pitch
+        if (pitch < -20 || pitch > 20) {
+            throw new Error(`Pitch must be between -20 and 20, got ${pitch}`);
+        }
+        
+        const token = await this._getAccessToken();
+        
+        const requestBody = {
+            input: { text },
+            voice: {
+                languageCode: language,
+                name: voice
+            },
+            audioConfig: {
+                audioEncoding: 'MP3',
+                speakingRate: speed,
+                pitch: pitch
+            }
+        };
+        
+        let response;
+        try {
+            response = await fetch('https://texttospeech.googleapis.com/v1/text:synthesize', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(requestBody)
+            });
+        } catch (fetchError) {
+            const cause = fetchError.cause ? `: ${fetchError.cause.message || fetchError.cause.code}` : '';
+            throw new Error(`Network error connecting to Google Cloud TTS API${cause}. Check your internet connection.`);
+        }
+        
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({ error: { message: 'Unknown error' } }));
+            throw new Error(`Google Cloud TTS API error (${response.status}): ${errorData.error?.message || JSON.stringify(errorData)}`);
+        }
+        
+        const data = await response.json();
+        
+        // Google returns base64-encoded audio
+        if (!data.audioContent) {
+            throw new Error('No audio content in response');
+        }
+        
+        return Buffer.from(data.audioContent, 'base64');
+    }
+}

package/framework/scripts/tts-providers/index.js

@@ -0,0 +1,158 @@
+/**
+ * TTS Provider Registry
+ * 
+ * Manages available TTS providers and handles provider selection.
+ * 
+ * Provider Selection Priority:
+ *   1. TTS_PROVIDER environment variable (explicit selection)
+ *   2. Auto-detect based on available API keys
+ *   3. Default to deepgram
+ * 
+ * Environment Variables:
+ *   TTS_PROVIDER - Explicit provider selection: elevenlabs, openai, azure
+ */
+
+import { ElevenLabsProvider } from './elevenlabs-provider.js';
+import { OpenAIProvider } from './openai-provider.js';
+import { AzureProvider } from './azure-provider.js';
+import { GoogleProvider } from './google-provider.js';
+import { DeepgramProvider } from './deepgram-provider.js';
+
+// Provider registry
+const PROVIDERS = {
+    elevenlabs: ElevenLabsProvider,
+    openai: OpenAIProvider,
+    azure: AzureProvider,
+    google: GoogleProvider,
+    deepgram: DeepgramProvider
+};
+
+// Provider aliases for convenience
+const PROVIDER_ALIASES = {
+    '11labs': 'elevenlabs',
+    'eleven': 'elevenlabs',
+    'gpt': 'openai',
+    'chatgpt': 'openai',
+    'microsoft': 'azure',
+    'cognitive': 'azure',
+    'chirp': 'google',
+    'gcloud': 'google',
+    'googlecloud': 'google',
+    'aura': 'deepgram'
+};
+
+/**
+ * Get a provider instance by name
+ * @param {string} name - Provider name or alias
+ * @param {Object} config - Optional provider configuration
+ * @returns {BaseTTSProvider}
+ */
+export function getProvider(name, config = {}) {
+    // Resolve aliases
+    const resolvedName = PROVIDER_ALIASES[name?.toLowerCase()] || name?.toLowerCase();
+    
+    const ProviderClass = PROVIDERS[resolvedName];
+    if (!ProviderClass) {
+        const available = Object.keys(PROVIDERS).join(', ');
+        throw new Error(`Unknown TTS provider '${name}'. Available providers: ${available}`);
+    }
+    
+    return new ProviderClass(config);
+}
+
+/**
+ * Auto-detect the best available provider based on configured API keys
+ * @returns {string|null} Provider name or null if none configured
+ */
+export function detectProvider() {
+    // Check each provider's required env vars
+    if (process.env.ELEVENLABS_API_KEY) {
+        return 'elevenlabs';
+    }
+    if (process.env.OPENAI_API_KEY) {
+        return 'openai';
+    }
+    if (process.env.AZURE_SPEECH_KEY && process.env.AZURE_SPEECH_REGION) {
+        return 'azure';
+    }
+    if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+        return 'google';
+    }
+    if (process.env.DEEPGRAM_API_KEY) {
+        return 'deepgram';
+    }
+    return null;
+}
+
+/**
+ * Get the active provider based on environment configuration
+ * @param {Object} config - Optional provider configuration
+ * @returns {BaseTTSProvider}
+ */
+export function getActiveProvider(config = {}) {
+    // 1. Explicit selection via TTS_PROVIDER
+    let providerName = process.env.TTS_PROVIDER;
+    
+    // 2. Auto-detect from available API keys
+    if (!providerName) {
+        providerName = detectProvider();
+    }
+    
+    // 3. Default to deepgram
+    if (!providerName) {
+        providerName = 'deepgram';
+    }
+    
+    return getProvider(providerName, config);
+}
+
+/**
+ * List all available providers with their configuration status
+ * @returns {Array<{name: string, configured: boolean, envVars: Array}>}
+ */
+export function listProviders() {
+    return Object.entries(PROVIDERS).map(([name, ProviderClass]) => {
+        const envVars = ProviderClass.getRequiredEnvVars();
+        const configured = envVars
+            .filter(v => v.required)
+            .every(v => !!process.env[v.name]);
+        
+        return {
+            name,
+            configured,
+            envVars
+        };
+    });
+}
+
+/**
+ * Print provider configuration help
+ * @param {boolean} verbose - Include all env vars, not just required
+ */
+export function printProviderHelp(verbose = false) {
+    console.warn('\n📢 Available TTS Providers:\n');
+    
+    for (const [name, ProviderClass] of Object.entries(PROVIDERS)) {
+        const envVars = ProviderClass.getRequiredEnvVars();
+        const requiredVars = envVars.filter(v => v.required);
+        const configured = requiredVars.every(v => !!process.env[v.name]);
+        
+        const status = configured ? '✅' : '❌';
+        console.warn(`   ${status} ${name}`);
+        
+        if (verbose || !configured) {
+            for (const v of envVars) {
+                const isSet = !!process.env[v.name];
+                const required = v.required ? '(required)' : '(optional)';
+                const setStatus = isSet ? '✓' : '✗';
+                console.warn(`      ${setStatus} ${v.name} ${required} - ${v.description}`);
+            }
+            console.warn('');
+        }
+    }
+    
+    console.warn('   Set TTS_PROVIDER=<name> to explicitly select a provider.\n');
+}
+
+// Export provider classes for direct use
+export { ElevenLabsProvider, OpenAIProvider, AzureProvider, GoogleProvider, DeepgramProvider };

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

@@ -0,0 +1,143 @@
+/**
+ * OpenAI TTS Provider
+ * 
+ * Uses OpenAI's Text-to-Speech API with natural-sounding voices.
+ * 
+ * Environment variables:
+ *   OPENAI_API_KEY  - Required: Your OpenAI API key
+ *   OPENAI_VOICE    - Optional: Default voice (alloy, echo, fable, onyx, nova, shimmer)
+ *   OPENAI_MODEL    - Optional: Model to use (tts-1, tts-1-hd)
+ * 
+ * Voice settings (per-narration):
+ *   voice  - Voice name (alloy, echo, fable, onyx, nova, shimmer)
+ *   model  - Model to use (tts-1 for speed, tts-1-hd for quality)
+ *   speed  - Speed multiplier (0.25-4.0, default: 1.0)
+ */
+
+import { BaseTTSProvider } from './base-provider.js';
+
+// Default settings
+const DEFAULT_VOICE = 'alloy';
+const DEFAULT_MODEL = 'tts-1';
+const DEFAULT_SPEED = 1.0;
+
+// Available voices
+const AVAILABLE_VOICES = [
+    { id: 'alloy', name: 'Alloy', description: 'Neutral and balanced' },
+    { id: 'echo', name: 'Echo', description: 'Warm and conversational' },
+    { id: 'fable', name: 'Fable', description: 'Expressive and British-accented' },
+    { id: 'onyx', name: 'Onyx', description: 'Deep and authoritative' },
+    { id: 'nova', name: 'Nova', description: 'Friendly and upbeat' },
+    { id: 'shimmer', name: 'Shimmer', description: 'Clear and pleasant' }
+];
+
+export class OpenAIProvider extends BaseTTSProvider {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'openai';
+        this.apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+    }
+
+    static getRequiredEnvVars() {
+        return [
+            { name: 'OPENAI_API_KEY', required: true, description: 'OpenAI API key' },
+            { name: 'OPENAI_VOICE', required: false, description: 'Default voice (alloy, echo, fable, onyx, nova, shimmer)' },
+            { name: 'OPENAI_MODEL', required: false, description: 'Model (tts-1 or tts-1-hd)' }
+        ];
+    }
+
+    validateConfig() {
+        if (!this.apiKey) {
+            throw new Error('OPENAI_API_KEY not set in environment or .env file');
+        }
+        
+        const trimmedKey = this.apiKey.trim();
+        if (trimmedKey !== this.apiKey || !trimmedKey) {
+            throw new Error('OPENAI_API_KEY contains invalid whitespace - check your .env file');
+        }
+    }
+
+    getDefaultVoiceId() {
+        return process.env.OPENAI_VOICE || DEFAULT_VOICE;
+    }
+
+    getDefaultSettings() {
+        return {
+            voice: this.getDefaultVoiceId(),
+            model: process.env.OPENAI_MODEL || DEFAULT_MODEL,
+            speed: DEFAULT_SPEED
+        };
+    }
+
+    normalizeSettings(settings) {
+        const normalized = { ...settings };
+        
+        // Map 'voice_id' to 'voice' (from ElevenLabs format)
+        if (settings.voice_id && !settings.voice) {
+            normalized.voice = settings.voice_id;
+            delete normalized.voice_id;
+        }
+        
+        // Map 'model_id' to 'model'
+        if (settings.model_id && !settings.model) {
+            normalized.model = settings.model_id;
+            delete normalized.model_id;
+        }
+        
+        return normalized;
+    }
+
+    async getVoices() {
+        // OpenAI voices are fixed, no API call needed
+        return AVAILABLE_VOICES;
+    }
+
+    async generateAudio(text, settings = {}) {
+        this.validateConfig();
+        
+        const normalizedSettings = this.normalizeSettings(settings);
+        const defaults = this.getDefaultSettings();
+        
+        const voice = normalizedSettings.voice || defaults.voice;
+        const model = normalizedSettings.model || defaults.model;
+        const speed = parseFloat(normalizedSettings.speed) || defaults.speed;
+        
+        // Validate voice
+        if (!AVAILABLE_VOICES.some(v => v.id === voice)) {
+            throw new Error(`Invalid voice '${voice}'. Available: ${AVAILABLE_VOICES.map(v => v.id).join(', ')}`);
+        }
+        
+        // Validate speed
+        if (speed < 0.25 || speed > 4.0) {
+            throw new Error(`Speed must be between 0.25 and 4.0, got ${speed}`);
+        }
+        
+        let response;
+        try {
+            response = await fetch('https://api.openai.com/v1/audio/speech', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey.trim()}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    model,
+                    input: text,
+                    voice,
+                    speed,
+                    response_format: 'mp3'
+                })
+            });
+        } catch (fetchError) {
+            const cause = fetchError.cause ? `: ${fetchError.cause.message || fetchError.cause.code}` : '';
+            throw new Error(`Network error connecting to OpenAI API${cause}. Check your internet connection.`);
+        }
+        
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({ error: { message: 'Unknown error' } }));
+            throw new Error(`OpenAI API error (${response.status}): ${errorData.error?.message || JSON.stringify(errorData)}`);
+        }
+        
+        return Buffer.from(await response.arrayBuffer());
+    }
+}

package/framework/version.json

@@ -0,0 +1,63 @@
+{
+  "version": "0.1.0",
+  "name": "SCORM 2004 4th Edition Framework",
+  "description": "Production-ready SCORM framework with modular architecture and advanced features",
+  "released": "2025-11-07",
+  "scorm_version": "SCORM 2004 4th Edition",
+  "compatibility": {
+    "minimum_course_version": "0.1.0",
+    "breaking_changes": [
+      "StateManager now owns all SCORM persistence; PersistenceManager removed"
+    ]
+  },
+  "components": {
+    "core": [
+      "pipwerks.js",
+      "runtime.js",
+      "event-bus.js",
+      "course-app.js",
+      "accessibility-enhancements.js"
+    ],
+    "managers": [
+      "state-manager.js",
+      "navigation-manager.js",
+      "objective-manager.js",
+      "interaction-manager.js",
+      "accessibility-manager.js",
+      "assessment-manager.js"
+    ],
+    "utilities": [
+      "utilities.js",
+      "feedback-system.js"
+    ],
+    "components": [
+      "ui-components/index.js",
+      "ui-components/modal.js",
+      "ui-components/dropdown.js",
+      "ui-components/notifications.js",
+      "ui-components/tabs.js",
+      "interactions/"
+    ]
+  },
+  "features": [
+    "SCORM 2004 4th Edition compliant",
+    "Sequential assessment navigator",
+    "Interactive question types (multiple-choice, fill-in, numeric, hotspot, drag-drop, true-false)",
+    "SCORM-based state persistence",
+    "Accessibility features (WCAG 2.1 AA)",
+    "Adaptive feedback system",
+    "Course gating and navigation rules",
+    "Time tracking and analytics",
+    "Offline mode support",
+    "Assessment security features"
+  ],
+  "upgrade": {
+    "instructions": "See UPGRADE_GUIDE.md for detailed upgrade instructions",
+    "backup_recommended": true,
+    "test_before_deployment": true
+  },
+  "support": {
+    "documentation": "https://github.com/svincent/scorm-template",
+    "issues": "https://github.com/svincent/scorm-template/issues"
+  }
+}