@ysolve/ocity-heritage-visualizer 1.0.8 → 1.1.0

package/README.md

@@ -64,15 +64,16 @@ import avatarImage2 from './assets/avatar2.webp';
 function App() {
   const heritageItems = [
     {
-      id: "1",
-      name: "Castillo de Buñol",
+      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..."
-        }
+          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"
+      imageUrl: 'https://example.com/castle.jpg',
     },
     // Más patrimonios...
   ];
@@ -83,7 +84,7 @@ function App() {
       targetLanguage="es"
       descriptionLength="extended"
       autoAdvance={false}
-      voiceIds={["21m00Tcm4TlvDq8ikWAM"]} // IDs de voces de ElevenLabs
+      voiceIds={['21m00Tcm4TlvDq8ikWAM']} // IDs de voces de ElevenLabs
       avatars={[avatarImage1, avatarImage2]}
     />
   );
@@ -96,14 +97,15 @@ export default App;
 
 ### `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 |
+| 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       |
+| `ttsPreset`         | `string`                | ❌        | ID del preset TTS a usar           |
 
 ### Tipo `HeritageItem`
 
@@ -138,7 +140,12 @@ Los estilos se incluyen en el archivo CSS de la librería. Puedes sobrescribirlo
 El componente requiere ciertas variables de entorno para funcionar correctamente:
 
 ```env
-# ElevenLabs API
+# Qwen3-TTS-Flash API via ocity_tts Server (Proveedor principal)
+# URL del servidor ocity_tts que actúa como proxy a Alibaba DashScope
+# Default: http://localhost:3000 (si no se especifica)
+VITE_QWEN_TTS_API_URL=http://localhost:3000
+
+# ElevenLabs API (Proveedor fallback)
 VITE_ELEVENLABS_API_BASE=https://api.elevenlabs.io/v1
 VITE_ELEVENLABS_API_KEY=tu_api_key_aqui
 
@@ -153,7 +160,152 @@ VITE_DEFAULT_IMAGE_URL=https://tu-cdn.com/default.jpg
 VITE_DEBUG_MODE=false
 ```
 
