Librería (text)

Autortrotacalles

¿Para qué sirve?

Este conjunto de funciones se enfoca en la manipulación, limpieza y análisis de las cadenas de texto. Son herramientas fundamentales para preparar los datos antes de aplicar efectos visuales, permitiendo desde simples cambios de mayúsculas/minúsculas hasta complejas verificaciones y correcciones de la estructura del karaoke.

Funciones

Convierte todos los caracteres alfabéticos de una cadena de texto a su versión en mayúsculas. Su principal ventaja sobre la función estándar de Lua es que preserva intactas todas las etiquetas de formato de ASS ({...}), procesando únicamente el texto visible.

Ejemplo

-- Convierte el texto de la sílaba actual a mayúsculas, manteniendo su tag \k
-- Si syl.text es "{\k25}hola", el resultado será "{\k25}HOLA"
return text.upper(syl.text)

Convierte todos los caracteres alfabéticos de una cadena de texto a su versión en minúsculas. Al igual que text.upper, preserva las etiquetas de formato ({...}) sin alterarlas.

Ejemplo

-- Convierte el texto de la línea a minúsculas
-- Si line.text_stripped es "KARAOKE TIME", el resultado será "karaoke time"
return text.lower(line.text_stripped)

Es una función interna que reconstruye la cadena de texto de la línea actual en un formato de karaoke temporizado básico. Itera sobre las sílabas ya procesadas por karaskel, toma sus duraciones y textos, y los une con etiquetas {\k...}. También fusiona etiquetas adyacentes si no hay texto entre ellas.

Ejemplo

-- Generalmente usado de forma interna para efectos que necesitan la línea reconstruida.
-- Si una línea fue procesada como dos sílabas, "Hola" (200ms) y "Mundo" (300ms),
-- esta función devolvería "{\k20}Hola{\k30}Mundo"
local karaoke_line = text.kara()

Es una función de filtro condicional que permite aplicar un efecto únicamente a un subconjunto de sílabas marcadas por el usuario. El efecto se activará para la sílaba que contenga +fx en su texto y continuará hasta la sílaba que contenga -fx (o hasta el final de la línea si no se encuentra -fx).

Ejemplo

-- Texto de la línea: Esta es una pala+fxbra de prue-fxba
-- En "Return[fx]":
return text.infx("{\\c&H0000FF&}" .. syl.text)

-- Resultado: Solo las sílabas "bra" y "de" se volverán azules.

Es la función complementaria a text.infx. Aplica un efecto a todas las sílabas que están fuera de un rango +fx/-fx. Es una forma abreviada de llamar a text.infx(valor, true).

Ejemplo

-- Texto de la línea: Esta es una pala+fxbra de prue-fxba
-- En "Return[fx]":
return text.outfx("{\\c&H808080&}" .. syl.text)

-- Resultado: Las sílabas "Esta", "es", "una", "pala" y "ba" se volverán grises.

Es una función de validación que comprueba si una tabla de fragmentos de texto (generalmente sílabas o palabras) contiene etiquetas de tiempo de karaoke (\k...). Devuelve true solo si todos los fragmentos están temporizados, y false en cuanto encuentra uno que no lo está.

Ejemplo

-- Usado internamente para decidir el método de temporización de efectos.
local syllables = {"{\\k20}Ho", "la"}
if not text.karaoke_true(syllables) then
    error("La línea no está completamente temporizada.")
end

Función de limpieza que elimina todas las etiquetas de formato ASS ({...}) de una cadena, devolviendo únicamente el texto visible. Es equivalente a la propiedad .text_stripped de los objetos línea/sílaba.

Ejemplo

local texto_con_tags = "{\\b1\\c&HFFFFFF&}Texto en negrita"
local texto_limpio = text.remove_tags(texto_con_tags) -- Devuelve "Texto en negrita"

Función de corrección para limpiar espacios en blanco innecesarios dentro de las etiquetas de formato. Un tag como {\b 1 \c &HFFFFFF&} puede causar errores, y esta función lo corrige a {\b1\c&HFFFFFF&}. Tiene excepciones para no romper etiquetas que legítimamente pueden contener espacios, como \fn (nombre de fuente) o \clip (figuras vectoriales).

