Librería (aegisub)

Autortrotacalles

¿Para qué sirve?

Esta librería actúa como un puente entre la estructura de datos interna de Kara Effector y las funcionalidades principales de Aegisub. Su propósito es proporcionar herramientas para medir texto y, lo más importante, para pre-procesar y analizar la línea de subtítulos en sus diferentes componentes (palabras, sílabas, caracteres).

Las funciones con 2 en su nombre (ej. word2s) son funciones de “mapeo” que ayudan a relacionar un componente con otro (ej. “de palabra a sílaba”). Las funciones como line2W son funciones de “configuración” que procesan una unidad de texto grande (como una línea entera) y la dividen en una tabla estructurada de unidades más pequeñas (palabras), haciéndolas accesibles para bucles y efectos complejos.

Funciones

aegisub.word

aegisub.word(line_text, line_dur, ci_)

Una función de utilidad estructural fundamental que analiza una línea de texto completa y puebla la variable global word con los datos detallados de una palabra específica, identificada mediante su índice. Esta función es crucial cuando se necesita aislar las propiedades métricas y temporales de una palabra sin depender del ciclo de iteración automático del motor de plantillas. Al invocarse, descompone la cadena de texto, ignora las etiquetas override de ASS y recalcula los tiempos de inicio, fin y duraciones absolutas y relativas.

Argumentos

• line_text: string: El texto completo de la línea, incluyendo o excluyendo etiquetas dependiendo de la fase de renderizado.
• line_dur: number: La duración total de la línea en milisegundos, necesaria para calcular proporciones de tiempo.
• ci_: number: El índice numérico de la palabra específica de la que se requiere extraer la información métrica y temporal.

Principalmente diseñada para uso interno del motor o en funciones de nivel avanzado donde el creador del efecto necesita acceder asíncronamente a los metadatos de una palabra (como su posición en X/Y o su ancho) fuera del bucle de ejecución estándar (syl o char).

aegisub.word2s

aegisub.word2s()

Word to Syllable. Una función de mapeo de contexto inverso. En lugar de iterar de arriba hacia abajo, esta función determina el índice global de la palabra (Word) a la que pertenece la sílaba actual iterada (syl.i). Es excepcionalmente útil para agrupar sílabas lógicamente durante efectos de tipo “Template syl”, permitiendo, por ejemplo, que todas las sílabas de una misma palabra cambien al mismo color primario simultáneamente, o que compartan un mismo retraso (delay) en animaciones de entrada.

Argumentos

• Ninguno. La función hereda automáticamente el estado del contexto global de la sílaba que se está procesando actualmente.

Devuelve un número entero que representa el índice de la palabra madre (word.i).

Ejemplo

-- En un entorno de template por sílabas:
local indice_palabra = aegisub.word2s()
return "\\1c" .. colores_por_palabra[indice_palabra]

aegisub.wordsi

aegisub.wordsi(ws_)

Word Syllable Index. Una herramienta de indexación relacional. Dada una sílaba específica referenciada por su índice global, esta función no solo identifica a qué palabra pertenece, sino que calcula su posición relativa (índice local) dentro de esa palabra, así como la cantidad total de sílabas que componen dicha palabra. Esto abre la puerta a la creación de efectos tipográficos avanzados, como aplicar un modificador de escala masivo únicamente a la primera sílaba de cada palabra (efecto capitular), o retrasar la desaparición sistemáticamente hasta la última sílaba de la palabra.

Argumentos

• ws_: number: El índice global de la sílaba en la línea (normalmente se pasa la variable de entorno syl.i).

Devuelve dos valores numéricos simultáneos: indice_local_silaba (posición de la sílaba en la palabra actual) y total_silabas_en_palabra (longitud silábica total de la palabra).

Ejemplo

local i_local, n_total = aegisub.wordsi(syl.i)
-- Si es la última sílaba de la palabra, aplica un difuminado extendido
if i_local == n_total then return "\\blur5" else return "\\blur0" end

aegisub.syls2c

aegisub.syls2c()

Syllable to Characters. Una función destructiva de análisis tipográfico profundo. Analiza la sílaba actual (syl) retenida en memoria y la descompone atómicamente en sus caracteres individuales (incluyendo espacios o signos de puntuación si los hubiere). Como resultado de esta operación, sobrescribe/crea una nueva tabla global char que contiene información de granularidad extremadamente fina: tiempos de inicio/fin interpolados, posiciones relativas en X/Y, dimensiones (ancho/alto) y centro de cada glifo individual de la sílaba.

Argumentos

• Ninguno. Actúa directamente sobre el entorno virtual de la variable syl.

Se invoca en la casilla “Variables [fx]:” usando _ = aegisub.syls2c(). Una vez inicializada, habilita la capacidad de crear bucles anidados (for j=1, char.n do ...) en la fase de retorno, permitiendo animar una sílaba letra por letra (ej. un efecto de máquina de escribir fluida) sin perder la estructuración original de los tiempos de karaoke (\k).

