Guía de diseño de audio

Esta no es una receta individual — es una colección de técnicas para usar el sistema de audio de Yumina para crear un paisaje sonoro completo: BGM que sigue los cambios de escena, efectos de sonido disparados por palabras clave, sonidos ambientales en bucle, crossfades sedosos, y todas las formas de controlar la música desde UI personalizada y narración de IA.

Visión general

El sistema de audio de Yumina tiene múltiples puntos de entrada para controlar el sonido en diferentes niveles:

Método de control	Dónde configurarlo	Características
Reproducción automática de playlist	Pestaña Audio	El más simple — la música de fondo comienza tan pronto como el jugador entra al mundo
BGM condicional	Pestaña Audio	Cambia automáticamente de pista cuando se cumplen condiciones de variable/palabra clave/conteo de turnos, sin comportamientos necesarios
Comportamiento + acción Reproducir Audio	Pestaña Behaviors	Crossfade en transiciones de escena, combinar con cambios de variable y alternancia de entradas
Directivas de audio de IA	La IA escribe `[audio: ...]` en su respuesta	La IA decide qué reproducir y cuándo — el más flexible, también el menos predecible
API de audio del Root Component	Sección Custom UI	Disparar desde botones personalizados, ideal para UI interactiva estilo jukebox

Esta guía cubre 7 patrones uno por uno. Elige lo que necesites, o combínalos.

Patrón 1: Configuración básica de BGM

Lo que vas a construir

Música de fondo que comienza a reproducirse en el momento en que un jugador entra a tu mundo — en bucle, sin configuración extra requerida.

Paso a paso

Paso 1: Sube pistas de audio

Editor → pestaña Audio → haz clic en "Add Track"

Campo	Valor	Por qué
Nombre visible	Tema principal	Para tu propia referencia
ID	`main_theme`	Todas las referencias usan este ID
Tipo	BGM	Música de fondo
Archivo de audio	Sube tu archivo `.mp3` o `.ogg`	Formatos de audio comunes soportados
Loop	Activado	La BGM normalmente necesita estar en bucle
Volumen	`0.7`	No te pases con el volumen — deja espacio para SFX y ambiente
Fade In	`2` segundos	Aparece gradualmente para que no sea discordante

¿Quieres más de una pista? Repite los pasos anteriores para crear pistas adicionales — por ejemplo, explore_bgm (exploración), battle_bgm (combate), town_bgm (pueblo).

Paso 2: Configura la playlist

Aún en la pestaña Audio, encuentra la sección "BGM Playlist":

Campo	Valor	Por qué
Track List	Selecciona `main_theme` (selecciona todas si tienes varias)	Las pistas en la lista se reproducen en orden
Play Mode	`loop` o `shuffle`	`loop` = reproducir en orden, repetir; `shuffle` = aleatorizar
Autoplay	Activado	La música empieza cuando el jugador entra al mundo
Wait for First Message	Desactivado (o Activado, según tu preferencia)	Si está Activado, la música espera hasta que el jugador envíe su primer mensaje
Gap Seconds	`0` (o `2`)	Pausa entre pistas; `0` = transición sin interrupciones

Resultado

El jugador entra al mundo → la música comienza automáticamente (con un fade-in de 2 segundos) → cuando una pista termina, comienza la siguiente → tras la última pista, vuelve al principio.

¿Solo tienes una pista de BGM?

Si solo tienes una canción, simplemente activa loop para esa pista y ponla sola en la playlist. Incluso puedes omitir la playlist por completo y controlarla a través de BGM Condicional o directivas de IA en su lugar.

Patrón 2: Crossfade de BGM en transiciones de escena

Lo que vas a construir

Cuando el jugador se mueve de "Pueblo" a "Mazmorra", la música suave del pueblo se desvanece gradualmente mientras la música ominosa de la mazmorra aumenta — ambas pistas se reproducen simultáneamente durante una breve superposición, haciendo la transición suave y cinematográfica.

Cómo funciona

El jugador hace clic en el botón "Ir a la Mazmorra"
  → El comportamiento se dispara: establece variable location = "dungeon"
  → La misma acción Reproducir Audio del comportamiento: crossfade a dungeon_bgm
  → La pista antigua se desvanece + la nueva pista aumenta, duración de transición 2 segundos

Paso a paso

Paso 1: Prepara pistas de audio

