agentic-qe 2.4.0 → 2.5.0

package/dist/mcp/tools/qe/accessibility/webvtt-generator.d.ts

@@ -0,0 +1,193 @@
+/**
+ * WebVTT Caption File Generator
+ *
+ * Generate Web Video Text Tracks (WebVTT) caption files for video accessibility
+ * Version: Based on W3C WebVTT Specification (W3C Candidate Recommendation)
+ *
+ * Purpose: Generate properly formatted caption files with AI-assisted transcription
+ * Reference: https://www.w3.org/TR/webvtt1/
+ *
+ * WCAG Success Criteria:
+ * - 1.2.2 Captions (Prerecorded) - Level A
+ * - 1.2.4 Captions (Live) - Level AA
+ * - 1.2.6 Sign Language (Prerecorded) - Level AAA
+ */
+export interface WebVTTCue {
+    /** Unique identifier for the cue (optional) */
+    identifier?: string;
+    /** Start time in seconds */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+    /** Caption text (can include formatting tags) */
+    text: string;
+    /** Speaker name (optional, for dialogue) */
+    speaker?: string;
+    /** Cue settings (position, alignment, etc.) */
+    settings?: {
+        vertical?: 'rl' | 'lr';
+        line?: number | 'auto';
+        position?: number;
+        size?: number;
+        align?: 'start' | 'center' | 'end' | 'left' | 'right';
+    };
+}
+export interface WebVTTStyle {
+    selector: string;
+    properties: Record<string, string>;
+}
+export interface WebVTTMetadata {
+    title?: string;
+    language?: string;
+    description?: string;
+    [key: string]: string | undefined;
+}
+export interface WebVTTFile {
+    metadata?: WebVTTMetadata;
+    styles?: WebVTTStyle[];
+    cues: WebVTTCue[];
+}
+export interface WebVTTGeneratorOptions {
+    /** Include NOTE blocks with metadata */
+    includeNotes?: boolean;
+    /** Validate caption best practices (length, reading speed) */
+    validateBestPractices?: boolean;
+    /** Maximum characters per line (default: 37) */
+    maxCharsPerLine?: number;
+    /** Maximum lines per cue (default: 2) */
+    maxLinesPerCue?: number;
+    /** Target reading speed in words per minute (default: 160) */
+    targetWPM?: number;
+}
+export interface CaptionValidationIssue {
+    cueIndex: number;
+    severity: 'error' | 'warning';
+    issue: string;
+    suggestion: string;
+}
+/**
+ * Format time in WebVTT timestamp format (HH:MM:SS.mmm)
+ */
+export declare function formatWebVTTTimestamp(seconds: number): string;
+/**
+ * Parse WebVTT timestamp to seconds
+ */
+export declare function parseWebVTTTimestamp(timestamp: string): number;
+/**
+ * Generate WebVTT file content from cues
+ */
+export declare function generateWebVTT(file: WebVTTFile, options?: WebVTTGeneratorOptions): string;
+/**
+ * Validate WebVTT file against best practices
+ */
+export declare function validateWebVTT(file: WebVTTFile, options?: WebVTTGeneratorOptions): CaptionValidationIssue[];
+/**
+ * Create a WebVTT file from a transcript
+ *
+ * @param transcript - Array of transcript segments with timestamps
+ * @param options - Generation options
+ */
+export declare function createWebVTTFromTranscript(transcript: Array<{
+    text: string;
+    startTime: number;
+    endTime: number;
+    speaker?: string;
+}>, options?: WebVTTGeneratorOptions): WebVTTFile;
+/**
+ * Common caption templates and patterns
+ */
+export declare const CAPTION_TEMPLATES: {
+    /**
+     * Generate sound effect caption
+     */
+    soundEffect: (description: string, startTime: number, endTime: number) => WebVTTCue;
+    /**
+     * Generate music caption
+     */
+    music: (description: string, startTime: number, endTime: number) => WebVTTCue;
+    /**
+     * Generate speaker change caption
+     */
+    dialogue: (speaker: string, text: string, startTime: number, endTime: number) => WebVTTCue;
+    /**
+     * Generate atmosphere/ambient sound caption
+     */
+    ambient: (description: string, startTime: number, endTime: number) => WebVTTCue;
+};
+/**
+ * WebVTT style presets for common use cases
+ */
+export declare const WEBVTT_STYLE_PRESETS: {
+    /**
+     * High contrast style for better visibility
+     */
+    highContrast: () => WebVTTStyle[];
+    /**
+     * Speaker differentiation with colors
+     */
+    speakerColors: () => WebVTTStyle[];
+    /**
+     * Sound effect styling
+     */
+    soundEffects: () => WebVTTStyle[];
+};
+/**
+ * AI-Assisted Caption Generation Helpers
+ */
+export interface AITranscriptionSegment {
+    text: string;
+    startTime: number;
+    endTime: number;
+    confidence: number;
+    speaker?: string;
+}
+/**
+ * Generate caption generation prompt for AI services
+ *
+ * @param videoMetadata - Video information
+ * @returns Prompt for AI transcription services
+ */
+export declare function generateAICaptionPrompt(videoMetadata: {
+    title?: string;
+    duration?: number;
+    topic?: string;
+    language?: string;
+}): string;
+/**
+ * Convert AI transcription to WebVTT file
+ */
+export declare function convertAITranscriptionToWebVTT(segments: AITranscriptionSegment[], options?: WebVTTGeneratorOptions): WebVTTFile;
+/**
+ * Caption quality scoring
+ */
+export declare function scoreCaptionQuality(file: WebVTTFile): {
+    score: number;
+    breakdown: {
+        timing: number;
+        readability: number;
+        completeness: number;
+        formatting: number;
+    };
+    recommendations: string[];
+};
+/**
+ * Export WebVTT file to disk
+ */
+export declare function saveWebVTT(file: WebVTTFile, options?: WebVTTGeneratorOptions): {
+    content: string;
+    filename: string;
+};
+/**
+ * Example usage and best practices
+ */
+export declare const WEBVTT_EXAMPLES: {
+    /**
+     * Basic video with dialogue
+     */
+    simpleDialogue: () => WebVTTFile;
+    /**
+     * Educational video with sound effects
+     */
+    educational: () => WebVTTFile;
+};
+//# sourceMappingURL=webvtt-generator.d.ts.map