Usado internamente durante el pre-procesamiento de las líneas para asegurar la compatibilidad.

Función de limpieza simple que elimina todos los espacios en blanco que se encuentren al principio y al final de una cadena de texto.

Ejemplo

local texto = "   Esto tiene espacios extra.   "
return text.remove_extra_space(texto) -- Devuelve "Esto tiene espacios extra."

Función de saneamiento de datos de karaoke. Analiza una línea temporizada y elimina las sílabas “nulas” o “fantasmas”, que son aquellas que no contienen texto visible (por ejemplo, {\k10} ). Reconstruye la línea para que solo contenga sílabas con contenido real, previniendo errores en bucles de efectos.

Usado internamente para garantizar que los datos de karaoke sean consistentes antes de aplicar efectos.

Esta es una función de análisis fundamental. Divide una línea de texto completa en una tabla donde cada elemento es una “palabra”. Una palabra se define como una secuencia de caracteres sin espacios, junto con las etiquetas de formato que la preceden.

Ejemplo

-- Si line.text es "{\k20}Hola {\k30}Mundo", devuelve:
-- {"{\k20}Hola ", "{\k30}Mundo"}
local words_table = text.to_word(line.text, line.duration)

Una versión más avanzada de text.to_word. No solo divide la línea en palabras, sino que también calcula y devuelve las duraciones de cada una. Devuelve dos tablas: una con las palabras y otra con sus respectivas duraciones en milisegundos.

Si la línea tiene tiempos de karaoke (\k), las duraciones se suman por palabra.
Si no, las duraciones se prorratean basándose en el número de caracteres de cada palabra.

Ejemplo

-- Devuelve: {"{\k20}Hola "}, {200}
words_table, durations_table = text.text2word("{\\k20}Hola ", 200)

Similar a text.text2word, pero opera a nivel de sílaba. Divide la línea de karaoke en una tabla de sílabas individuales, donde cada sílaba es una cadena que contiene su texto y sus etiquetas. Devuelve dos tablas: una con las sílabas y otra con sus duraciones.

Ejemplo

-- Devuelve: {"{\k20}Ho", "{\k25}la"}, {200, 250}
syls_table, durations_table = text.text2syl("{\\k20}Ho{\\k25}la", 450)

Divide la línea de texto en sus caracteres individuales. Devuelve dos tablas: una con cada caracter como una cadena de texto y otra con la duración calculada para cada uno. La duración se prorratea a partir de la duración de la sílaba a la que pertenece cada caracter. text.text2char2 es una variante interna con una lógica ligeramente diferente pero el mismo propósito.

Ejemplo

-- Si el texto es "{\k40}Hi", devuelve: {"H", "i"}, {200, 200}
chars_table, durations_table = text.text2char("{\\k40}Hi", 400)

Convierte una cadena de texto plano (generalmente en romaji) a un formato de karaoke temporizado, dividiéndolo en sílabas fonéticas japonesas y asignando etiquetas \k. Es una herramienta muy útil para generar karaokes básicos de forma automática a partir de texto sin formato.

Ejemplo

-- Devuelve "{\k20}de{\k20}mo" asumiendo que la duración de "demo" era 400ms
return text.to_kara("demo")

Convierte una sílaba de texto, ya sea en romaji o katakana, a su equivalente en hiragana. Utiliza tablas de conversión internas para realizar la transcripción.

Ejemplo

-- Devuelve "か"
return text.syl2hiragana("ka")

Convierte una sílaba de texto, ya sea en romaji o hiragana, a su equivalente en katakana.

Ejemplo

-- Devuelve "カ"
return text.syl2katakana("ka")

Convierte una sílaba de texto, ya sea en hiragana o katakana, a su equivalente en romaji.

Ejemplo

-- Devuelve "ka"
return text.kana2romaji("か")

Es una función de limpieza más agresiva. Elimina de una cadena de texto tanto las etiquetas de formato ({...}) como todos los espacios en blanco.

Ejemplo

-- Devuelve "HolaMundo"
return text.text2stripped("{\\b1}Hola Mundo")