En la pestaña Audio, crea dos (o más) pistas de BGM:

village_bgm — música del pueblo, tipo BGM, bucle activado
dungeon_bgm — música de la mazmorra, tipo BGM, bucle activado

Pon village_bgm en la playlist como la pista predeterminada, con reproducción automática activada.

Paso 2: Crea una variable

Editor → pestaña Variables → Add Variable

Campo	Valor
Nombre visible	Ubicación actual
ID	`location`
Tipo	String
Valor por defecto	`village`

Paso 3: Crea un comportamiento

Editor → pestaña Behaviors → Add Behavior

Nombre del comportamiento: Go to Dungeon

Disparador: Action → Action ID: go-dungeon

Acciones (en orden):

#	Tipo de acción	Configuración	Propósito
1	Establecer variable	`location` set a `dungeon`	Registra que el jugador fue a la mazmorra
2	Reproducir audio	Pista `dungeon_bgm`, operación: `crossfade`, duración de fundido `2` segundos	Cambio de pista sedoso
3	Habilitar entrada	Dungeon Atmosphere	Activa el lore de la mazmorra
4	Deshabilitar entrada	Village Atmosphere	Desactiva el lore del pueblo

Crea un comportamiento coincidente "Return to Village" con action ID go-village que hace lo inverso (crossfade a village_bgm, intercambia activación de entradas).

Paso 4: Dispara desde el Root Component

En el Root Component index.tsx (dentro del callback <Chat renderBubble> o en cualquier botón personalizado), llama a executeAction:

tsx

<button onClick={() => api.executeAction("go-dungeon")}>
  Go to Dungeon
</button>

El comportamiento ejecuta todas sus acciones en secuencia — cambia la variable, cambia la música, alterna entradas — todo desde un clic de botón.

¿Qué es crossfade? Fundido cruzado — la pista antigua gradualmente se vuelve más silenciosa mientras la nueva pista gradualmente se vuelve más alta. Ambas pistas se reproducen simultáneamente durante un breve período, sonando como una transición de escena cinematográfica en lugar de un corte abrupto. Una duración de fundido de 2-3 segundos funciona bien.

Patrón 3: Efectos de sonido disparados por palabras clave

Lo que vas a construir

Un sonido de explosión se reproduce automáticamente cuando la IA escribe "explosion". Un sonido de puerta chirriante se reproduce cuando el jugador dice "open the door". Sin comportamientos necesarios — configuras esto directamente en la sección BGM Condicional de la pestaña Audio.

Cómo funciona

BGM Condicional tiene tipos de disparador llamados ai-keyword (palabra clave de IA) y keyword (palabra clave del jugador). El motor escanea el texto de cada mensaje y reproduce la pista correspondiente cuando una palabra clave coincide. A pesar del nombre "BGM Condicional", puede apuntar a cualquier tipo de pista — incluyendo SFX.

Paso a paso

Paso 1: Crea pistas SFX

En la pestaña Audio, crea pistas de efectos de sonido:

SFX de Explosión:

Campo	Valor
Nombre visible	Explosión
ID	`explosion_sfx`
Tipo	SFX
Loop	Desactivado (los efectos de sonido normalmente se reproducen una vez)
Volumen	`0.9`

SFX de Apertura de Puerta:

Campo	Valor
Nombre visible	Apertura de puerta
ID	`door_open_sfx`
Tipo	SFX
Loop	Desactivado
Volumen	`0.8`

Paso 2: Crea reglas de BGM Condicional

Aún en la pestaña Audio, encuentra la sección "Conditional BGM" → haz clic en "Add Rule"

Regla 1: Reproducir SFX cuando la IA dice "explosion"

Campo	Valor	Por qué
Nombre	SFX de explosión de IA	Para tu propia referencia
Trigger Type	AI Keyword (`ai-keyword`)	Se dispara cuando la respuesta de la IA contiene la palabra clave especificada
Keywords	`explosion`, `blast`, `detonate`	Puedes añadir múltiples sinónimos — coincidir con cualquiera lo dispara
Target Track	`explosion_sfx`	Reproduce el sonido de explosión
Stop Current BGM	Desactivado	Los SFX se superponen a la BGM — no detengas la música

Regla 2: Reproducir SFX cuando el jugador dice "open the door"

