Esta librería proporciona un conjunto completo de herramientas para trabajar con colores. Permite convertir colores entre diferentes formatos (ASS, HTML, RGB, HSV), generar colores aleatorios, crear gradientes y secuencias de colores animados, y realizar manipulaciones avanzadas mediante matrices. Es fundamental para cualquier efecto que involucre cambios de color dinámicos.
color.ass( Color )Descripción: Normaliza un color de diferentes formatos al estándar de xy-vsfilter (&HBBGGRR&). Es capaz de interpretar colores en formato HTML (#RRGGBB) y en el formato de VSFilterMod (\1vc(...)), convirtiéndolos al formato ASS estándar.
Argumentos:
Color (string | table): El color a convertir. Puede ser una cadena de texto en formato ASS, HTML, o VSFilterMod.Ejemplo de Uso:
-- Convierte un color HTML rojo a formato ASS
return "\\1c" .. color.ass("#FF0000") -- Devuelve: \1c&H0000FF&
color.ass2( Rnum, Gnum, Bnum )Descripción: Convierte valores numéricos decimales de Rojo, Verde y Azul (RGB) a un string de color en formato ASS.
Argumentos:
Rnum, Gnum, Bnum (number): Valores de 0 a 255 para cada componente de color. También se puede pasar una tabla {R, G, B} como primer argumento.Ejemplo de Uso:
-- Crea un color amarillo
return "\\1c" .. color.ass2(255, 255, 0) -- Devuelve: \1c&H00FFFF&
color.ass3( Hnum, Snum, Vnum )Descripción: Convierte valores de Tono, Saturación y Valor (HSV) a un string de color en formato ASS. Es muy útil para crear gradientes o secuencias de colores que varían en el círculo cromático.
Argumentos:
Hnum (number): Tono (Hue), un valor de 0 a 360.Snum (number): Saturación (Saturation), un valor de 0 a 1.Vnum (number): Valor/Brillo (Value), un valor de 0 a 1.Ejemplo de Uso:
-- Genera un color que cambia a lo largo de las sílabas
return "\\1c" .. color.ass3(syl.i * 20, 1, 1)
color.to_RGB( Color )Descripción: Realiza la operación inversa a color.ass2. Convierte un string de color en formato ASS a una tabla con sus componentes RGB en valores decimales.
Argumentos:
Color (string): El color en formato ASS (ej. &H00FFFF&).Ejemplo de Uso:
-- En "Variables [fx]:":
mi_color_rgb = color.to_RGB("&H00FFFF&") -- Devuelve: {255, 255, 0}
color.to_HSV( Color )Descripción: Realiza la operación inversa a color.ass3. Convierte un string de color en formato ASS a una tabla con sus componentes HSV.
Argumentos:
Color (string): El color en formato ASS.Ejemplo de Uso:
-- En "Variables [fx]:":
mi_color_hsv = color.to_HSV("&H00FFFF&") -- Devuelve: {60, 1, 1}
color.random( H, S, V )Descripción: Genera un color aleatorio. Opcionalmente, se pueden restringir los rangos de Tono, Saturación y Valor para controlar el tipo de color generado.
Argumentos:
H, S, V (number | table, opcional): Restricciones para los componentes HSV. Pueden ser un número fijo o una tabla {min, max}.Ejemplo de Uso:
-- Genera un color totalmente aleatorio
return "\\1c" .. color.random()
-- Genera un tono aleatorio de azul/cian (entre 180 y 240)
return "\\1c" .. color.random({180, 240})
color.interpolate( Ipol, Color1, Color2 )Descripción: Interpola linealmente entre dos colores. Es idéntica a la función interpolate_color de utils-auto4.
Argumentos:
Ipol (number): El porcentaje de interpolación (de 0 a 1).Color1, Color2 (string): Los colores de inicio y fin en formato ASS.Ejemplo de Uso:
-- Crea un gradiente de color a lo largo de la sílaba
return "\\1c" .. color.interpolate(syl.progress, "&HFFFFFF&", "&H0000FF&")
color.set( Times, Colors, ... )Descripción: Crea una secuencia de transformaciones \t para cambiar de color en momentos específicos.
Argumentos:
Times (table): Una tabla con los milisegundos en los que ocurren los cambios.Colors (string | table): Un color o una tabla de colores a aplicar en cada tiempo.... (string, opcional): El tag de color a usar (ej. \1c, \3c). Por defecto es \1c.Ejemplo de Uso:
-- El color cambia a rojo en 500ms y a azul en 1200ms
return tag.set({500, 1200}, {"&H0000FF&", "&HFF0000&"}, "\\1c")
color.matrix( Color, ... )Descripción: Aplica una o más matrices de transformación 3x3 a los componentes RGB de un color. Es una función muy avanzada para efectos de manipulación de color complejos.
Argumentos:
Color (string): El color inicial en formato ASS.... (table): Una o más matrices 3x3 a aplicar secuencialmente.Uso: Avanzado. Se utiliza en combinación con funciones como math.matrix_rot para rotar colores en el espacio RGB.
color.fromstyle( ColorAlpha )Descripción: Extrae únicamente la parte del color (RGB) de un string ASS que contiene color y alpha (&HAABBGGRR).
Argumentos:
ColorAlpha (string): El string de color y alpha completo.Ejemplo de Uso: color.fromstyle(line.styleref.color1)
color.val2ass( val_R, val_G, val_B )Descripción: Función de utilidad interna, idéntica a color.ass2. Convierte valores decimales a un string de color ASS.
Argumentos:
val_R, val_G, val_B (number): Valores decimales de 0 a 255.color.HSV_to_RGB( Hue, Saturation, Value )Descripción: Función de utilidad interna, idéntica a color.ass3. Convierte valores HSV a un string de color ASS.
Argumentos:
Hue, Saturation, Value (number): Valores en el espacio HSV.Esta librería se especializa en la manipulación de la transparencia (alpha). Funciona de manera análoga a la librería color, pero aplicada a los tags de alpha (\alpha, \1a, \3a, \4a). Importante: Recuerda que en el formato de tags de ASS, un valor de alpha &H00& es totalmente opaco y &HFF& es totalmente transparente.
alpha.ass( Alpha )Descripción: Normaliza un valor de alpha de diferentes formatos al estándar de xy-vsfilter (&HAA&). Puede interpretar formatos como HTML (#AA).
Argumentos:
Alpha (string | number): El valor de alpha a convertir.Ejemplo de Uso:
-- Convierte un alpha HTML semitransparente a formato ASS
return "\\1a" .. alpha.ass("#80") -- Devuelve: \1a&H80&
alpha.random( Alpha1, Alpha2 )Descripción: Genera un valor de alpha aleatorio dentro de un rango.
Argumentos:
Alpha1, Alpha2 (number | string, opcional): Los límites inferior y superior del alpha a generar. Pueden ser decimales (0-255) o strings en formato ASS. Por defecto, el rango es de 0 a 255.Ejemplo de Uso:
-- Genera un alpha aleatorio entre opaco y semitransparente
return "\\1a" .. alpha.random(0, 128)
alpha.interpolate( Ipol, Alpha1, Alpha2 )Descripción: Interpola linealmente entre dos valores de alpha. Es idéntica a la función interpolate_alpha de utils-auto4.
Argumentos:
Ipol (number): El porcentaje de interpolación (de 0 a 1).Alpha1, Alpha2 (number | string): Los valores de alpha de inicio y fin.Ejemplo de Uso:
-- Crea un fundido de entrada (fade in) a lo largo de la sílaba
return "\\1a" .. alpha.interpolate(syl.progress, "&HFF&", "&H00&")
alpha.set( Times, Alphas, ... )Descripción: Crea una secuencia de transformaciones \t para cambiar el alpha en momentos específicos.
Argumentos:
Times (table): Una tabla con los milisegundos en los que ocurren los cambios.Alphas (number | string | table): Un valor de alpha o una tabla de alphas a aplicar.... (string, opcional): El tag de alpha a usar (\1a, \3a, etc.). Por defecto es \1a.Ejemplo de Uso:
-- El alpha del borde cambia a opaco en 500ms y a transparente en 1200ms
return tag.set({500, 1200}, {"&H00&", "&HFF&"}, "\\3a")
alpha.fromstyle( ColorAlpha )Descripción: Extrae únicamente la parte del alpha (&HAA&) de un string ASS que contiene color y alpha (&HAABBGGRR).
Argumentos:
ColorAlpha (string): El string de color y alpha completo.Ejemplo de Uso: alpha.fromstyle(line.styleref.color1)
alpha.val2ass( val_A )Descripción: Función de utilidad que convierte un valor numérico decimal (0-255) a su representación hexadecimal de dos dígitos para ser usada en tags de alpha (&HAA&). Importante: Esta función realiza una conversión directa (0 -> &H00&, 255 -> &HFF&).
Argumentos:
val_A (number): El valor decimal (0-255) a convertir.Ejemplo de Uso:
-- Crea un tag de alpha semitransparente
return "\\1a" .. alpha.val2ass(128) -- Devuelve: \1a&H80&