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.
text.upper( Text )Descripción: 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.
Argumentos:
Text (string, opcional): El texto a convertir. Si se omite este argumento, la función utilizará por defecto el texto completo de la línea actual (linefx[ii].text).Ejemplo de Uso:
-- 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)
text.lower( Text )Descripción: 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.
Argumentos:
Text (string, opcional): El texto a convertir. Si se omite, utiliza el texto de la línea actual.Ejemplo de Uso:
-- 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)
text.kara( )Descripción: 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.
Argumentos: Ninguno. Opera sobre la línea que se está procesando actualmente.
Ejemplo de Uso:
-- 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()
text.infx( syl_in_fx, true_false )Descripción: 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).
Argumentos:
syl_in_fx: El valor (string de texto, shape, número, etc.) que se debe retornar si la sílaba actual se encuentra dentro del rango +fx/-fx.true_false (boolean, opcional): Si se establece a true o 2, invierte la lógica de la función (ver text.outfx).Ejemplo de Uso:
-- 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.
text.outfx( syl_out_fx )Descripción: 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).
Argumentos:
syl_out_fx: El valor que se debe retornar si la sílaba actual está fuera del rango.Ejemplo de Uso:
-- 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.
text.karaoke_true( Table )Descripción: 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á.
Argumentos:
Table (table): Una tabla que contiene cadenas de texto.Ejemplo de Uso:
-- 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
text.remove_tags( text_string )Descripción: 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.
Argumentos:
text_string (string): La cadena de texto de la que se limpiarán las etiquetas.Ejemplo de Uso:
local texto_con_tags = "{\\b1\\c&HFFFFFF&}Texto en negrita"
local texto_limpio = text.remove_tags(texto_con_tags) -- Devuelve "Texto en negrita"
text.remove_space_in_tags( text_str )Descripción: 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).
Argumentos:
text_str (string): La cadena de texto con etiquetas a limpiar.Ejemplo de Uso: Usado internamente durante el pre-procesamiento de las líneas para asegurar la compatibilidad.
text.remove_extra_space( linetext_str )Descripción: 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.
Argumentos:
linetext_str (string): La cadena de texto a recortar.Ejemplo de Uso:
local texto = " Esto tiene espacios extra. "
return text.remove_extra_space(texto) -- Devuelve "Esto tiene espacios extra."
text.remove_syls_nil( linetext_str, linetext_dur )Descripción: 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.
Argumentos:
linetext_str (string): La línea de karaoke completa a limpiar.linetext_dur (number): La duración total de la línea.Ejemplo de Uso: Usado internamente para garantizar que los datos de karaoke sean consistentes antes de aplicar efectos.
text.to_word( l_text_str, l_text_dur )Descripción: 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.
Argumentos:
l_text_str (string): La línea de texto completa a procesar.l_text_dur (number): La duración total de la línea, utilizada para calcular los tiempos si no están presentes.Ejemplo de Uso:
-- Si line.text es "{\k20}Hola {\k30}Mundo", devuelve:
-- {"{\k20}Hola ", "{\k30}Mundo"}
local words_table = text.to_word(line.text, line.duration)
text.text2word( line_text_str, line_text_dur )Descripción: 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.
\k), las duraciones se suman por palabra.Argumentos: Mismos que text.to_word.
Ejemplo de Uso:
-- Devuelve: {"{\k20}Hola "}, {200}
words_table, durations_table = text.text2word("{\k20}Hola ", 200)
text.text2syl( line_text_str, line_text_dur )Descripción: 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.
Argumentos: Mismos que text.to_word.
Ejemplo de Uso:
-- Devuelve: {"{\k20}Ho", "{\k25}la"}, {200, 250}
syls_table, durations_table = text.text2syl("{\k20}Ho{\k25}la", 450)
text.text2char( line_text_str, line_text_dur ) y text.text2char2( ... )Descripción: Divide la línea de texto en sus caracteres individuales. Devuelve dos tablas: una con cada caracter como un string 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.
Argumentos: Mismos que text.to_word.
Ejemplo de Uso:
-- Si el texto es "{\k40}Hi", devuelve: {"H", "i"}, {200, 200}
chars_table, durations_table = text.text2char("{\k40}Hi", 400)
text.to_kara( String, K_mode )Descripción: 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.
Argumentos:
String (string): El texto a convertir.K_mode (string, opcional): El tipo de etiqueta de karaoke a usar. Opciones: "k", "kf", "ko". Por defecto es "k".Ejemplo de Uso:
-- Devuelve "{\k20}de{\k20}mo" asumiendo que la duración de "demo" era 400ms
return text.to_kara("demo")
text.syl2hiragana( Text )Descripción: 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.
Argumentos:
Text (string): La sílaba a convertir (ej. "ka", "カ").Ejemplo de Uso:
-- Devuelve "か"
return text.syl2hiragana("ka")
text.syl2katakana( Text )Descripción: Convierte una sílaba de texto, ya sea en romaji o hiragana, a su equivalente en katakana.
Argumentos:
Text (string): La sílaba a convertir (ej. "ka", "か").Ejemplo de Uso:
-- Devuelve "カ"
return text.syl2katakana("ka")
text.kana2romaji( Text )Descripción: Convierte una sílaba de texto, ya sea en hiragana o katakana, a su equivalente en romaji.
Argumentos:
Text (string): La sílaba a convertir (ej. "か", "カ").Ejemplo de Uso:
-- Devuelve "ka"
return text.kana2romaji("か")
text.text2stripped( text_str4 )Descripción: 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.
Argumentos:
text_str4 (string): El texto a limpiar.Ejemplo de Uso:
-- Devuelve "HolaMundo"
return text.text2stripped("{\b1}Hola Mundo")
text.char_size( )Descripción: 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.
Argumentos: Ninguno. Opera sobre las variables globales del efecto.
Ejemplo de Uso:
-- 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.
text.char2byte( string_text )Descripción: 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.
Argumentos:
string_text (string): La cadena de texto a convertir.Ejemplo de Uso (interno):
-- 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)
text.byte2char( table_bytes )Descripción: 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.
Argumentos:
table_bytes (table): La tabla de bytes a convertir.Ejemplo de Uso (interno):
-- 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)
text.text2part( line_text_str, line_text_dur, line_text_left, Parts )Descripción: 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.
Argumentos:
line_text_str (string): La línea de texto a dividir.line_text_dur (number): La duración de la línea.line_text_left (number): La coordenada X del inicio de la línea.Parts (number | table): El número de partes a crear. Si es un número, divide el texto en ese número de partes iguales. Si es una tabla como {min, max}, crea partes de longitud aleatoria entre min y max.Ejemplo de Uso:
-- 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)
text.inside( inside, Text )Descripción: 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.
Argumentos:
inside (string): La subcadena o patrón de búsqueda a encontrar.Text (string, opcional): El texto donde se realizará la búsqueda. Si se omite, utiliza el texto del objeto actual que se está procesando en el bucle (sílaba, caracter, etc.).Ejemplo de Uso:
-- 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
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.
text.to_shape( Text, Scale, Tags, Offset )Descripción: Es la función central de esta sección. Convierte una cadena de texto en una 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 una shape que puede ser manipulada por cualquier función de la librería shape.
Argumentos:
Text (string): El texto a convertir en figura.Scale (number, opcional): Un factor de escala para el tamaño de la shape resultante. Por defecto es 1.Tags (boolean, opcional): Si es true, la shape se devuelve envuelta en las etiquetas necesarias para ser usada directamente en un Return[fx] (ej. {\p1}m 0 0...). Si es false (por defecto), devuelve solo el código de la shape (m 0 0...).Offset (boolean, opcional): Si es true, el origen de coordenadas (0,0) de la shape se sitúa en la esquina superior izquierda del texto. Por defecto, está en la línea base de la fuente.Ejemplo de Uso:
-- 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
text.bord_to_shape( Text, Scale, Tags, Bord )Descripción: Similar a text.to_shape, pero en lugar de la forma rellena del texto, convierte su borde (outline) en una shape. El resultado es una figura que representa el contorno del texto.
Argumentos:
Text, Scale, Tags: Mismos argumentos que text.to_shape.Bord (number, opcional): El grosor en píxeles del borde que se quiere convertir a shape. Si se omite, utiliza el grosor del borde definido en el estilo de la línea.Ejemplo de Uso:
-- 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)
text.to_clip( Text, relative_pos, iclip, Scale )Descripción: 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.
Argumentos:
Text (string): El texto cuyas dimensiones se usarán para crear el clip.relative_pos (boolean, opcional): Si es true, las coordenadas del clip son relativas a la posición del objeto (sílaba, caracter). Si es false (por defecto), son relativas a las variables fx.move_l1, fx.move_t1.iclip (boolean, opcional): Si es true, genera un \iclip (recorte inverso), que oculta lo que está dentro y muestra lo que está fuera.Scale (number, opcional): Un factor para escalar el tamaño del clip.Ejemplo de Uso:
-- 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
text.to_pixels( Text, Mode, Shape, ... ) y text.bord_to_pixels( Text, Shape, ... )Descripción: 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.
Argumentos:
Text (string): Texto a convertir en píxeles.Mode (number | function, opcional): Un modo de animación predefinido para los píxeles (ej. 5 para un movimiento aleatorio) o una función personalizada que define la posición de cada píxel.Shape (string, opcional): La shape que se usará para representar cada píxel (por defecto, un cuadrado de 1x1).Ejemplo de Uso:
-- 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)
text.grid( Text, Filter, Align, Line )Descripción: 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 una única shape compuesta 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.
Argumentos:
Text (string): Texto a convertir en rejilla.Filter (string | function): Un filtro para colorear los píxeles. Puede ser la ruta a una imagen .bmp (para mapear sus colores) o una función que devuelve etiquetas (\1c, \1a) basadas en la posición del píxel.Align (number): Código de alineación de ASS (como \an7) si se usa una imagen.Line (boolean): Si es true, agrupa los píxeles por línea de texto (\N).Ejemplo de Uso:
-- 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)
text.gridr( Width, Height, Mode, Filter, Align, Lines )Descripción: Genera una 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.
Argumentos:
Width, Height (number): Ancho y alto del rectángulo de píxeles.Mode (string): "h" para barras horizontales, "v" para barras verticales, o por defecto para una cuadrícula.Filter (string | function): Mismo uso que en text.grid.Align (number): Mismo uso que en text.grid.Lines (number | table): Si se proporciona, divide la shape de salida en múltiples líneas de efecto.Ejemplo de Uso:
-- Crea un fondo de 100x100 píxeles con colores aleatorios.
return text.gridr(100, 100, nil, function() return "\\1c" .. color.random() end)
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.
text.tag( ... )Descripción: 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.
Argumentos:
... (string | table): Múltiples argumentos. El primero puede ser opcionalmente el texto a afectar. Los siguientes son las etiquetas a aplicar.{"\\tag", valor_inicial, valor_final, [valor_intermedio_1], ...}. La función interpola linealmente los valores numéricos entre el inicio y el final del texto.Ejemplo de Uso:
-- 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})
text.rand( Text, num_tran, dur_tran, ... )Descripción: 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.
Argumentos:
Text (string): El texto sobre el que se aplicará el efecto.num_tran (number): El número de caracteres aleatorios que aparecerán por cada caracter original.dur_tran (number): La duración en milisegundos (o frame_dur) de cada transición.extra_tags (string, opcional): Etiquetas adicionales para aplicar a los caracteres aleatorios (ej. \c, \blur).table_rand (table, opcional): Una tabla de caracteres para usar en la animación. Por defecto usa alfanuméricos.text_all (boolean, opcional): Si es true, aplica la animación a toda la línea de forma continua.Ejemplo de Uso:
-- 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())
text.inclip( Text )Descripción: 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.
Argumentos:
Text: El valor (texto, shape, etc.) que se retornará si el objeto está dentro del clip.Ejemplo de Uso:
-- 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)
text.outclip( Text )Descripción: 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.
Argumentos:
Text: El valor que se retornará si el objeto está fuera del clip.Ejemplo de Uso:
-- Se aplica un desenfoque a todo el texto que no esté dentro del área del clip.
return text.outclip("{\\blur2}" .. syl.text)
text.do_shape( Text, Shape, Scale, Mode, Tags, Split )Descripción: Proyecta o "pega" el texto a lo largo de la trayectoria de una 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.
Argumentos:
Text (string): El texto que se va a deformar.Shape (string): La shape que define la trayectoria.Scale (number, opcional): Factor de escala para el texto.Mode (number, opcional): Modo de alineación del texto sobre la shape. (1: centrado, 2: de inicio a fin, 3: de fin a inicio, 4: justificado).Tags (boolean, opcional): Si es true, devuelve el resultado envuelto en etiquetas {...}.Split (number, opcional): La precisión de la deformación (longitud de los segmentos).Ejemplo de Uso:
-- 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)
text.deformed( Text, Deformed, Pixel, Axis )Descripción: Aplica una deformación de onda sinusoidal al texto. Convierte el texto en una shape y luego aplica un filtro matemático a las coordenadas de sus puntos para crear un efecto ondulado.
Argumentos:
Text (string): El texto a deformar.Deformed (number): La frecuencia de la onda (cuántas "olas" completas hay).Pixel (number): La amplitud de la onda en píxeles (la altura de las "olas").Axis (string): El eje sobre el cual se aplica la deformación: 'x', 'y', o 'xy'.Ejemplo de Uso:
-- Hace que el texto de la sílaba ondule verticalmente.
return text.deformed(syl.text, 4, 10, "y")
text.deformed2( Text, Mode )Descripción: Aplica deformaciones más complejas y, a menudo, caóticas al texto. Convierte el texto en una shape y luego aplica algoritmos de transformación más avanzados que los de text.deformed.
Argumentos:
Text (string): El texto a deformar.Mode (number, opcional): Un número que selecciona un algoritmo de deformación predefinido.Ejemplo de Uso:
-- Aplica una deformación predefinida al texto de la sílaba.
return text.deformed2(syl.text, 2)
text.gradienth( ... )Descripción: Crea un degradado de color horizontal sobre el texto. Lo hace generando una shape compuesta por múltiples franjas verticales muy delgadas, cada una con un color interpolado. Esta shape se recorta con la forma del texto usando \clip.
Argumentos:
...: Una serie de colores en formato string ("&HFFFFFF&", "#00FF00", etc.) que definen los puntos clave del degradado.Ejemplo de Uso:
-- Crea un degradado de blanco a azul de izquierda a derecha sobre la sílaba.
return text.gradienth("&HFFFFFF&", "&H0000FF&")
text.gradienth2( ... )Descripción: 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.
Argumentos:
...: Una serie de colores que definen el degradado para toda la línea.Ejemplo de Uso:
-- En un Template [Syl], crea un degradado que fluye sin interrupciones a través de todas las sílabas.
return text.gradienth2("&HFFFFFF&", "&H0000FF&")
text.gradientv( ... )Descripción: Crea un degradado de color vertical sobre el texto. Funciona de manera similar a text.gradienth, pero generando franjas horizontales.
Argumentos:
...: Una serie de colores que definen los puntos del degradado de arriba hacia abajo.Ejemplo de Uso:
-- Crea un degradado de blanco a azul de arriba a abajo sobre la sílaba.
return text.gradientv("&HFFFFFF&", "&H0000FF&")
text.gradientangle( Angle, ... )Descripción: 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.
Argumentos:
Angle (number): El ángulo en grados del degradado. 0 es horizontal (de izquierda a derecha), 90 es vertical (de abajo hacia arriba)....: Una serie de colores en formato string ("&HFFFFFF&", "#00FF00", etc.) que definen los puntos clave del degradado.Ejemplo de Uso:
-- Crea un degradado diagonal (45°) de rojo a amarillo sobre la sílaba.
return text.gradientangle(45, "&H0000FF&", "&H00FFFF&")
text.maskclip( Fondo, Color, fxBord, fxMask, Shape, Space )Descripción: 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 una shape de fondo. A su vez, esta shape puede tener su propio color, borde y animaciones.
Argumentos:
Fondo (string): El color del texto que actúa como "marco" de la ventana.Color (string | table): El color o colores de la shape que se ve a través del texto.fxBord (string, opcional): Etiquetas adicionales para aplicar al borde del texto (ej. \blur).fxMask (string, opcional): Etiquetas adicionales para aplicar a la shape de fondo.Shape (string, opcional): La shape a usar como fondo. Por defecto, es un círculo.Space (number, opcional): Un factor de espaciado para la animación de la shape.Ejemplo de Uso:
-- 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")
text.bezier( Shape, Mode, Accel, Offset_time )Descripción: 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.
Argumentados:
Shape (string): La shape que define la trayectoria. Si se omite, usa una línea recta a lo largo de la línea de karaoke o el clip de la línea.Mode (number, opcional):
1-4: Modos de alineación estática (igual que math.bezier2).5-6: Modos de movimiento a lo largo de la curva (igual que math.bezier2move).Accel (number | string, opcional): Factor de aceleración para el movimiento.Offset_time (number, opcional): Desfase de tiempo para el inicio del movimiento.Ejemplo de Uso:
-- Mueve el texto de la sílaba a lo largo de un círculo durante su duración.
return text.bezier(shape.circle, 5)
text.filter( Text, Split, ... )Descripción: Aplica uno o más filtros (funciones de transformación de coordenadas (x, y)) directamente a la shape generada 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 de la shape del texto) dentro de la función de filtro.
Argumentos:
Text (string): El texto a convertir y filtrar.Split (number): La precisión (longitud de segmento) para aplanar las curvas del texto antes de aplicar el filtro. A menor valor, mayor precisión....: Una o más funciones de filtro. Cada función toma x e y como entrada y debe devolver las nuevas coordenadas.Ejemplo de Uso:
-- 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)
text.move( Text, Dx, Dy, Ox, Oy, Accel )Descripción: 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.
Argumentos:
Text (string): El texto a mover.Dx, Dy (string | number | table): Las trayectorias en los ejes X e Y. Pueden ser un número (desplazamiento simple), una shape (trayectoria compleja) o una tabla de valores y tiempos.Ox, Oy (number, opcional): Desplazamiento adicional (\fsp, \fscy).Accel (number, opcional): Factor de aceleración.Ejemplo de Uso:
-- Mueve la sílaba siguiendo la trayectoria de un círculo.
return text.move(syl.text, shape.circle)