Campo	Valor	Por qué
Nombre	SFX puerta del jugador	Para tu propia referencia
Trigger Type	Player Keyword (`keyword`)	Se dispara cuando el mensaje del jugador contiene la palabra clave especificada
Keywords	`open the door`, `push the door`, `open door`	Múltiples sinónimos
Target Track	`door_open_sfx`	Reproduce el sonido de la puerta
Stop Current BGM	Desactivado	Igual que antes

Resultado

La IA escribe: "BOOM — una explosión ensordecedora sacude la ladera, el fuego ilumina todo el cielo."
  → El motor escanea y coincide "explosion" → reproduce automáticamente explosion_sfx
  → El jugador escucha el sonido de explosión mientras la BGM sigue sonando

El jugador escribe: "I walk to the door and open it."
  → El motor escanea y coincide "open the door" → reproduce automáticamente door_open_sfx

SFX vs BGM

Los SFX (efectos de sonido) se reproducen una vez y se detienen. La BGM (música de fondo) hace bucle o continúa según la playlist. Cuando una regla de BGM Condicional apunta a una pista de tipo SFX, se reproduce una vez y no reemplaza la música de fondo actual. Pero si stopPreviousBGM se establece en true, detiene la BGM actual primero antes de reproducir la pista — los SFX normalmente no necesitan esto.

Patrón 4: BGM Condicional — Cambio automático impulsado por variables

Lo que vas a construir

Sin comportamientos necesarios — configura una regla directamente en la pestaña Audio: cuando hp baja por debajo de 20, cambia automáticamente a música tensa de crisis; cuando hp vuelve por encima de 20, vuelve a la pista predeterminada.

Cómo funciona

El tipo de disparador variable de BGM Condicional comprueba automáticamente tras cada cambio de variable. Condición cumplida → cambia a la pista objetivo; condición ya no cumplida → retrocede según la configuración fallback (volver a la pista predeterminada de la playlist, o a la pista que estaba sonando previamente).

Paso a paso

Paso 1: Prepara pistas de audio

Asegúrate de que la pestaña Audio tenga:

explore_bgm — música de exploración predeterminada (en la playlist)
crisis_bgm — música de crisis (solo se reproduce cuando la condición se dispara; no necesita estar en la playlist)

Paso 2: Crea una regla de BGM Condicional

Pestaña Audio → Conditional BGM → Add Rule

Campo	Valor	Por qué
Nombre	Música de crisis por HP bajo	Para tu propia referencia
Trigger Type	Variable (`variable`)	Decide según los valores de variables
Condition	`hp` < `20`	Se dispara cuando HP está por debajo de 20
Condition Logic	All (`all`)	Solo una condición aquí, así que `all` y `any` funcionan igual
Target Track	`crisis_bgm`	Cambia a música de crisis
Priority	`10`	Si múltiples reglas coinciden simultáneamente, gana la de mayor prioridad
Fade In Duration	`1` segundo	La nueva pista aumenta gradualmente
Fade Out Duration	`1` segundo	La pista antigua se desvanece gradualmente
Stop Current BGM	Activado	Detiene la música de exploración antes de reproducir música de crisis
Fallback	`default`	Cuando la condición ya no se cumple (HP vuelve por encima de 20), vuelve automáticamente a la pista predeterminada de la playlist

Resultado

El jugador está explorando, la BGM es explore_bgm
  → La IA responde: [hp: -15] (hp baja de 30 a 15)
  → El motor detecta hp < 20, condición cumplida
  → explore_bgm se desvanece en 1 segundo, crisis_bgm aumenta en 1 segundo
  → La atmósfera se vuelve tensa instantáneamente

El jugador usa una poción curativa
  → La IA responde: [hp: +20] (hp vuelve de 15 a 35)
  → El motor detecta que hp ya no es < 20, condición no cumplida
  → fallback: "default" → vuelve automáticamente a explore_bgm

Combinaciones multi-condición

Puedes añadir múltiples condiciones a una sola regla. Por ejemplo: hp < 20 Y location == "dungeon" → la música de crisis solo se reproduce cuando estás en la mazmorra con HP bajo. Establece la lógica de condición a all (todas deben coincidir).

Patrón 5: Bucles de sonido ambiental

Lo que vas a construir

Sonidos ambientales que se reproducen continuamente en el fondo de la escena — lluvia, viento, charla de taberna — superpuestos a la BGM para profundizar la inmersión.

