Minor bugfixing in karaskel.

Added preliminary Automation 4 design docs.

Originally committed to SVN as r218.
This commit is contained in:
Niels Martin Hansen 2006-03-12 20:32:25 +00:00
parent 7b95ba47fb
commit 6ed6cfc289
3 changed files with 325 additions and 2 deletions

View file

@ -80,7 +80,7 @@ function karaskel.precalc_syllable_data(meta, styles, lines)
meta.res_y = 288
elseif meta.res_x == 0 then
-- This is braindead, but it's how TextSub does things...
if meta.res_x == 1024 then
if meta.res_y == 1024 then
meta.res_x = 1280
else
meta.res_x = meta.res_y / 3 * 4
@ -154,21 +154,27 @@ function karaskel.precalc_syllable_data(meta, styles, lines)
syl.inline_fx = inline_fx
-- Do positioning calculations, if applicable
sumtext = sumtext .. syl.text_stripped
karaskel.trace("new sumtext = " .. sumtext)
if karaskel.engage_positioning then
-- Summed text dimensions
local sumwidth = aegisub.text_extents(style, sumtext)
karaskel.trace("sumwidth = " .. sumwidth)
-- Strip some spaces
local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^(%s*)(.-)(%s*)$")
local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^([ \t]*)(.-)([ \t]*)$")
-- Pre/post space dimensions
local prespc_width = aegisub.text_extents(style, prespc)
local postspc_width = aegisub.text_extents(style, postspc)
karaskel.trace("space capture lengths = " .. string.len(prespc) .. ", " .. string.len(syltxt) .. ", " .. string.len(postspc))
karaskel.trace("space widths = " .. prespc_width .. ", " .. postspc_width)
-- Syllable dimensions
syl.width, syl.height, syl.ascent, syl.extlead = aegisub.text_extents(style, syltxt)
karaskel.trace("syllable text, width = " .. syltxt .. ", " .. syl.width)
karaskel.trace("precalc_syllable_data:8::")
-- Syllable positioning
syl.right = sumwidth - postspc_width
syl.left = sumwidth - syl.width + prespc_width
syl.center = math.floor(syl.left + (syl.right - syl.left) / 2)
karaskel.trace("syllable left, center, right = " .. syl.left .. ", " .. syl.center .. ", " .. syl.right)
if syl.furigana then
karaskel.calc_furigana_sizes(line, syl)
end

View file

@ -0,0 +1,141 @@
Automation 4 Basic Interface
This document described the basic functions needed to define an Automation 4
script. This covers Feature registration and the prototypes of functions used
to implement the various features.
---
Macro Registation Function
This is a function called from top-level of an Automation script to register
a new Macro Feature.
function aegisub.register_macro(
name,
description,
menu,
processing_function,
validation_function)
@name (string)
The displayed name of the menu item this macro will generate.
@description (string)
A longer description of the function of this macro. This will appear
on the status bar when hovering over the menu item.
@menu (string)
The menu this macro will appear in. Can be one of:
o "edit"
o "video"
o "audio"
o "tools"
o "right" (the subtitles grid right-click menu)
The menu chosen should be relevant to the function of the macro.
@processing_function (function)
The actual function called for the macro execution.
This function must be an instance of the Macro Processing Function
described below.
@validation_function (functioon)
Optional. A function called when it is to be determined whether the
macro can act on the current subtitles.
This function, if provided, must execute very quickly to avoid lag
in the GUI.
This function must be an instance of the Macro Validation Function
described below.
---
Filter Registration Function
This is a function called from top level of an Automation script to register
a new Export Filter Feature.
function aegisub.register_filter(
name,
description,
priority,
processing_function,
options_window_provider)
@name (string)
The name of the filter, as presented to the user.
@description (string)
A longer description of the filter presented to the user.
@priority (nhumber)
A number determining the default order the enabled filters will be
processed. The order can be overridden by the user.
Priorities of some built-in filters:
o Clean Script Info = 0
o Fix Styles = -5000
o Transform Framerate = 1000
Filters with higher priority will be executed earlier by default.
@processing_function (function)
The function called to do the actual filter processing.
This function must be an instance of the Filter Processing Function
described below.
@options_window_provider (function)
Optional. A function providing a dialog template for setting options
prior to filter processing.
This function must be an instance of the Filter Options Window Provider
function described below.
---
Format Reader Registration
This is a function called from top level in an Automation script to register
a new File Format Reader Feature.
function aegisub.register_reader(
name,
extension,
processing_function)
@name (string)
The name of the file format.
@extension (string)
The file extension usually given to this file format. This must not
include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
so on.)
@processing_function (function)
The function called to do the actual file import.
This function must be an instance of the Format Reader Function described
below.
---
Format Writer Registration
This is a function called from top level in an Automation script to register
a new File Format Writer Feature.
function aegisub.register_writer(
name,
extension,
processing_function)
@name (string)
Name of the file format, as presented to the user.
@extension (string)
The usual file extension given to this file format. This is automatically
be attached to the file name on export, unless the user chooses to
override it.
@processing_function (function)
The function doing the actual file export.
This function must be an instance of the Format Writer Function described
below.
---

View file

