O-CITY Heritage Visualizer

Componente React para visualizar patrimonio cultural con texto a voz y avatares animados

📖 Descripción

ocity-heritage-visualizer es un componente React que transforma la información de patrimonio cultural de la plataforma O-CITY en una experiencia audiovisual interactiva.

En lugar de mostrar texto plano e imágenes, genera una "simulación de video" que incluye:

• 🎤 Narración por voz usando ElevenLabs TTS
• 🌍 Traducción automática con Google Translate
• 📝 Subtítulos sincronizados
• 🎭 Avatar animado (PNGTuber) que acompaña la narración
• ⏯️ Controles de reproducción completos (play, pause, stop)
• 🔄 Navegación entre patrimonios con autoavance opcional

✨ Características

• ✅ Soporte multiidioma (Español, Inglés, Francés)
• ✅ Reproducción de audio con Text-to-Speech
• ✅ Animación de avatares sincronizada con el audio
• ✅ Sistema de caché de audio para mejorar el rendimiento
• ✅ Completamente tipado con TypeScript
• ✅ Responsive y accesible

📦 Instalación

npm install @ysolve/ocity-heritage-visualizer

O con yarn:

yarn add @ysolve/ocity-heritage-visualizer

O con pnpm:

pnpm add @ysolve/ocity-heritage-visualizer

🚀 Uso Básico

import { StoryVisualizer } from '@ysolve/ocity-heritage-visualizer';
import '@ysolve/ocity-heritage-visualizer/dist/ocity-heritage-visualizer.css';
// O también puedes usar el alias 'styles':
// import '@ysolve/ocity-heritage-visualizer/styles';

// Importa tus avatares
import avatarImage1 from './assets/avatar1.webp';
import avatarImage2 from './assets/avatar2.webp';

function App() {
  const heritageItems = [
    {
      id: "1",
      name: "Castillo de Buñol",
      description: {
        local: {
          short: "Castillo medieval del siglo XI",
          extended: "El castillo de Buñol es una fortaleza cristiana construida sobre un asentamiento islámico..."
        }
      },
      imageUrl: "https://example.com/castle.jpg"
    },
    // Más patrimonios...
  ];

  return (
    <StoryVisualizer
      heritageItems={heritageItems}
      targetLanguage="es"
      descriptionLength="extended"
      autoAdvance={false}
      voiceIds={["21m00Tcm4TlvDq8ikWAM"]} // IDs de voces de ElevenLabs
      avatars={[avatarImage1, avatarImage2]}
    />
  );
}

export default App;

🔧 Props

StoryVisualizerProps

| Prop | Tipo | Requerido | Descripción | |------|------|-----------|-------------| | heritageItems | HeritageItem[] | ✅ | Array de objetos de patrimonio | | targetLanguage | "es" \| "en" \| "fr" | ✅ | Idioma de narración | | descriptionLength | "short" \| "extended" | ✅ | Longitud de la descripción | | autoAdvance | boolean | ❌ | Autoavance al siguiente patrimonio | | voiceIds | string[] | ✅ | IDs de voces de ElevenLabs | | avatars | string[] | ✅ | URLs de imágenes de avatares |

Tipo HeritageItem

interface HeritageItem {
  id: string;
  name: string;
  description: {
    local: {
      short: string;
      extended: string;
    };
  };
  imageUrl: string;
}

🎨 Personalización de Estilos

Los estilos se incluyen en el archivo CSS de la librería. Puedes sobrescribirlos en tu aplicación:

/* En tu archivo CSS */
.viewer {
  max-width: 1200px;
  /* Tus estilos personalizados */
}

🔑 Configuración de Variables de Entorno

El componente requiere ciertas variables de entorno para funcionar correctamente:

# ElevenLabs API
VITE_ELEVENLABS_API_BASE=https://api.elevenlabs.io/v1
VITE_ELEVENLABS_API_KEY=tu_api_key_aqui

# Google Translate API
VITE_GOOGLE_TRANSLATE_BASE=https://translate.googleapis.com

# URLs de imágenes
VITE_IMAGE_BASE_URL=https://tu-cdn.com/images/
VITE_DEFAULT_IMAGE_URL=https://tu-cdn.com/default.jpg

# Modo debug (opcional)
VITE_DEBUG_MODE=false

🎤 Obtener IDs de Voces de ElevenLabs

1. Inicia sesión en ElevenLabs
2. Ve a "Voice Library" o "My Voices"
3. Copia el "Voice ID" de la voz deseada

Ejemplo de voces disponibles:

const voices = [
  { id: "21m00Tcm4TlvDq8ikWAM", name: "Rachel - Voz Femenina" },
  { id: "Nh2zY9kknu6z4pZy6FhD", name: "Adam - Voz Masculina" },
];

📋 Requisitos

• React 18.0.0 o superior
• Node.js 16.0.0 o superior

🛠️ Tecnologías Utilizadas

• React 19 - Framework de UI
• TypeScript - Tipado estático
• Vite - Build tool y bundler
• ElevenLabs API - Síntesis de voz (TTS)
• Google Translate API - Traducción automática
• TensorFlow.js - Procesamiento de texto
• IndexedDB - Caché de audio

📚 Ejemplos Avanzados

Ejemplo con múltiples voces y avatares

import { StoryVisualizer, voices } from '@ysolve/ocity-heritage-visualizer';
import avatar1 from './avatars/narrator1.webp';
import avatar2 from './avatars/narrator2.webp';

function AdvancedExample() {
  return (
    <StoryVisualizer
      heritageItems={heritageData}
      targetLanguage="es"
      descriptionLength="extended"
      autoAdvance={true}
      voiceIds={[
        voices[0].id, // Alterna entre diferentes voces
        voices[1].id,
      ]}
      avatars={[avatar1, avatar2]}
    />
  );
}

Uso con datos dinámicos

import { StoryVisualizer } from '@ysolve/ocity-heritage-visualizer';
import { useEffect, useState } from 'react';

function DynamicExample() {
  const [heritages, setHeritages] = useState([]);

  useEffect(() => {
    fetch('https://api.o-city.org/heritages')
      .then(res => res.json())
      .then(data => setHeritages(data));
  }, []);

  if (heritages.length === 0) {
    return <div>Cargando...</div>;
  }

  return (
    <StoryVisualizer
      heritageItems={heritages}
      targetLanguage="es"
      descriptionLength="extended"
      voiceIds={["21m00Tcm4TlvDq8ikWAM"]}
      avatars={["./avatar.webp"]}
    />
  );
}

🔄 Desarrollo Local

Si deseas contribuir o desarrollar localmente:

1. Clona el repositorio:

git clone https://github.com/tu-usuario/ocity_history_visualizer.git
cd ocity_history_visualizer

2. Instala las dependencias:

npm install

3. Inicia el servidor de desarrollo:

npm run dev

4. Construye la librería:

npm run build:lib

📝 Scripts Disponibles

• npm run dev - Inicia el servidor de desarrollo
• npm run build:lib - Construye la librería para producción
• npm run lint - Ejecuta el linter
• npm run preview - Previsualiza la build de producción

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo LICENSE para más detalles.

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Haz un fork del proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add: amazing feature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📧 Contacto

Para preguntas o sugerencias, contacta con el equipo de O-CITY.

🗺️ Roadmap

• [x] Componente base con TTS
• [x] Traducción automática
• [x] Sistema de avatares
• [x] Publicación en npm
• [ ] Soporte para más idiomas
• [ ] Personalización avanzada de avatares
• [ ] Temas personalizables
• [ ] Integración con más proveedores de TTS

Hecho con ❤️ por el equipo de O-CITY