Cómo funciona

Ambient es el tercer tipo de pista. Se reproduce independientemente de la BGM — puedes tener una pista de BGM + una pista de ambient sonando simultáneamente. Ambient normalmente se establece en bucle a bajo volumen, sirviendo como un telón de fondo atmosférico constante.

Paso a paso

Paso 1: Crea pistas Ambient

Pestaña Audio → Add Track

Campo	Valor
Nombre visible	Lluvia
ID	`rain_ambient`
Tipo	Ambient
Loop	Activado
Volumen	`0.3` (el ambient debería ser más silencioso que la BGM — es el telón de fondo)
Fade In	`3` segundos (aparece gradualmente, no es discordante)
Fade Out	`3` segundos

Crea más según sea necesario: wind_ambient (viento), tavern_ambient (charla de taberna), forest_ambient (cantos de pájaros e insectos).

Paso 2: Controla el ambient mediante BGM Condicional

Igual que el Patrón 4 — usa una regla de BGM Condicional para controlar cuándo se reproduce el ambient.

Regla: Reproducir ambient de bosque cuando esté en el bosque

Campo	Valor
Nombre	Ambiente del bosque
Trigger Type	Variable (`variable`)
Condition	`location` == `forest`
Target Track	`forest_ambient`
Stop Current BGM	Desactivado
Fallback	`default`

Clave: stopPreviousBGM debe estar Desactivado. El ambient se superpone a la BGM — no debería detener la música de fondo. Si lo activas, cambiar pistas de ambient también matará cualquier BGM que esté sonando actualmente.

También puedes controlar el ambient mediante comportamientos

Si ya tienes comportamientos de cambio de escena (como el Patrón 2), simplemente añade una acción "Reproducir Audio" a la lista de acciones del comportamiento, apuntando a la pista de ambient:

#	Tipo de acción	Configuración	Propósito
1	Establecer variable	`location` set a `forest`	Registra la ubicación
2	Reproducir audio	`forest_bgm`, operación: crossfade, fundido 2s	Cambia la BGM
3	Reproducir audio	`forest_ambient`, operación: play, fade in 3s	Superpone el sonido ambiental
4	Reproducir audio	`tavern_ambient`, operación: stop, fade out 3s	Detiene el ambient antiguo

De esta forma, un único comportamiento maneja tanto el cambio de BGM como el intercambio de ambient.

Recomendaciones de volumen

BGM: típicamente 0.5-0.7. Ambient: 0.2-0.4. SFX: 0.7-1.0. Con estas tres capas en niveles diferentes, no se pelearán entre sí.

Patrón 6: Controlando audio desde el Root Component

Lo que vas a construir

Un "jukebox" en el Root Component — algunos botones que cada uno reproduce una pista diferente, más un botón "Stop". Este es control puro de UI — no se necesitan comportamientos ni reglas condicionales.

Cómo funciona

useYumina() proporciona estas APIs de audio (todas las duraciones en segundos):

api.playAudio?.(trackId, opts) — reproduce la pista especificada. opts incluye volume, fadeDuration, chainTo, maxDuration, duckBgm y loop (sobrescribe el loop de la pista solo para esta reproducción)
api.stopAudio?.(trackId?) — detiene la pista especificada (omite el ID para detener todo). Destruye el elemento — usa pauseAudio para reanudar más tarde
api.pauseAudio?.(trackId) / api.resumeAudio?.(trackId) — pausa/reanudación real en el sitio
api.onAudioEnded?.(cb) — ejecuta cb(trackId) cuando una pista no en bucle termina; devuelve una función para cancelar la suscripción. Úsalo para avanzar automáticamente una lista de reproducción:

tsx

React.useEffect(() => api.onAudioEnded?.((endedId) => {
  if (endedId === currentTrackId && mode !== "single") playNext();
}), [currentTrackId, mode]);

Ambos métodos se pueden llamar directamente en el Root Component index.tsx (dentro de los callbacks <Chat renderBubble>, o en cualquier botón que añadas).

Paso a paso

Paso 1: Prepara pistas de audio

Asegúrate de que la pestaña Audio tenga las pistas que quieres reproducir (créalas como en el Patrón 1). Digamos que tienes:

jazz_bgm — jazz
rock_bgm — rock
classical_bgm — clásica