-## 🎤 Obtener IDs de Voces de ElevenLabs
+### Notas sobre variables de entorno
+
+- **`VITE_QWEN_TTS_API_URL`**: URL del servidor ocity_tts (proveedor principal). Default: `http://localhost:3000`. Sin esta URL disponible, se usará automáticamente ElevenLabs como proveedor único.
+- **`VITE_ELEVENLABS_API_KEY`**: Requerida como proveedor fallback o principal si Qwen no está disponible.
+- Las demás variables son obligatorias para el correcto funcionamiento del componente.
+
+## Sistema de Fallback de TTS
+
+Este componente implementa automaticamente un sistema de fallback entre dos proveedores de TTS:
+
+1. **Proveedor Principal**: Qwen3-TTS-Flash (a través de ocity_tts)
+   - Si el servidor está disponible (`VITE_QWEN_TTS_API_URL`), se intenta sintetizar primero con este proveedor
+   - Voces soportadas: Peter, Bodega, Ebona
+   - El servidor ocity_tts maneja la autenticación con Alibaba (sin CORS)
+
+2. **Proveedor Fallback**: ElevenLabs
+   - Si la síntesis con Qwen falla, automáticamente se intenta con ElevenLabs
+   - Si ambos fallan, el usuario ve un error informativo
+
+**Mapeo de voces**:
+
+- Voz Mujer (ElevenLabs) ↔ Ebona (Qwen3)
+- Voz Hombre Joven (ElevenLabs) ↔ Bodega (Qwen3)
+
+### Levantar ocity_tts
+
+Para usar Qwen3-TTS-Flash, necesitas tener el servidor ocity_tts corriendo:
+
+```bash
+cd ../ocity_tts
+npm install
+ALIBABA_API_KEY=sk_your_key_here npm run dev
+# Corre en http://localhost:3000
+```
+
+Luego, en ocity_history_visualizer, asegúrate de que `VITE_QWEN_TTS_API_URL=http://localhost:3000` esté configurado.
+
+## Sistema de Presets TTS
+
+El componente soporta presets predefinidos de parámetros TTS que aplican estilos emocionales y de narración consistentes. Los presets pueden combinarse con parámetros individuales, donde **los parámetros individuales sobrescriben los valores del preset**.
+
+### Presets Disponibles
+
+El servidor ocity_tts expone un endpoint para obtener todos los presets disponibles:
+
+```bash
+curl http://localhost:3000/api/v1/tts/presets
+```
+
+**Presets incluidos:**
+
+| ID                      | Nombre                | Descripción           | Emoción      | Velocidad | Pitch | Propósito             |
+| ----------------------- | --------------------- | --------------------- | ------------ | --------- | ----- | --------------------- |
+| `formal_narrative`      | Formal Narrative      | Narración documental  | calm         | 1.0       | 1.0   | documentary narration |
+| `conversational`        | Conversational        | Presentación amigable | cheerful     | 1.1       | 1.05  | presentation          |
+| `dramatic_storytelling` | Dramatic Storytelling | Narración cautivadora | enthusiastic | 0.9       | 1.1   | storytelling          |
+| `audiobook`             | Audiobook             | Narración profesional | calm         | 0.85      | 0.95  | audiobook             |
+| `educational`           | Educational           | Tono educativo claro  | calm         | 0.95      | 1.0   | educational content   |
+
+### Usando Presets en el Componente
+
+Pasa el ID del preset a través de la prop `ttsPreset`:
+
+```tsx
+<StoryVisualizer
+  heritageItems={heritageItems}
+  targetLanguage="es"
+  descriptionLength="extended"
+  autoAdvance={false}
+  voiceIds={['21m00Tcm4TlvDq8ikWAM']}
+  avatars={[avatarImage]}
+  ttsPreset="dramatic_storytelling" // ← Usar preset específico
+/>
+```
+
+### Selector de Presets en Aplicación
+
+El componente de demostración (en `demo/src/App.tsx`) incluye un selector de presets que permite cambiar entre presets en tiempo de ejecución:
+
+```tsx
+import { useEffect, useState } from 'react';
+
+function App() {
+  const [presets, setPresets] = useState([]);
+  const [selectedPreset, setSelectedPreset] = useState<string | undefined>();
+
+  useEffect(() => {
+    // Obtener presets disponibles del servidor ocity_tts
+    fetch('http://localhost:3000/api/v1/tts/presets')
+      .then((res) => res.json())
+      .then((data) => {
+        setPresets(data.presets);
+        if (data.presets.length > 0) {
+          setSelectedPreset(data.presets[0].id);
+        }
+      });
+  }, []);
+
+  return (
+    <>
+      <select
+        value={selectedPreset || ''}
+        onChange={(e) => setSelectedPreset(e.target.value)}
+      >
+        {presets.map((p) => (
+          <option key={p.id} value={p.id}>
+            {p.label}
+          </option>
+        ))}
+      </select>
+
+      <StoryVisualizer
+        heritageItems={heritageItems}
+        targetLanguage="es"
+        descriptionLength="extended"
+        autoAdvance={false}
+        voiceIds={['21m00Tcm4TlvDq8ikWAM']}
+        avatars={[avatarImage]}
+        ttsPreset={selectedPreset}
+      />
+    </>
+  );
+}
+```
+
+### Diferencias Audibles entre Presets
+
+Cada preset produce diferencias audibles en la narración:
+
+- **Formal Narrative** → Narración tranquila y medida (documentales)
+- **Conversational** → Tono más rápido y alegre (presentaciones)
+- **Dramatic Storytelling** → Más lento pero entusiasta (historias cautivadoras)
+- **Audiobook** → Muy lento y profesional (audiolibros)
+- **Educational** → Moderadamente lento y claro (contenido educativo)
+
+### Caché Inteligente
+
+El sistema de caché diferencia entre presets diferentes, por lo que la misma narración con diferentes presets se cachea por separado:
+
+```
+Cache key: qwen-${voiceId}-${language}-${preset}-${text}
+```
+
+Esto significa que cambiar presets solicita síntesis nuevas pero evita re-procesar si vuelves a usar el mismo preset.
+
+## Obtener IDs de Voces de ElevenLabs
 
 1. Inicia sesión en [ElevenLabs](https://elevenlabs.io/)
 2. Ve a "Voice Library" o "My Voices"
@@ -163,8 +315,8 @@ Ejemplo de voces disponibles:
 
 ```typescript
 const voices = [
-  { id: "21m00Tcm4TlvDq8ikWAM", name: "Rachel - Voz Femenina" },
-  { id: "Nh2zY9kknu6z4pZy6FhD", name: "Adam - Voz Masculina" },
+  { id: '21m00Tcm4TlvDq8ikWAM', name: 'Rachel - Voz Femenina' },
+  { id: 'Nh2zY9kknu6z4pZy6FhD', name: 'Adam - Voz Masculina' },
 ];
 ```
 
@@ -220,8 +372,8 @@ function DynamicExample() {
 
   useEffect(() => {
     fetch('https://api.o-city.org/heritages')
-      .then(res => res.json())
-      .then(data => setHeritages(data));
+      .then((res) => res.json())
+      .then((data) => setHeritages(data));
   }, []);
 
   if (heritages.length === 0) {
@@ -233,8 +385,8 @@ function DynamicExample() {
       heritageItems={heritages}
       targetLanguage="es"
       descriptionLength="extended"
-      voiceIds={["21m00Tcm4TlvDq8ikWAM"]}
-      avatars={["./avatar.webp"]}
+      voiceIds={['21m00Tcm4TlvDq8ikWAM']}
+      avatars={['./avatar.webp']}
     />
   );
 }
@@ -245,22 +397,26 @@ function DynamicExample() {
 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
 ```