El Atributo ONCUECHANGE

El atributo oncuechange es un evento de JavaScript que se activa cuando un cue (segmento de tiempo de texto) en una pista de texto (subtítulos, descripciones, etc.) cambia durante la reproducción de elementos multimedia. Es especialmente útil para crear experiencias interactivas sincronizadas con contenido de audio o video, como subtítulos dinámicos, cuestionarios en tiempo real, o efectos visuales vinculados a momentos específicos.

¿Qué es un "cue"?

Un cue es un fragmento de texto con un intervalo de tiempo definido en una pista de texto (archivo WebVTT). Por ejemplo:

WEBVTT

00:00:02.000 --> 00:00:05.000
¡Bienvenidos al tutorial!

00:00:06.000 --> 00:00:10.000
Hoy aprenderemos sobre el evento oncuechange.

¿Dónde se aplica?

Funciona en elementos que admiten pistas de texto:

• <video> con <track>

• <audio> con <track> (aunque menos común)

Sintaxis básica

Como atributo HTML:

<video controls>
  <source src="video.mp4" type="video/mp4">
  <track 
    src="subtitulos.vtt" 
    kind="subtitles" 
    srclang="es" 
    label="Español"
    oncuechange="manejarCambioCue(event)"
  >
</video>

Con JavaScript (recomendado):

const video = document.querySelector('video');
const pista = video.querySelector('track');

pista.addEventListener('cuechange', (e) => {
  const cueActivo = pista.track.activeCues[0];
  // Acciones con el cue actual
});

Ejemplos prácticos

Ejemplo 1: Mostrar subtítulos personalizados

<video id="miVideo" controls>
  <source src="video.mp4" type="video/mp4">
  <track 
    id="subtitulos" 
    src="subtitulos.vtt" 
    kind="subtitles" 
    default
  >
</video>
<div id="subtituloPersonalizado"></div>

<script>
  const video = document.getElementById('miVideo');
  const pista = video.querySelector('#subtitulos');

  pista.oncuechange = () => {
    const cueActual = pista.track.activeCues[0];
    if (cueActual) {
      document.getElementById('subtituloPersonalizado').textContent = cueActual.text;
    }
  };
</script>

Ejemplo 2: Cuestionario interactivo sincronizado

<video id="tutorial" controls>
  <source src="leccion.mp4" type="video/mp4">
  <track 
    src="preguntas.vtt" 
    kind="metadata" 
    oncuechange="mostrarPregunta(event)"
  >
</video>
<div id="pregunta" hidden></div>

<script>
  function mostrarPregunta(e) {
    const cue = e.target.track.activeCues[0];
    if (cue && cue.text.startsWith('PREGUNTA:')) {
      const pregunta = cue.text.split(':')[1];
      document.getElementById('pregunta').textContent = pregunta;
      document.getElementById('pregunta').hidden = false;
    } else {
      document.getElementById('pregunta').hidden = true;
    }
  }
</script>

Propiedades clave de los cues

Accede a datos útiles desde el objeto cue:

• text: Contenido textual del cue.

• startTime: Momento de inicio (en segundos).

• endTime: Momento de finalización.

• id: Identificador único del cue.

pista.addEventListener('cuechange', () => {
  const cue = pista.track.activeCues[0];
  console.log(`Cue actual: ${cue.text} (${cue.startTime}-${cue.endTime}s)`);
});

Diferencias clave: oncuechange vs eventos multimedia

Evento	Descripción
oncuechange	Cambio en cues activos de una pista de texto
ontimeupdate	Actualización general del tiempo de reproducción
onplay	Al iniciar la reproducción

Mejores prácticas

Formato WebVTT válido:

Asegúrate de que el archivo .vtt esté bien estructurado:

WEBVTT

00:00:03.000 --> 00:00:06.000
Este es un cue de ejemplo.

Manejo de múltiples pistas:

const pistas = video.textTracks;
pistas[0].oncuechange = () => { /*...*/ }; // Pista 0

Accesibilidad:

• Usa kind="subtitles" para subtítulos estándar.

• Proporciona controles para activar/desactivar pistas.

Casos avanzados

Sincronización con animaciones CSS:

<video id="videoAnimado" controls>
  <source src="animacion.mp4" type="video/mp4">
  <track 
    src="animacion.vtt" 
    kind="metadata" 
    oncuechange="manejarAnimacion(event)"
  >
</video>
<div id="elementoAnimado"></div>

<script>
  function manejarAnimacion(e) {
    const cue = e.target.track.activeCues[0];
    if (cue && cue.text === 'animar') {
      document.getElementById('elementoAnimado').classList.add('animar');
    } else {
      document.getElementById('elementoAnimado').classList.remove('animar');
    }
  }
</script>

<style>
  .animar {
    animation: destacar 1s;
  }
</style>

Integración con APIs externas:

pista.addEventListener('cuechange', async () => {
  const cue = pista.track.activeCues[0];
  if (cue.text.startsWith('TRADUCIR:')) {
    const texto = cue.text.split(':')[1];
    const traduccion = await traducirTexto(texto, 'en');
    mostrarTraduccion(traduccion);
  }
});

Errores comunes

<!-- MAL: Pista no cargada o con errores -->
<track src="ruta-incorrecta.vtt"> <!-- El evento no se disparará -->

<!-- CONFUSIÓN: Usar en elementos sin pistas -->
<audio oncuechange="..."></audio> <!-- Requiere elemento <track> -->

<!-- OLVIDAR el atributo default en pistas múltiples -->
<track src="subtitulos.vtt" kind="subtitles"> <!-- Puede no activarse -->

Compatibilidad

Navegador	Soporte	Notas
Chrome	✅ Sí (v. 18+)
Firefox	✅ Sí (v. 31+)
Safari	✅ Sí
Edge	✅ Sí (v. 12+)
Móviles	✅ Sí (iOS/Android)

Conclusión

El atributo oncuechange es ideal para:

• Sincronizar contenido interactivo con momentos específicos de un video.
• Crear experiencias educativas con cuestionarios integrados.
• Mejorar la accesibilidad mediante subtítulos dinámicos.

Recuerda:

1. Usa archivos WebVTT bien formateados.
2. Combina con otras APIs multimedia para experiencias ricas.
3. Prueba en múltiples navegadores.

¡Ahora puedes crear aplicaciones multimedia interactivas y profesionales!