Paso 2: Escribe el código del Root Component

Editor → sección Custom UI → abre index.tsx → pega lo siguiente (reemplaza el predeterminado return <Chat />):

tsx

export default function MyWorld() {
  const api = useYumina();
  const msgs = api.messages || [];

  const tracks = [
    { id: "jazz_bgm", label: "Jazz", color: "#7c3aed" },
    { id: "rock_bgm", label: "Rock", color: "#dc2626" },
    { id: "classical_bgm", label: "Classical", color: "#0891b2" },
  ];

  return (
    <Chat renderBubble={(msg) => {
      const isLastMsg = msg.messageIndex === msgs.length - 1;
      return (
    <div>
      <div
        style={{ color: "#e2e8f0", lineHeight: 1.7 }}
        dangerouslySetInnerHTML={{ __html: msg.contentHtml }}
      />

      {isLastMsg && (
        <div style={{
          marginTop: "12px",
          padding: "12px",
          background: "rgba(30,41,59,0.5)",
          borderRadius: "8px",
          border: "1px solid #334155",
        }}>
          <div style={{ fontSize: "12px", color: "#94a3b8", marginBottom: "8px" }}>
            Jukebox
          </div>
          <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
            {tracks.map((t) => (
              <button
                key={t.id}
                onClick={() => api.playAudio?.(t.id, { fadeDuration: 1.5 })}
                style={{
                  padding: "8px 16px",
                  background: t.color,
                  border: "none",
                  borderRadius: "6px",
                  color: "#fff",
                  fontSize: "13px",
                  cursor: "pointer",
                }}
              >
                {t.label}
              </button>
            ))}
            <button
              onClick={() => api.stopAudio?.()}
              style={{
                padding: "8px 16px",
                background: "#475569",
                border: "none",
                borderRadius: "6px",
                color: "#e2e8f0",
                fontSize: "13px",
                cursor: "pointer",
              }}
            >
              Stop
            </button>
          </div>
        </div>
      )}
    </div>
      );
    }} />
  );
}

Desglose línea por línea:

MyWorld() es el Root Component — el punto de entrada de la UI del mundo. <Chat renderBubble={...} /> mantiene a la plataforma a cargo de la lista de mensajes, la entrada y el desplazamiento; solo personalizamos el layout por burbuja
api.playAudio?.(t.id, { fadeDuration: 1.5 }) — reproduce la pista especificada con un fade-in de 1.5 segundos. Si otra pista está sonando actualmente, la detiene automáticamente primero
api.stopAudio?.() — llamada sin argumentos = detiene todo el audio que esté sonando actualmente
msg.messageIndex === msgs.length - 1 — solo muestra el jukebox en el último mensaje, así no se repite en cada mensaje

Uso más avanzado

Puedes leer variables para controlar el estado de la UI. Por ejemplo, usa una variable now_playing para seguir el ID de la pista actual, luego muestra un indicador "Sonando ahora" en el botón:

tsx

const nowPlaying = String(api.variables.now_playing || "");

// Actualiza la variable junto con la reproducción
onClick={() => {
  api.playAudio?.(t.id, { fadeDuration: 1.5 });
  api.setVariable("now_playing", t.id);
}}

// Muestra el estado en el botón
{nowPlaying === t.id ? "♪ " + t.label : t.label}

Patrón 7: Control de audio impulsado por IA

Lo que vas a construir

Deja que la IA controle naturalmente la música durante la narración — reproducir una alegre melodía de acordeón al describir la entrada a una taberna, cambiar a BGM intensa de batalla cuando estalla una pelea, reproducir un efecto de sonido de dolor cuando un personaje resulta herido.

Cómo funciona

La IA puede incrustar directivas [audio: trackId action] en sus respuestas. El motor reconoce y ejecuta automáticamente estas directivas mientras las elimina del texto que el jugador ve — como acotaciones en un guion que la audiencia nunca lee, pero que el equipo sigue.

Paso a paso

Paso 1: Registra todas las pistas que la IA podría usar

En la pestaña Audio, crea todas las pistas que quieras que la IA controle:

tavern_bgm — música de taberna
battle_bgm — música de batalla
sword_clash_sfx — efecto de sonido de choque de espadas
pain_sfx — efecto de sonido de dolor/lesión
rain_ambient — ambient de lluvia

