Skip to content

TRANSCRIPTION_SYSTEM.md

Latest commit

 

History

History
269 lines (198 loc) · 8.15 KB

TRANSCRIPTION_SYSTEM.md

File metadata and controls

269 lines (198 loc) · 8.15 KB

🎙️ Sistema de Transcripción Automática con Groq Whisper

📋 Descripción

El sistema transcribe automáticamente todos los videos subidos usando Groq Whisper Large V3, proporcionando transcripciones con timestamps precisos que permiten análisis contextuales profundos.

🔄 Flujo de Trabajo

1. Subida de Video

Profesor sube video → R2 → Base de datos → Transcripción automática inicia

2. Proceso de Transcripción

  1. Video se guarda en R2 con estado transcript_status: 'pending'
  2. Sistema descarga el video
  3. Groq Whisper procesa el audio (transcript_status: 'processing')
  4. Transcripción se guarda con timestamps (transcript_status: 'completed')
  5. Si falla: transcript_status: 'failed'

3. Análisis con Contexto

Cuando se genera un reporte de métricas:

Métricas del estudiante + Transcripción con timestamps → LLM → Análisis contextual

📊 Ejemplo de Análisis Contextual

Sin Transcripción:

"El estudiante pausó el video 12 veces, sugiere dificultad de comprensión"

Con Transcripción:

"El estudiante pausó 8 veces entre los minutos 3:20-4:45 donde se explicaba el concepto de recursividad en funciones. Recomendación: reforzar este tema con ejercicios prácticos y ejemplos visuales."

🎯 Formato de Transcripción

{
  "transcript": [
    {
      "start": 0.0,
      "end": 5.2,
      "text": "Hola estudiantes, hoy vamos a aprender sobre algoritmos"
    },
    {
      "start": 5.2,
      "end": 10.8,
      "text": "Un algoritmo es una secuencia de pasos para resolver un problema"
    }
  ],
  "transcript_status": "completed",
  "transcribed_at": "2026-02-20T10:30:00Z"
}

⚙️ Configuración

Variables de Entorno (.env.local)

GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La misma API key usada para análisis de métricas funciona para transcripción.

🚀 Características de Groq Whisper

Característica Valor
Modelo Whisper Large V3
Idioma Español (auto-detectado)
Velocidad ~5 min de video en 10 segundos
Precisión Alta (modelo más avanzado)
Timestamps Automáticos por segmento
Costo GRATIS (con límites)

Límites del Plan Gratuito

  • Audio: 100,000 segundos/mes (~1,666 minutos)
  • Rate limit: 20 requests/minuto
  • Tamaño máximo: 25 MB por archivo

Suficiente para: ~55 videos de 30 minutos cada uno al mes.

📝 Estados de Transcripción

Estado Descripción
pending Video subido, transcripción no iniciada
processing Whisper procesando el audio
completed Transcripción completada exitosamente
failed Hubo un error en la transcripción

🔧 Funciones Disponibles

Server Actions (lib/actions/transcription.ts)

transcribeVideo(videoId, audioUrl)

Transcribe un video usando Groq Whisper.

const result = await transcribeVideo(videoId, videoUrl);
// result: { success: true, transcript: [...], fullText: "..." }

getVideoTranscript(videoId)

Obtiene la transcripción guardada de un video.

const { transcript, status } = await getVideoTranscript(videoId);

retryTranscription(videoId)

Reintenta la transcripción de un video que falló.

const result = await retryTranscription(videoId);

Utilidades (lib/utils/transcript.ts)

Funciones helper para trabajar con transcripciones (client/server side):

findTranscriptAtTime(transcript, seconds)

Encuentra qué se estaba diciendo en un timestamp específico.

import { findTranscriptAtTime } from '@/lib/utils/transcript';

const segment = findTranscriptAtTime(transcript, 125); // 2:05
// { start: 120, end: 130, text: "explicación del concepto..." }

getTranscriptContext(transcript, seconds, contextSeconds)

Obtiene el contexto de transcripción alrededor de un timestamp.

import { getTranscriptContext } from '@/lib/utils/transcript';

const context = getTranscriptContext(transcript, 125, 10);
// Retorna segmentos 10 segundos antes y después