@ -0,0 +1,176 @@
Aegisub Automation documentation
Version 4
Copyright 2005-2006 Niels Martin Hansen
THIS IS A DRAFT. SUBJECT TO CHANGE.
Last updated: 2006-02-01 04:17 UTC+1
---
This document describes version 4 of the automation system used in Aegisub.
The automation system uses the Lua language for scripting engine.
See <http://www.lua.org/> for more information.
---
Overview
Aegisub Automation is a scripting environment that allows you to automate
almost any task working with subtitles in Aegisub, ie. a macro environment.
Automation allows you to:
- Create macros (adding extra menu items to the main menu)
o Those macros can optionally also display dialog boxes to the user
o Allows adding new features to Aegisub without recompiling the entire
program!
- Write export filters
o This is what Automation 3 did, but with more options
o Useful for adding complicated special effects to a script
- Write file-format importers and exporters
o Load every strange subtitle format you come by
o Save in those formats as well
o Exporters write directly to a file stream, allowing you to generate
those huge karaoke effects much faster!
---
Scripts, files functions
An automation script is a Lua script following certain conventions described
in this document. A script consists of one or more files, with one of them
being the master script, and the others being include files.
Every script runs in a separate Lua interpreter, so separate scripts cannot
communicate directly with each other. Scripts can share code by having common
include files.
Files containing Automation scripts must in UTF-8 encoding, with or without
BOM (Byte Order Mark). Compiled Lua scripts should also work, as long as all
strings are UTF-8 encoded, but this is untested and unsupported.
Automation scripts implement one or more of four possible features. A feature
is implemented by filling a specially named global table with certain values.
See below for a discussion about the various features and how they differ.
---
Scriptable features
The following four features can be implemented by an Automation script:
- Macro
A macro is presented as a new menu item in the Automation menu on the menu
bar in Aegisub. When the user select the menu item, a function in the
Automation script is called to do processing. Features are present to allow
direct interaction with the subtitle data.
The macro can create and display dialog windows to the user.
For preformance-reasons, there is currently no provision for the script to
enable/disable its menu item based on eg. the selection in the Aegisub
subtitles grid.
- Export filter
An export filter is presented as a filter in the Export dialog accessed
from the File menu. The export filter is called when the user uses the
Export feature. The export filter is given access every line (including
Styles and Script Info lines) in the subtitle file, and can add/modify/
remove lines in those.
The export filter can specify a static configuration dialog presented to
the user in the Export UI.
The export filter can specify a function that's run after the user selects
the Export item on the File menu, but before the Export dialog is actually
displayed. This function will be given access to the subtitles currently
loaded. This is to feature customising the configuration dialog based on
the contents of the subtitles.
It is strongly discouraged to change anything but a single, private Script
Info header line in the subtitles handed to this initialisation function.
- File format reader
It is not yet decided how the file format reader is accessed.
Current ideas:
o It provides two functions, one to test whether it can handle a given
file and one to actually convert that file to ASS. Which import filter
to use is decided by Aegisub, based on the result of the first function.
o The user selects an import filter and a file. The import filter is
applied to the selected file.
The file format reader can present dialog windows to the user.
The file format reader is given access to the raw file stream.
- File format writer
The file format writer is selected in the Export dialog access from the
File menu. The file format writer is handed all the lines of the subtitles
file and a file stream to write to.
The file format writer can report itself as writing a binary format or a
text format. In the case of a text format, all output is passed through the
character set conversion routines in Aegisub.
The file format writer can present dialog windows to the user.
Every feature is given access to the following in addition to what's described
above:
- Displaying/hiding/updating a progress bar.
- Outputting messages to the user.
- Accessing framerate data
- (Not fully decided yet) Raw video frame data (RGB and/or YUV)
- (Not fully decided yet) Raw and FFT transformed wave data
- (Not fully decided yet) Utilising FexTracker functions
- Calculating the rendered size of a text string, given a style definition
---
Script registration
Scripts can be loaded in two ways, through autoload or by assigning them to
a subtitle file.
Autoloading of scripts happens by placing the master script file into the
"automation/autoload" directory under the Aegisub installation directory.
Assining scripts to a subtitle file is done through the Automation Manager
GUI. Scripts assigned to a subtitle file are stored in the ASS Script Info
line "Automation Scripts", using a pipe character as separator between the
master script filenames.
The automatic loading/storing of configuration options from Automation 3 has
been removed, but can still be implemented in an Export Filter feature using
the initialisation function.
---
Actual documentation for functions, data structures and other interfaces is
yet to be written.
---
Versions of the scripting interface
Here's a quick history of the scripting interface:
Version 1
Using Lua as engine.
The scripts used in the Karaoke Effector application, avaible at:
<http://www.jiifurusu.dk/files/programming/effector/> (currently down)
Version 2
Using Python as engine.
The first draft for an Aegisub automation engine.
Never implemented.
Version 3
Using Lua as engine.
Aegisub 1.10 was the last version to use Automation 3.
(Tentative release date only!)
Version 4
Using Lua as engine
Present in Aegisub 1.11 and later (tentative!)
Heavily expanded feature set, allowing a much wider range of modifications,
and more direct integration into the Aegisub user interface.