Paso 2: Dile a la IA qué pistas están disponibles mediante el prompt del sistema

La IA no sabrá automáticamente qué pistas has registrado. Necesitas crear una entrada en la pestaña Entries listando las pistas disponibles y las reglas de uso:

Nombre de entrada: Audio Directive Reference

Sección: System Presets

Contenido:

[Sistema de control de audio]
Puedes usar las siguientes directivas de audio en tus respuestas para controlar la música y los efectos de sonido. Las directivas se ejecutan automáticamente y se eliminan del texto que ve el jugador.

Formatos de directiva disponibles:
- [audio: trackId play] — reproducir
- [audio: trackId play 2.0] — reproducir con un fade-in de 2 segundos
- [audio: trackId stop] — detener
- [audio: trackId stop 1.5] — detener con un fade-out de 1.5 segundos
- [audio: trackId crossfade 2.0] — transición crossfade, superposición de 2 segundos
- [audio: trackId volume 0.5] — ajustar el volumen a 0.5
- [audio: trackId play chain:nextTrackId] — cuando esta pista termine, iniciar automáticamente la siguiente

Pistas disponibles:
- tavern_bgm — música animada de acordeón de taberna (buena para escenas sociales, compras)
- battle_bgm — música intensa de batalla (buena para combate, escenas de persecución)
- sword_clash_sfx — efecto de sonido de choque de espadas (bueno para descripciones de acción cuerpo a cuerpo)
- pain_sfx — efecto de sonido de dolor/lesión (bueno para cuando un personaje resulta herido)
- rain_ambient — sonido ambiental de lluvia (bueno para escenas lluviosas)

Pautas de uso:
- Inserta las directivas de audio en puntos narrativos naturales
- Usa crossfade para las transiciones de escena, con una duración de 1.5-2.5 segundos
- Empareja los efectos de sonido con las descripciones de acción, colocándolos cerca del texto correspondiente
- No te excedas — como mucho 2-3 directivas de audio por respuesta

Paso 3: Ejemplo de respuesta de IA

Tras decirle a la IA estas reglas, sus respuestas podrían verse así:

Empujas la pesada puerta de madera de la taberna y una ráfaga de aire cálido te golpea la cara. [audio: tavern_bgm crossfade 2.0]

La taberna está animada — alguien toca el acordeón en la esquina, y un enano en la barra grita por encima de una partida de dados. Apenas has encontrado asiento cuando una figura enmascarada saca de pronto una hoja y se lanza contra ti.

[audio: battle_bgm crossfade 0.5] [audio: sword_clash_sfx play]

Te echas a un lado por instinto. La mesa se parte en dos detrás de ti.

El jugador ve texto narrativo limpio mientras escucha: música de taberna apareciendo → cambio abrupto a música de batalla + efecto de sonido de choque de espadas.

La directiva `chain` — uso especial

chain permite que una pista inicie automáticamente otra cuando termina:

El sonido de los cuernos de guerra retumba por el valle — ¡la batalla está a punto de comenzar! [audio: war_horn_sfx play chain:battle_bgm]

Tras terminar el toque de cuerno war_horn_sfx, battle_bgm comienza automáticamente — una introducción a la pista principal, más ceremonial que un cambio directo.

La IA podría olvidar usar directivas

La IA no siempre recordará insertar directivas de audio, especialmente en conversaciones largas. Para cambios críticos de BGM de escena (como entrar en una zona de combate), configura reglas de BGM Condicional (Patrón 4) como respaldo. Las directivas de IA son la guinda del pastel; la BGM Condicional es la red de seguridad.

Referencia rápida exhaustiva

Tipos de pista

Tipo	Propósito	Configuración típica
BGM	Música de fondo	Bucle activado, volumen 0.5-0.7
SFX	Efectos de sonido puntuales	Bucle desactivado, volumen 0.7-1.0
Ambient	Sonidos ambientales en bucle	Bucle activado, volumen 0.2-0.4

5 formas de controlar audio