formatTranscriptTime(seconds)

Formatea segundos a formato MM:SS o HH:MM:SS.

import { formatTranscriptTime } from '@/lib/utils/transcript';

formatTranscriptTime(125); // "2:05"
formatTranscriptTime(3665); // "1:01:05"

transcriptToPlainText(transcript)

Convierte transcripción a texto plano sin timestamps.

import { transcriptToPlainText } from '@/lib/utils/transcript';

const text = transcriptToPlainText(transcript);
// "Hola estudiantes Un algoritmo es una secuencia..."

transcriptToTimestampedText(transcript)

Convierte transcripción a texto con timestamps formateados.

import { transcriptToTimestampedText } from '@/lib/utils/transcript';

const text = transcriptToTimestampedText(transcript);
// "[0:00-0:05] Hola estudiantes
// [0:05-0:10] Un algoritmo es..."

🎓 Uso en Análisis de Métricas

El sistema automáticamente incluye transcripciones en el análisis:

// En buildAnalysisPrompt()
if (hasTranscript) {
  // Incluye transcripción con timestamps en el prompt
  // LLM puede correlacionar métricas con contenido exacto
}

Ejemplo de Prompt al LLM:

### Video 1: Introducción a Python

Métricas:
- Pausas: 15
- Retrocesos: 8 
- Adelantos: 2

Contenido del Video (Transcripción):
[00:00-00:05] Hola estudiantes, hoy aprenderemos Python
[00:05-00:15] Python es un lenguaje de programación interpretado
[03:20-03:45] Las funciones se definen con la palabra def
[03:45-04:15] Veamos un ejemplo de recursividad...
[04:15-04:30] La recursividad puede ser confusa al principio

ANÁLISIS CONTEXTUAL: Con esta transcripción, identifica qué 
temas causaron más pausas/retrocesos y proporciona recomendaciones
específicas de minutos a reforzar.

🐛 Solución de Problemas

Error: "Cannot download video"

Causa: El video en R2 no es accesible públicamente o la URL expiró.

Solución: Verifica que la URL de R2 permita acceso temporal o usa signed URLs.

Error: "Audio too long"

Causa: El video excede los límites de Groq (25 MB o límites de cuenta).

Solución:

  • Comprime el video antes de subir
  • Divide videos largos en partes

Estado "failed" permanente

Causa: Error en el procesamiento, formato no soportado, o problema de red.

Solución:

  1. Verifica logs del servidor
  2. Intenta retryTranscription(videoId)
  3. Revisa que el formato sea compatible (MP4, MKV, MOV, etc.)

Transcripción incorrecta o con errores

Causa: Audio de baja calidad, ruido de fondo, o idioma no detectado correctamente.

Solución:

  • Mejora calidad de audio en grabación
  • Reduce ruido de fondo
  • Especifica idioma manualmente en transcribeVideo()

📈 Mejores Prácticas

Para Profesores:

  1. ✅ Habla claro: Mejor calidad de audio = mejor transcripción
  2. ✅ Minimiza ruido: Graba en ambiente silencioso
  3. ✅ Estructura bien: Introduce temas claramente para mejor análisis
  4. ✅ Revisa estado: Verifica que la transcripción se completó

Para el Sistema:

  1. ✅ Transcripción en background: No bloquea la carga del video
  2. ✅ Reintentos automáticos: Si falla, permite reintentar manualmente
  3. ✅ Manejo de errores: Estados claros para debugging
  4. ✅ Timestamps precisos: Permite análisis granular

🔮 Futuras Mejoras

  • UI para ver transcripciones: Panel para profesores con texto completo
  • Edición manual: Permitir corregir errores en transcripción
  • Búsqueda por contenido: Buscar videos por lo que se dice en ellos
  • Subtítulos automáticos: Generar SRT/VTT desde transcript
  • Detección de capítulos: Identificar secciones automáticamente
  • Análisis de sentimiento: Detectar tono/énfasis en explicaciones
  • Resúmenes automáticos: Generar TL;DR del video con LLM

📚 Referencias

¿Problemas? Revisa los logs del servidor o contacta al equipo de desarrollo.