Es una función interna de posicionamiento vertical. Analiza el caracter actual (val_text) y ajusta las variables globales c_top, c_bottom y c_height para reflejar con mayor precisión la altura visual del caracter. Tiene en cuenta si el caracter tiene trazos ascendentes (como ‘b’, ‘d’, ‘k’), descendentes (como ‘g’, ‘p’, ‘y’) o si es de altura media (como ‘a’, ‘c’, ‘e’). Esto permite que los efectos se alineen perfectamente con la forma de cada letra.

Ejemplo

-- Dentro de un bucle por caracteres, antes de calcular la posición del efecto.
text.char_size()
y = c_middle -- Usa la altura ajustada del caracter.

Es una función de utilidad de bajo nivel que toma una cadena de texto y la convierte en una tabla de números, donde cada número es el valor en bytes del caracter correspondiente. Es utilizada principalmente para validaciones internas y comprobaciones de integridad del script.

Ejemplo

-- Usado en la función effector.decide() para verificar que los nombres
-- y descripciones del script no hayan sido alterados.
local bytes_del_nombre = text.char2byte(script_name)

Es la función inversa de text.char2byte. Toma una tabla de valores numéricos en bytes y la convierte de nuevo en una cadena de texto.

Ejemplo

-- Usado para mostrar mensajes de error si la validación de bytes falla.
local mensaje_error = text.byte2char({ 78, 111, 32, 109, 111, ... })
error(mensaje_error)

Divide una línea de texto en un número determinado de “partes” o segmentos, que pueden abarcar múltiples caracteres. Devuelve un conjunto completo de tablas con las propiedades de cada parte: texto, duración, posición central, ancho, y coordenadas izquierda y derecha. Es ideal para efectos que necesitan agrupar caracteres en bloques de tamaño fijo o variable.

Ejemplo

-- Divide el texto de la línea en bloques de 3 caracteres cada uno.
local parts_text, parts_dur, parts_centers, ... = text.text2part(line.text_stripped, line.duration, line.left, 3)

Es una función de comprobación booleana muy flexible. Verifica si una subcadena o patrón está presente dentro del texto de un objeto (sílaba, palabra, línea). Es más genérica que text.infx y text.outfx, ya que puede buscar cualquier cadena, no solo +fx o -fx.

Ejemplo

-- En un Template [Syl], aplica un borde solo si la sílaba contiene la letra "a".
if text.inside("a", syl.text_stripped) then
    return "{\\bord1}" .. syl.text
else
    return syl.text
end

Funciones de conversión a gráficos

Este es el conjunto de funciones más potente de Kara Effector, ya que rompe la barrera entre el texto y las figuras. Permiten tratar las letras, palabras y líneas de texto como objetos gráficos vectoriales (shapes) o como matrices de píxeles, abriendo un abanico infinito de posibilidades para la manipulación y animación visual.

Es la función central de esta sección. Convierte una cadena de texto en un shape vectorial de ASSDraw. Utiliza la librería Yutils y las fuentes instaladas en el sistema para obtener el contorno exacto de cada caracter según el estilo de la línea. El resultado es un shape que puede ser manipulada por cualquier función de la librería shape.

Ejemplo

-- Convierte la sílaba en una shape y luego la rota 360 grados durante 1 segundo.
local mi_shape = text.to_shape(syl.text)
return "{\\t(0, 1000, \\frz360)}" .. mi_shape

Similar a text.to_shape, pero en lugar de la forma rellena del texto, convierte su borde (outline) en un shape. El resultado es una figura que representa el contorno del texto.

Ejemplo

-- Crea una shape que es solo el contorno del texto de la línea, con un grosor de 1px
return text.bord_to_shape(line.text_stripped, 1, true, 1)

Genera una etiqueta de recorte rectangular (\clip o \iclip) que se ajusta perfectamente a las dimensiones del texto proporcionado. Es una herramienta de alta precisión para efectos de revelado, enmascaramiento o barrido.

Ejemplo

