@ysolve/ocity-heritage-visualizer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ysolve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# O-CITY Heritage Visualizer
+
+<div align="center">
+
+**Componente React para visualizar patrimonio cultural con texto a voz y avatares animados**
+
+[![npm version](https://img.shields.io/npm/v/@ysolve/ocity-heritage-visualizer.svg)](https://www.npmjs.com/package/@ysolve/ocity-heritage-visualizer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+## 📖 Descripción
+
+`ocity-heritage-visualizer` es un componente React que transforma la información de **patrimonio cultural** de la plataforma [O-CITY](https://o-city.org/) 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](https://elevenlabs.io/)
+- 🌍 **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
+
+```bash
+npm install @ysolve/ocity-heritage-visualizer
+```
+
+O con yarn:
+
+```bash
+yarn add @ysolve/ocity-heritage-visualizer
+```
+
+O con pnpm:
+
+```bash
+pnpm add @ysolve/ocity-heritage-visualizer
+```
+
+## 🚀 Uso Básico
+
+```tsx
+import { StoryVisualizer } from '@ysolve/ocity-heritage-visualizer';
+import '@ysolve/ocity-heritage-visualizer/dist/style.css';
+
+// 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`
+
+```typescript
+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:
+
+```css
+/* 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:
+
+```env
+# 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](https://elevenlabs.io/)
+2. Ve a "Voice Library" o "My Voices"
+3. Copia el "Voice ID" de la voz deseada
+
+Ejemplo de voces disponibles:
+
+```typescript
+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
+
+```tsx
+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
+
+```tsx
+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:
+```bash
+git clone https://github.com/tu-usuario/ocity_history_visualizer.git
+cd ocity_history_visualizer
+```
+
+2. Instala las dependencias:
+```bash
+npm install
+```
+
+3. Inicia el servidor de desarrollo:
+```bash
+npm run dev
+```
+
+4. Construye la librería:
+```bash
+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](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
+
+---
+
+<div align="center">
+
+**Hecho con ❤️ por el equipo de [O-CITY](https://o-city.org/)**
+
+</div>