Qué quieres hacer	Qué método	Dónde configurarlo
Reproducción automática de BGM al entrar al mundo	Playlist + reproducción automática	Pestaña Audio → BGM Playlist
Cambio automático de pista cuando se cumplen condiciones de variable	BGM Condicional (disparador de variable)	Pestaña Audio → Conditional BGM
Reproducir SFX cuando la respuesta de la IA contiene una palabra clave	BGM Condicional (disparador ai-keyword)	Pestaña Audio → Conditional BGM
Reproducir SFX cuando el mensaje del jugador contiene una palabra clave	BGM Condicional (disparador keyword)	Pestaña Audio → Conditional BGM
Cambiar de pista en un número específico de turno	BGM Condicional (disparador turn-count)	Pestaña Audio → Conditional BGM
Crossfade en transición de escena	Comportamiento + acción Reproducir Audio	Pestaña Behaviors
Reproducir/detener desde un clic de botón	Root Component `api.playAudio?.()` / `api.stopAudio?.()`	Sección Custom UI
La IA dispara audio durante la narración	Directivas de audio de IA `[audio: trackId action]`	Pestaña Entries (dile a la IA las reglas)

Referencia de directivas de audio de la IA

Directiva	Efecto
`[audio: trackId play]`	Reproducir
`[audio: trackId play 2.0]`	Reproducir con fade-in de 2 segundos
`[audio: trackId stop]`	Detener
`[audio: trackId stop 1.5]`	Detener con fade-out de 1.5 segundos
`[audio: trackId crossfade 2.0]`	Transición crossfade, superposición de 2 segundos
`[audio: trackId volume 0.5]`	Ajustar volumen
`[audio: trackId play chain:nextId]`	Tras terminar, iniciar automáticamente la siguiente pista

Tipos de disparador de BGM Condicional

Tipo de disparador	Cuándo se dispara	Uso típico
`variable`	Cuando se cumplen las condiciones de variable	hp < 20 reproduce música de crisis
`ai-keyword`	Cuando la respuesta de la IA contiene palabra clave	La IA escribe "explosion" reproduce SFX de explosión
`keyword`	Cuando el mensaje del jugador contiene palabra clave	El jugador dice "perform" reproduce música
`turn-count`	Cuando se alcanza un turno específico	Turno 10 reproduce música de cuenta atrás
`session-start`	Cuando comienza la sesión	Pista de apertura fija

Parámetros de la acción Reproducir Audio del comportamiento

Parámetro	Descripción
Track ID (`trackId`)	Coincide con el ID de pista registrado en la pestaña Audio
Operación (`action`)	`play` (reproducir), `stop` (detener), `crossfade` (cambio crossfade), `volume` (ajustar volumen)
Volumen (`volume`)	0-1, opcional
Duración del fundido (`fadeDuration`)	Segundos, opcional; 1.5-3 segundos recomendados para crossfade

API de audio del Root Component

Método	Descripción
`api.playAudio?.(trackId, opts)`	Reproduce una pista. opts puede incluir `fadeDuration` (segundos), `loop`, etc.
`api.stopAudio?.(trackId?)`	Detiene una pista. Omite el ID para detener todo
`api.pauseAudio?.(trackId)` / `api.resumeAudio?.(trackId)`	Pausa/reanuda una pista en el sitio (conserva la posición)
`api.onAudioEnded?.(cb)`	Suscríbete a eventos de pista terminada; devuelve una función para cancelar la suscripción. Úsalo para avanzar automáticamente una lista de reproducción

Problemas comunes

Síntoma	Causa probable	Solución
No hay sonido en absoluto	El navegador bloquea la reproducción automática	Los navegadores modernos requieren interacción del usuario (clic, escribir) antes de permitir la reproducción de audio. Haz que el jugador envíe un mensaje primero, o activa "Wait for First Message" en la playlist
La transición de BGM suena entrecortada	No se usa crossfade	Asegúrate de que la operación "Reproducir Audio" del comportamiento esté establecida en `crossfade` con una duración de fundido de al menos 1.5 segundos
SFX y BGM se interrumpen entre sí	`stopPreviousBGM` está establecido en `true`	Las reglas de BGM Condicional de tipo SFX deben tener "Detener BGM Actual" desactivado
La IA no usa directivas de audio	La entrada no le dice a la IA sobre ellas	Crea una entrada de System Presets listando todos los IDs de pista disponibles y formatos de directiva (mira el Patrón 7)
Ambient demasiado alto	Volumen demasiado alto	Ambient debería ser 0.2-0.4, con BGM en 0.5-0.7 para mantener la separación
BGM Condicional no se dispara	Desajuste de tipo de valor de variable	Asegúrate de que el tipo de valor de la condición coincida con el tipo de la variable (por ejemplo, las variables numéricas necesitan comparaciones numéricas, no comparaciones de cadenas)
Múltiples reglas en conflicto	Misma prioridad	Da a las diferentes reglas de BGM Condicional diferentes valores de prioridad — los números más altos tienen precedencia