-- Crea un clip del tamaño de la sílaba, que luego se anima con \t para revelarla.
local clip_inicial = text.to_clip(syl.text) -- \clip(x1,y1,x2,y2)
return "{\\t(0, 500, " .. text.to_clip("") .. ")" .. clip_inicial .. "}" .. syl.text

Convierten el texto (to_pixels) o su borde (bord_to_pixels) en una multitud de shapes de un solo píxel. Estas funciones están diseñadas para usarse en templates de tipo Shape, ya que generan una línea de efecto por cada píxel, permitiendo animaciones individuales. El bucle principal (j) del template itera a través de cada píxel generado.

Ejemplo

-- En un Template [Shape]
-- Desintegra el texto en píxeles que se mueven aleatoriamente.
-- La función se llama una vez, pero genera 'j' líneas de efecto.
return text.to_pixels(syl.text, 5)

Es una versión mucho más optimizada y eficiente de text.to_pixels. En lugar de crear una línea por píxel, genera un único shape compuesto que representa toda la rejilla de píxeles del texto, utilizando saltos de línea (\N) y movimientos para posicionar cada fila. El resultado es una sola línea de efecto.

Ejemplo

-- En un Template [Syl]
-- Muestra la sílaba como una rejilla de píxeles con colores aleatorios.
local filtro_color = function() return "\\1c" .. color.random() end
return text.grid(syl.text, filtro_color)

Genera un shape de rejilla de píxeles, pero en lugar de basarse en un texto, crea un rectángulo de dimensiones especificadas. Es perfecta para crear fondos, patrones o campos de partículas.

Ejemplo

-- Crea un fondo de 100x100 píxeles con colores aleatorios.
return text.gridr(100, 100, nil, function() return "\\1c" .. color.random() end)

Funciones de efectos visuales y deformación

Este grupo de funciones proporciona las herramientas para crear las animaciones y transformaciones visuales que definen un efecto. Incluyen desde la aplicación de etiquetas progresivas y efectos aleatorios hasta la deformación del texto para que siga trayectorias complejas o adopte nuevas formas.

Aplica un conjunto de etiquetas de formato de forma progresiva y interpolada a cada caracter de una cadena de texto. Es una herramienta extremadamente potente para crear degradados suaves, efectos de pulsación o cualquier animación que evolucione letra por letra a lo largo de una palabra o sílaba.

Ejemplo

-- Aplica un degradado de color (blanco a azul) y un efecto de crecimiento (fscy 100 a 150)
-- a cada letra de la sílaba.
return text.tag(syl.text, {"\\1c", "&HFFFFFF&", "&HFF0000&"}, {"\\fscy", 100, 150})

Genera un efecto de “máquina de escribir” o de “codificación/decodificación”. Cada caracter del texto original es reemplazado por una secuencia rápida de caracteres aleatorios antes de revelarse el caracter correcto.

Ejemplo

-- Efecto de decodificación para la sílaba, con 5 transiciones de 2 frames_dur cada una.
return text.rand(syl.text, 5, "2f", "\\1c" .. color.random())

Es una función de filtro condicional. Verifica si el centro del objeto actual (sílaba, caracter) se encuentra dentro del área definida por una etiqueta \clip o \iclip en la línea original. Si la condición se cumple, retorna el valor proporcionado.

Ejemplo

-- El texto se vuelve invisible solo si está dentro del área de un clip predefinido en la línea.
return text.inclip("{\\alpha&HFF&}" .. syl.text)

La función inversa de text.inclip. Verifica si el centro del objeto actual está fuera del área definida por un \clip o \iclip en la línea original.

Ejemplo

-- Se aplica un desenfoque a todo el texto que no esté dentro del área del clip.
return text.outclip("{\\blur2}" .. syl.text)

Proyecta o “pega” el texto a lo largo de la trayectoria de un shape. El texto se deforma y curva para seguir el contorno de la figura, permitiendo crear textos en arcos, círculos o cualquier forma personalizada.

Ejemplo

-- Escribe el texto de la línea siguiendo la forma de un círculo.
return text.do_shape(line.text_stripped, shape.circle, 1, 4, true)

Aplica una deformación de onda sinusoidal al texto. Convierte el texto en un shape y luego aplica un filtro matemático a las coordenadas de sus puntos para crear un efecto ondulado.