aegisub.line2W / aegisub.line2S / aegisub.line2C

aegisub.line2W()

aegisub.line2S()

aegisub.line2C()

Line to Word / Syllable / Character. Son las funciones de pre-procesamiento jerárquico más robustas del entorno. Escapan del contexto microscópico de la iteración actual para realizar un escaneo completo y absoluto de la línea de subtítulos entera (linefx[ii]). Al ser llamadas, traducen la línea a una arquitectura de tablas multidimensionales (word, syl o char). Esto rompe las barreras de tiempo lineal del script, dándote acceso omnisciente: puedes saber las coordenadas exactas de la última palabra mientras apenas estás procesando y animando la primera.

Argumentos

• Ninguno. Operan sobre la base de datos de la línea madre actual.

Se llaman en “Variables [fx]:” (ej. _ = aegisub.line2W()) para instanciar la estructura de datos en memoria. Luego, en la declaración de salida “Return [fx]:”, puedes invocar dimensiones, tiempos o posiciones de entidades completamente ajenas a la iteración en curso.

Ejemplo

-- Conecta el centro de la tercera palabra de la línea con un efecto visual, sin importar en qué sílaba nos encontremos iterando.
return "\\pos("..word[3].center..","..word[3].middle..")" .. word[3].text

aegisub.word2S / aegisub.word2C

aegisub.word2S()

aegisub.word2C()

Word to Syllables / Characters. Actúan como contrapartes lógicas de las funciones line2*, pero restringiendo su radio de acción y análisis exclusivamente a los límites y dominios de la palabra actual iterada (word). Su función es seccionar quirúrgicamente una palabra en sus fragmentos menores (sílabas o caracteres), recalculando offsets de posición, anchos relativos y re-distribuyendo los tiempos parciales de manera equitativa o basándose en los tiempos de lectura detectados.

Argumentos

• Ninguno. Exigen como prerrequisito estricto que la variable global word ya haya sido procesada y se encuentre poblada en el entorno.

Son la piedra angular para construir arquitecturas de efectos multinivel fuertemente anidados. Por ejemplo: puedes iterar la línea por palabras con line2W, y en el interior de ese bloque, llamar a word2C para aplicar un comportamiento de dispersión de partículas individualizado letra por letra, pero manteniendo la coherencia gravitacional y temporal de la palabra entera.

aegisub.word2c

aegisub.word2c()

Word to character (index mapping). Función de emparejamiento semántico de bajo nivel. Determina de forma matemática a qué palabra padre pertenece un caracter específico que está siendo procesado actualmente (char.i). Analiza los índices, espacios en blanco y fronteras de las etiquetas para deducir la contención léxica.

Argumentos

• Ninguno. Absorbe los valores globales del iterador de caracteres actual.

Devuelve el valor numérico entero del índice de la palabra (word.i) que encapsula al caracter en cuestión. Es vital para aplicar lógicas condicionales a nivel de letra basadas en su ubicación dentro del flujo de palabras.

aegisub.wordci

aegisub.wordci(wc_)

Word Character Index. El equivalente microscópico de wordsi. Toma un caracter específico (identificado por su índice global absoluto en toda la línea) y realiza un cálculo de anclaje local para revelar qué posición ocupa dentro de los límites de su palabra matriz, así como la cantidad exacta de caracteres que construyen dicha palabra. Permite aplicar un degradado de color perfecto letra por letra dentro de una misma palabra, o resaltar la primera letra de cada término (Capitalización estilística por ASS).

Argumentos

• wc_: number: El índice absoluto y global del caracter, extraído típicamente de la variable de estado char.i.

Devuelve una dupla de valores: indice_local_caracter (su posición desde el inicio de la palabra actual) y total_caracteres_en_palabra (la longitud de la cadena de la palabra).

aegisub.width / aegisub.height

aegisub.width(string_txt)

aegisub.height(string_txt)

Funciones de renderizado en memoria e interfaces directas a la API interna de C++ de Aegisub (aegisub.text_extents). Calcular el ancho de un texto nunca es tan simple como contar sus letras, ya que el kerning, el interlineado, la familia tipográfica (font name), los estilos negrita/cursiva, las escalas dinámicas (\fscx, \fscy) y el espaciado entre letras (\fsp) alteran drásticamente sus dimensiones de salida. Estas funciones simulan un renderizado invisible en pantalla utilizando estrictamente la configuración del estilo (Style) de la línea actual, devolviendo los píxeles reales y exactos que ocupará ese fragmento de texto una vez dibujado.

Argumentos

• string_txt: string: La cadena de texto cruda o con etiquetas incrustadas que se desea pre-medir antes de procesarla en el render final.

Ejemplo

-- Obtiene el ancho absoluto de una sílaba para crear un recuadro (bounding box) de fondo perfecto que reaccione dinámicamente si cambias la fuente del estilo.
local ancho_real = aegisub.width(syl.text)
local alto_real = aegisub.height(syl.text)
return shape.rectangle(ancho_real, alto_real)

---

InicioVolver a la biblioteca de funciones