Esta es la Receta #14: Guía de diseño de audio

La filosofía de diseño del sistema de audio es: las cosas simples simplemente funcionan (playlist + reproducción automática), y la complejidad se desbloquea por capas (BGM Condicional → control de comportamiento → directivas de IA → API personalizada). No necesitas aprender todos los patrones a la vez — empieza con el Patrón 1, y vuelve por más cuando necesites un control más fino.

Guía de diseño de audio ​

Visión general ​

Patrón 1: Configuración básica de BGM ​

Lo que vas a construir ​

Paso a paso ​

Paso 1: Sube pistas de audio ​

Paso 2: Configura la playlist ​

Resultado ​

Patrón 2: Crossfade de BGM en transiciones de escena ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Prepara pistas de audio ​

Paso 2: Crea una variable ​

Paso 3: Crea un comportamiento ​

Paso 4: Dispara desde el Root Component ​

Patrón 3: Efectos de sonido disparados por palabras clave ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Crea pistas SFX ​

Paso 2: Crea reglas de BGM Condicional ​

Resultado ​

Patrón 4: BGM Condicional — Cambio automático impulsado por variables ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Prepara pistas de audio ​

Paso 2: Crea una regla de BGM Condicional ​

Resultado ​

Patrón 5: Bucles de sonido ambiental ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Crea pistas Ambient ​

Paso 2: Controla el ambient mediante BGM Condicional ​

También puedes controlar el ambient mediante comportamientos ​

Patrón 6: Controlando audio desde el Root Component ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Prepara pistas de audio ​

Paso 2: Escribe el código del Root Component ​

Patrón 7: Control de audio impulsado por IA ​

Lo que vas a construir ​

Cómo funciona ​

Paso a paso ​

Paso 1: Registra todas las pistas que la IA podría usar ​

Paso 2: Dile a la IA qué pistas están disponibles mediante el prompt del sistema ​

Paso 3: Ejemplo de respuesta de IA ​

La directiva chain — uso especial ​

Referencia rápida exhaustiva ​

Tipos de pista ​

5 formas de controlar audio ​

Referencia de directivas de audio de la IA ​

Tipos de disparador de BGM Condicional ​

Parámetros de la acción Reproducir Audio del comportamiento ​

API de audio del Root Component ​

Problemas comunes ​

Guía de diseño de audio

Visión general

Patrón 1: Configuración básica de BGM

Lo que vas a construir

Paso a paso

Paso 1: Sube pistas de audio

Paso 2: Configura la playlist

Resultado

Patrón 2: Crossfade de BGM en transiciones de escena

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Prepara pistas de audio

Paso 2: Crea una variable

Paso 3: Crea un comportamiento

Paso 4: Dispara desde el Root Component

Patrón 3: Efectos de sonido disparados por palabras clave

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Crea pistas SFX

Paso 2: Crea reglas de BGM Condicional

Resultado

Patrón 4: BGM Condicional — Cambio automático impulsado por variables

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Prepara pistas de audio

Paso 2: Crea una regla de BGM Condicional

Resultado

Patrón 5: Bucles de sonido ambiental

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Crea pistas Ambient

Paso 2: Controla el ambient mediante BGM Condicional

También puedes controlar el ambient mediante comportamientos

Patrón 6: Controlando audio desde el Root Component

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Prepara pistas de audio

Paso 2: Escribe el código del Root Component

Patrón 7: Control de audio impulsado por IA

Lo que vas a construir

Cómo funciona

Paso a paso

Paso 1: Registra todas las pistas que la IA podría usar

Paso 2: Dile a la IA qué pistas están disponibles mediante el prompt del sistema

Paso 3: Ejemplo de respuesta de IA

La directiva `chain` — uso especial

Referencia rápida exhaustiva

Tipos de pista

5 formas de controlar audio

Referencia de directivas de audio de la IA

Tipos de disparador de BGM Condicional

Parámetros de la acción Reproducir Audio del comportamiento

API de audio del Root Component

Problemas comunes