Ejemplo

-- Hace que el texto de la sílaba ondule verticalmente.
return text.deformed(syl.text, 4, 10, "y")

Aplica deformaciones más complejas y, a menudo, caóticas al texto. Convierte el texto en shape y luego aplica algoritmos de transformación más avanzados que los de text.deformed.

Ejemplo

-- Aplica una deformación predefinida al texto de la sílaba.
return text.deformed2(syl.text, 2)

Crea un degradado de color horizontal sobre el texto. Lo hace generando un shape compuesta por múltiples franjas verticales muy delgadas, cada una con un color interpolado. Este shape se recorta con la forma del texto usando \clip.

Ejemplo

-- Crea un degradado de blanco a azul de izquierda a derecha sobre la sílaba.
return text.gradienth("&HFFFFFF&", "&H0000FF&")

Una variante avanzada de text.gradienth diseñada para crear un degradado continuo y fluido a lo largo de toda la línea de karaoke. Mientras gradienth reinicia el degradado en cada sílaba, gradienth2 usa la función remember para que el degradado de una sílaba comience con el color exacto donde terminó la anterior.

Ejemplo

-- En un Template [Syl], crea un degradado que fluye sin interrupciones a través de todas las sílabas.
return text.gradienth2("&HFFFFFF&", "&H0000FF&")

Crea un degradado de color vertical sobre el texto. Funciona de manera similar a text.gradienth, pero generando franjas horizontales.

Ejemplo

-- Crea un degradado de blanco a azul de arriba a abajo sobre la sílaba.
return text.gradientv("&HFFFFFF&", "&H0000FF&")

Crea un degradado de color sobre el texto que se aplica en un ángulo personalizado, en lugar de ser estrictamente horizontal o vertical. Internamente, genera una rejilla de franjas de color y la rota (\frz) al ángulo especificado antes de usarla como máscara sobre el texto.

Ejemplo

-- Crea un degradado diagonal (45°) de rojo a amarillo sobre la sílaba.
return text.gradientangle(45, "&H0000FF&", "&H00FFFF&")

Es una de las funciones más complejas y versátiles para efectos de revelado. Crea un efecto de máscara donde el texto actúa como una “ventana” (\iclip) que revela un shape de fondo. A su vez, este shape puede tener su propio color, borde y animaciones.

Ejemplo

-- El texto es una ventana negra que revela un círculo azul con desenfoque.
-- El resultado final es un texto azul con borde negro desenfocado.
return text.maskclip("&H000000&", "&HFF0000&", "\\blur2")

Es una función “envoltorio” (wrapper) de alto nivel que simplifica enormemente la animación de texto a lo largo de una trayectoria. Internamente, llama a las funciones más complejas math.bezier2 (para posición estática) y math.bezier2move (para movimiento). Permite posicionar o mover texto a lo largo de cualquier shape.

Ejemplo

-- Mueve el texto de la sílaba a lo largo de un círculo durante su duración.
return text.bezier(shape.circle, 5)

Aplica uno o más filtros (funciones de transformación de coordenadas (x, y)) directamente al shape generado a partir de un texto. Es una versión de shape.filter específicamente adaptada para trabajar con texto, proporcionando acceso a variables de contexto como Mp (progreso a lo largo del shape del texto) dentro de la función de filtro.

Ejemplo

-- Deforma el texto de la sílaba aplicando una onda sinusoidal a sus puntos.
local filtro_onda = function(x, y)
    y = y + 10 * sin(Mp * 2 * pi)
    return x, y
end
return text.filter(syl.text, 2, filtro_onda)

Genera un efecto de movimiento complejo y fluido utilizando una técnica avanzada y eficiente. En lugar de usar \move, simula el desplazamiento con \fscx y \fscy sobre un píxel invisible (\p0), y luego renderiza el texto en esa posición. Esto permite movimientos no lineales (definidos por shapes o tablas de valores) con un rendimiento muy superior a \move.

Ejemplo

-- Mueve la sílaba siguiendo la trayectoria de un círculo.
return text.move(syl.text, shape.circle)

InicioVolver a la biblioteca de funciones