package/dist/mcp/tools/qe/accessibility/webvtt-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webvtt-generator.d.ts","sourceRoot":"","sources":["../../../../../src/mcp/tools/qe/accessibility/webvtt-generator.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/qe/accessibility/webvtt-generator.js

@@ -0,0 +1,511 @@
+"use strict";
+/**
+ * WebVTT Caption File Generator
+ *
+ * Generate Web Video Text Tracks (WebVTT) caption files for video accessibility
+ * Version: Based on W3C WebVTT Specification (W3C Candidate Recommendation)
+ *
+ * Purpose: Generate properly formatted caption files with AI-assisted transcription
+ * Reference: https://www.w3.org/TR/webvtt1/
+ *
+ * WCAG Success Criteria:
+ * - 1.2.2 Captions (Prerecorded) - Level A
+ * - 1.2.4 Captions (Live) - Level AA
+ * - 1.2.6 Sign Language (Prerecorded) - Level AAA
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBVTT_EXAMPLES = exports.WEBVTT_STYLE_PRESETS = exports.CAPTION_TEMPLATES = void 0;
+exports.formatWebVTTTimestamp = formatWebVTTTimestamp;
+exports.parseWebVTTTimestamp = parseWebVTTTimestamp;
+exports.generateWebVTT = generateWebVTT;
+exports.validateWebVTT = validateWebVTT;
+exports.createWebVTTFromTranscript = createWebVTTFromTranscript;
+exports.generateAICaptionPrompt = generateAICaptionPrompt;
+exports.convertAITranscriptionToWebVTT = convertAITranscriptionToWebVTT;
+exports.scoreCaptionQuality = scoreCaptionQuality;
+exports.saveWebVTT = saveWebVTT;
+/**
+ * Format time in WebVTT timestamp format (HH:MM:SS.mmm)
+ */
+function formatWebVTTTimestamp(seconds) {
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+    const milliseconds = Math.floor((seconds % 1) * 1000);
+    return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(secs).padStart(2, '0')}.${String(milliseconds).padStart(3, '0')}`;
+}
+/**
+ * Parse WebVTT timestamp to seconds
+ */
+function parseWebVTTTimestamp(timestamp) {
+    const parts = timestamp.split(':');
+    const hours = parseInt(parts[0], 10);
+    const minutes = parseInt(parts[1], 10);
+    const secondsParts = parts[2].split('.');
+    const seconds = parseInt(secondsParts[0], 10);
+    const milliseconds = parseInt(secondsParts[1] || '0', 10);
+    return hours * 3600 + minutes * 60 + seconds + milliseconds / 1000;
+}
+/**
+ * Format cue settings object to WebVTT settings string
+ */
+function formatCueSettings(settings) {
+    if (!settings)
+        return '';
+    const parts = [];
+    if (settings.vertical) {
+        parts.push(`vertical:${settings.vertical}`);
+    }
+    if (settings.line !== undefined) {
+        parts.push(`line:${settings.line}`);
+    }
+    if (settings.position !== undefined) {
+        parts.push(`position:${settings.position}%`);
+    }
+    if (settings.size !== undefined) {
+        parts.push(`size:${settings.size}%`);
+    }
+    if (settings.align) {
+        parts.push(`align:${settings.align}`);
+    }
+    return parts.length > 0 ? ' ' + parts.join(' ') : '';
+}
+/**
+ * Generate WebVTT file content from cues
+ */
+function generateWebVTT(file, options = {}) {
+    let content = 'WEBVTT\n';
+    // Add metadata as NOTE blocks
+    if (options.includeNotes && file.metadata) {
+        content += '\n';
+        Object.entries(file.metadata).forEach(([key, value]) => {
+            if (value) {
+                content += `NOTE ${key}\n${value}\n\n`;
+            }
+        });
+    }
+    // Add STYLE blocks
+    if (file.styles && file.styles.length > 0) {
+        content += '\nSTYLE\n';
+        file.styles.forEach(style => {
+            content += `${style.selector} {\n`;
+            Object.entries(style.properties).forEach(([prop, value]) => {
+                content += `  ${prop}: ${value};\n`;
+            });
+            content += '}\n';
+        });
+        content += '\n';
+    }
+    // Add cues
+    file.cues.forEach((cue, index) => {
+        // Optional identifier
+        if (cue.identifier) {
+            content += `${cue.identifier}\n`;
+        }
+        // Timestamp line
+        const startTimestamp = formatWebVTTTimestamp(cue.startTime);
+        const endTimestamp = formatWebVTTTimestamp(cue.endTime);
+        const settings = formatCueSettings(cue.settings);
+        content += `${startTimestamp} --> ${endTimestamp}${settings}\n`;
+        // Caption text
+        let text = cue.text;
+        // Add speaker identification if provided
+        if (cue.speaker) {
+            text = `<v ${cue.speaker}>${text}</v>`;
+        }
+        content += `${text}\n\n`;
+    });
+    return content.trim();
+}
+/**
+ * Validate WebVTT file against best practices
+ */
+function validateWebVTT(file, options = {}) {
+    const issues = [];
+    const maxCharsPerLine = options.maxCharsPerLine || 37;
+    const maxLinesPerCue = options.maxLinesPerCue || 2;
+    const targetWPM = options.targetWPM || 160;
+    const maxWPM = 180; // Maximum comfortable reading speed
+    file.cues.forEach((cue, index) => {
+        // Check cue duration
+        const duration = cue.endTime - cue.startTime;
+        if (duration < 1) {
+            issues.push({
+                cueIndex: index,
+                severity: 'warning',
+                issue: 'Cue duration less than 1 second',
+                suggestion: 'Captions should remain on screen for at least 1 second for readability'
+            });
+        }
+        // Check overlapping cues
+        if (index > 0) {
+            const previousCue = file.cues[index - 1];
+            if (cue.startTime < previousCue.endTime) {
+                issues.push({
+                    cueIndex: index,
+                    severity: 'error',
+                    issue: 'Cue overlaps with previous cue',
+                    suggestion: `Start time ${formatWebVTTTimestamp(cue.startTime)} is before previous cue end time ${formatWebVTTTimestamp(previousCue.endTime)}`
+                });
+            }
+        }
+        // Remove speaker tags and formatting tags for text analysis
+        const plainText = cue.text
+            .replace(/<v\s+[^>]+>/g, '')
+            .replace(/<\/v>/g, '')
+            .replace(/<[^>]+>/g, '');
+        // Check line length
+        const lines = plainText.split('\n');
+        if (lines.length > maxLinesPerCue) {
+            issues.push({
+                cueIndex: index,
+                severity: 'warning',
+                issue: `Cue has ${lines.length} lines (max recommended: ${maxLinesPerCue})`,
+                suggestion: 'Split long captions into multiple cues for better readability'
+            });
+        }
+        lines.forEach((line, lineIndex) => {
+            if (line.length > maxCharsPerLine) {
+                issues.push({
+                    cueIndex: index,
+                    severity: 'warning',
+                    issue: `Line ${lineIndex + 1} has ${line.length} characters (max recommended: ${maxCharsPerLine})`,
+                    suggestion: 'Break long lines at natural phrase boundaries'
+                });
+            }
+        });
+        // Check reading speed
+        const wordCount = plainText.split(/\s+/).length;
+        const durationMinutes = duration / 60;
+        const wpm = wordCount / durationMinutes;
+        if (wpm > maxWPM) {
+            issues.push({
+                cueIndex: index,
+                severity: 'warning',
+                issue: `Reading speed is ${Math.round(wpm)} WPM (max comfortable: ${maxWPM} WPM)`,
+                suggestion: 'Increase cue duration or split into multiple cues'
+            });
+        }
+        // Check for empty captions
+        if (plainText.trim().length === 0) {
+            issues.push({
+                cueIndex: index,
+                severity: 'error',
+                issue: 'Empty caption text',
+                suggestion: 'Remove empty cue or add caption text'
+            });
+        }
+    });
+    return issues;
+}
+/**
+ * Create a WebVTT file from a transcript
+ *
+ * @param transcript - Array of transcript segments with timestamps
+ * @param options - Generation options
+ */
+function createWebVTTFromTranscript(transcript, options = {}) {
+    const maxCharsPerLine = options.maxCharsPerLine || 37;
+    const cues = transcript.map((segment, index) => {
+        // Smart line breaking at natural boundaries
+        const words = segment.text.split(' ');
+        const lines = [];
+        let currentLine = '';
+        words.forEach(word => {
+            const testLine = currentLine ? `${currentLine} ${word}` : word;
+            if (testLine.length <= maxCharsPerLine) {
+                currentLine = testLine;
+            }
+            else {
+                if (currentLine) {
+                    lines.push(currentLine);
+                }
+                currentLine = word;
+            }
+        });
+        if (currentLine) {
+            lines.push(currentLine);
+        }
+        // Join lines (max 2 lines per cue recommended)
+        const text = lines.slice(0, options.maxLinesPerCue || 2).join('\n');
+        return {
+            identifier: `cue-${index + 1}`,
+            startTime: segment.startTime,
+            endTime: segment.endTime,
+            text,
+            speaker: segment.speaker
+        };
+    });
+    return { cues };
+}
+/**
+ * Common caption templates and patterns
+ */
+exports.CAPTION_TEMPLATES = {
+    /**
+     * Generate sound effect caption
+     */
+    soundEffect: (description, startTime, endTime) => ({
+        startTime,
+        endTime,
+        text: `[${description}]`,
+        settings: { align: 'center' }
+    }),
+    /**
+     * Generate music caption
+     */
+    music: (description, startTime, endTime) => ({
+        startTime,
+        endTime,
+        text: `♪ ${description} ♪`,
+        settings: { align: 'center' }
+    }),
+    /**
+     * Generate speaker change caption
+     */
+    dialogue: (speaker, text, startTime, endTime) => ({
+        startTime,
+        endTime,
+        text,
+        speaker
+    }),
+    /**
+     * Generate atmosphere/ambient sound caption
+     */
+    ambient: (description, startTime, endTime) => ({
+        startTime,
+        endTime,
+        text: `(${description})`,
+        settings: { position: 50, align: 'center' }
+    })
+};
+/**
+ * WebVTT style presets for common use cases
+ */
+exports.WEBVTT_STYLE_PRESETS = {
+    /**
+     * High contrast style for better visibility
+     */
+    highContrast: () => [
+        {
+            selector: '::cue',
+            properties: {
+                'background-color': 'rgba(0, 0, 0, 0.9)',
+                'color': '#FFFFFF',
+                'font-size': '1.5em',
+                'font-family': 'Arial, sans-serif'
+            }
+        }
+    ],
+    /**
+     * Speaker differentiation with colors
+     */
+    speakerColors: () => [
+        {
+            selector: '::cue(v[voice="Speaker 1"])',
+            properties: {
+                'color': '#00CCFF'
+            }
+        },
+        {
+            selector: '::cue(v[voice="Speaker 2"])',
+            properties: {
+                'color': '#FFCC00'
+            }
+        },
+        {
+            selector: '::cue(v[voice="Speaker 3"])',
+            properties: {
+                'color': '#FF66CC'
+            }
+        }
+    ],
+    /**
+     * Sound effect styling
+     */
+    soundEffects: () => [
+        {
+            selector: '::cue(i)',
+            properties: {
+                'color': '#CCCCCC',
+                'font-style': 'italic'
+            }
+        }
+    ]
+};
+/**
+ * Generate caption generation prompt for AI services
+ *
+ * @param videoMetadata - Video information
+ * @returns Prompt for AI transcription services
+ */
+function generateAICaptionPrompt(videoMetadata) {
+    return `Generate accurate captions for a video with the following details:
+
+Title: ${videoMetadata.title || 'Untitled Video'}
+Duration: ${videoMetadata.duration ? formatWebVTTTimestamp(videoMetadata.duration) : 'Unknown'}
+Topic: ${videoMetadata.topic || 'General'}
+Language: ${videoMetadata.language || 'English'}
+
+Caption Requirements:
+- Maximum 37 characters per line
+- Maximum 2 lines per caption
+- Reading speed: 160-180 words per minute
+- Include speaker identification for dialogue
+- Mark sound effects with [brackets]
+- Mark music with ♪ symbols
+- Mark ambient sounds with (parentheses)
+- Ensure accurate timing synchronization
+- Follow WebVTT format specification
+
+Please provide:
+1. Timestamp (HH:MM:SS.mmm format)
+2. Speaker name (if applicable)
+3. Caption text with proper line breaks
+4. Confidence score (0-1)`;
+}
+/**
+ * Convert AI transcription to WebVTT file
+ */
+function convertAITranscriptionToWebVTT(segments, options = {}) {
+    const cues = segments.map((segment, index) => {
+        // Filter out low-confidence segments (you may want manual review)
+        if (segment.confidence < 0.8) {
+            console.warn(`Low confidence segment at ${formatWebVTTTimestamp(segment.startTime)}: ${segment.confidence}`);
+        }
+        return {
+            identifier: `ai-cue-${index + 1}`,
+            startTime: segment.startTime,
+            endTime: segment.endTime,
+            text: segment.text,
+            speaker: segment.speaker
+        };
+    });
+    const file = {
+        metadata: {
+            title: 'AI-Generated Captions',
+            description: 'Generated using AI transcription service'
+        },
+        cues
+    };
+    return file;
+}
+/**
+ * Caption quality scoring
+ */
+function scoreCaptionQuality(file) {
+    const issues = validateWebVTT(file, { validateBestPractices: true });
+    const errorCount = issues.filter(i => i.severity === 'error').length;
+    const warningCount = issues.filter(i => i.severity === 'warning').length;
+    // Scoring components (0-100)
+    let timing = 100;
+    let readability = 100;
+    let completeness = 100;
+    let formatting = 100;
+    const recommendations = [];
+    // Penalize for errors and warnings
+    timing -= errorCount * 10;
+    readability -= warningCount * 5;
+    // Check completeness (minimum 80% of expected cues)
+    if (file.cues.length === 0) {
+        completeness = 0;
+        recommendations.push('Add captions to the video');
+    }
+    // Check formatting
+    const hasSpeakers = file.cues.some(c => c.speaker);
+    if (!hasSpeakers && file.cues.length > 5) {
+        formatting -= 10;
+        recommendations.push('Consider adding speaker identification for dialogue');
+    }
+    // Overall score (weighted average)
+    const score = Math.max(0, Math.round(timing * 0.3 +
+        readability * 0.3 +
+        completeness * 0.2 +
+        formatting * 0.2));
+    if (score < 80) {
+        recommendations.push('Review and address validation issues for better quality');
+    }
+    if (errorCount > 0) {
+        recommendations.push('Fix critical errors (overlapping cues, empty captions)');
+    }
+    if (warningCount > 5) {
+        recommendations.push('Consider revising captions for better readability');
+    }
+    return {
+        score,
+        breakdown: {
+            timing: Math.max(0, timing),
+            readability: Math.max(0, readability),
+            completeness: Math.max(0, completeness),
+            formatting: Math.max(0, formatting)
+        },
+        recommendations
+    };
+}
+/**
+ * Export WebVTT file to disk
+ */
+function saveWebVTT(file, options = {}) {
+    const content = generateWebVTT(file, options);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+    const filename = `captions-${timestamp}.vtt`;
+    return { content, filename };
+}
+/**
+ * Example usage and best practices
+ */
+exports.WEBVTT_EXAMPLES = {
+    /**
+     * Basic video with dialogue
+     */
+    simpleDialogue: () => ({
+        metadata: {
+            title: 'Product Demo Video',
+            language: 'en'
+        },
+        cues: [
+            {
+                identifier: 'intro',
+                startTime: 0,
+                endTime: 3.5,
+                text: 'Welcome to our product demo.',
+                speaker: 'Narrator'
+            },
+            {
+                identifier: 'feature-1',
+                startTime: 3.5,
+                endTime: 7.0,
+                text: 'Today we\'ll show you\nthree amazing features.',
+                speaker: 'Narrator'
+            },
+            exports.CAPTION_TEMPLATES.music('Upbeat background music', 7.0, 10.0)
+        ]
+    }),
+    /**
+     * Educational video with sound effects
+     */
+    educational: () => ({
+        metadata: {
+            title: 'Science Experiment',
+            language: 'en',
+            description: 'Chemistry demonstration with captions'
+        },
+        styles: exports.WEBVTT_STYLE_PRESETS.highContrast(),
+        cues: [
+            {
+                startTime: 0,
+                endTime: 4,
+                text: 'First, we add the sodium chloride\nto the beaker.',
+                speaker: 'Professor'
+            },
+            exports.CAPTION_TEMPLATES.soundEffect('Bubbling sounds', 4, 6),
+            {
+                startTime: 6,
+                endTime: 10,
+                text: 'Notice the chemical reaction\noccurring.',
+                speaker: 'Professor'
+            }
+        ]
+    })
+};
+//# sourceMappingURL=webvtt-generator.js.map