kara-templater 源码分析

1
aegisub.register_macro(tr"Apply karaoke template", tr"Applies karaoke effects from templates", macro_apply_templates, macro_can_template)
2
aegisub.register_filter(tr"Karaoke template", tr"Apply karaoke effect templates to the subtitles.\n\nSee the help file for information on how to use this.", 2000, filter_apply_templates)

1
type ProcessFunction = (subtitle: Subtitle, selected: lines[], active: number) => void;
2
declare function aegisub.register_macro(
3
  name: string,
4
  desc: string,
5
  processing: ProcessFunction,
6
  validation: ProcessFunction,
7
  is_active: ProcessFunction
8
)

1
type ConfigPanelFunction = (subtitles: Subtitle, old_settings: Table<Setting>) => Table<Dialog>;
2
declare function aegisub.register_filter(
3
  name: string,
4
  description: string,
5
  priority: number,
6
  processing: ProcessFunction,
7
  configuration_panel_provider
8
);

1
function macro_can_template(subs)
2
  -- 检测文件中是否有模板，当不存在模板时不允许宏运行
3
  local num_dia = 0
4
  for i = 1, #subs do
5
    local l = subs[i]
6
    if l.class == "dialogue" then
7
      num_dia = num_dia + 1
8
      -- 检测该行是否为 template 行
9
      if (string.headtail(l.effect)):lower() == "template" then
10
        return true
11
      end
12
      -- 不尝试匹配所有行以减短执行时间
13
      if num_dia > 50 then
14
        return false
15
      end
16
    end
17
  end
18
  return false
19
end

1
function macro_apply_templates(subs, sel)
2
  filter_apply_templates(subs, {ismacro=true, sel=sel})
3
  aegisub.set_undo_point("apply karaoke template")
4
end

1
-- 模板的主函数
2
function filter_apply_templates(subs, config)
3
  aegisub.progress.task("Collecting header data...")
4
  local meta, styles = karaskel.collect_head(subs, true)
5

6
  aegisub.progress.task("Parsing templates...")
7
  local templates = parse_templates(meta, styles, subs)
8

9
  aegisub.progress.task("Applying templates...")
10
  apply_templates(meta, styles, subs, templates)
11
end

1
-- 从字幕文件中收集样式和 metadata
2
function karaskel.collect_head(subs, generate_furigana)
3
  local meta = {
4
    -- X and Y script resolution
5
    res_x = 0, res_y = 0,
6
    -- 对视频和脚本分辨率不一致的修正因子
7
    video_x_correct_factor = 1.0
8
  }
9
  local styles = { n = 0 }
10
  local toinsert = {}
11
  local first_style_line = nil
12

13
  if not karaskel.furigana_scale then
14
    karaskel.furigana_scale = 0.5
15
  end

1
  -- First pass: collect all existing styles and get resolution info
2
  for i = 1, #subs do
3
    if aegisub.progress.is_cancelled() then error("User cancelled") end
4
    local l = subs[i]
5

6
    if l.class == "style" then
7
      if not first_style_line then first_style_line = i end
8
      -- Store styles into the style table
9
      styles.n = styles.n + 1
10
      styles[styles.n] = l
11
      styles[l.name] = l
12
      l.margin_v = l.margin_t -- convenience
13

14
      -- And also generate furigana styles if wanted
15
      if generate_furigana and not l.name:match("furigana") then
16
        aegisub.debug.out(5, "Creating furigana style for style: " .. l.name .. "\n")
17
        local fs = table.copy(l)
18
        fs.fontsize = l.fontsize * karaskel.furigana_scale
19
        fs.outline = l.outline * karaskel.furigana_scale
20
        fs.shadow = l.shadow * karaskel.furigana_scale
21
        fs.name = l.name .. "-furigana"
22

23
        table.insert(toinsert, fs) -- queue to insert in file
24
      end
25

26
    elseif l.class == "info" then
27
      -- Also look for script resolution
28
      local k = l.key:lower()
29
      meta[k] = l.value
30
    end
31
  end

1
  -- Second pass: insert all toinsert styles that don't already exist
2
  for i = 1, #toinsert do
3
    if not styles[toinsert[i].name] then
4
      -- 加入样式表
5
      styles.n = styles.n + 1
6
      styles[styles.n] = toinsert[i]
7
      styles[toinsert[i].name] = toinsert[i]
8
      -- 加入字幕文件
9
      subs[-first_style_line] = toinsert[i]
10
    end
11
  end

1
  -- 修复分辨率
2
  if meta.playresx then
3
    meta.res_x = math.floor(meta.playresx)
4
  end
5
  if meta.playresy then
6
    meta.res_y = math.floor(meta.playresy)
7
  end
8
  if meta.res_x == 0 and meta_res_y == 0 then
9
    meta.res_x = 384
10
    meta.res_y = 288
11
  elseif meta.res_x == 0 then
12
    -- This is braindead, but it's how TextSub does things...
13
    if meta.res_y == 1024 then
14
      meta.res_x = 1280
15
    else
16
      meta.res_x = meta.res_y / 3 * 4
17
    end
18
  elseif meta.res_y == 0 then
19
    -- As if 1280x960 didn't exist
20
    if meta.res_x == 1280 then
21
      meta.res_y = 1024
22
    else
23
      meta.res_y = meta.res_x * 3 / 4
24
    end
25
  end

1
  local video_x, video_y = aegisub.video_size()
2
  if video_y then
3
    -- Correction factor for TextSub weirdness when render resolution does
4
    -- not match script resolution. Text pixels are considered square in
5
    -- render resolution rather than in script resolution, which is
6
    -- logically inconsistent. Correct for that.
7
    meta.video_x_correct_factor =
8
      (video_y / video_x) / (meta.res_y / meta.res_x)
9
  end
10
  aegisub.debug.out(4, "Karaskel: Video X correction factor = %f\n\n", meta.video_x_correct_factor)
11

12
  return meta, styles
13
end

1
-- Find and parse/prepare all karaoke template lines
2
function parse_templates(meta, styles, subs)
3
  local templates = { once = {}, line = {}, syl = {}, char = {}, furi = {}, styles = {} }
4
  local i = 1
5
  while i <= #subs do
6
    aegisub.progress.set((i-1) / #subs * 100)
7
    local l = subs[i]
8
    i = i + 1
9
    if l.class == "dialogue" and l.comment then
10
      local fx, mods = string.headtail(l.effect)
11
      fx = fx:lower()
12
      if fx == "code" then
13
        parse_code(meta, styles, l, templates, mods)
14
      elseif fx == "template" then
15
        parse_template(meta, styles, l, templates, mods)
16
      end
17
      templates.styles[l.style] = true
18
    elseif l.class == "dialogue" and l.effect == "fx" then
19
      -- this is a previously generated effect line, remove it
20
      i = i - 1
21
      subs.delete(i)
22
    end
23
  end
24
  aegisub.progress.set(100)
25
  return templates
26
end

1
function parse_code(meta, styles, line, templates, mods)
2
  local template = {
3
    code = line.text,
4
    loops = 1,
5
    style = line.style
6
  }
7
  local inserted = false
8

9
  local rest = mods
10
  while rest ~= "" do
11
    local m, t = string.headtail(rest)
12
    rest = t
13
    m = m:lower()
14
    if m == "once" then
15
      aegisub.debug.out(5, "Found run-once code line: %s\n", line.text)
16
      table.insert(templates.once, template)
17
      inserted = true
18
    elseif m == "line" then
19
      aegisub.debug.out(5, "Found per-line code line: %s\n", line.text)
20
      table.insert(templates.line, template)
21
      inserted = true
22
    elseif m == "syl" then
23
      aegisub.debug.out(5, "Found per-syl code line: %s\n", line.text)
24
      table.insert(templates.syl, template)
25
      inserted = true
26
    elseif m == "furi" then
27
      aegisub.debug.out(5, "Found per-furi code line: %s\n", line.text)
28
      table.insert(templates.furi, template)
29
      inserted = true
30
    elseif m == "all" then
31
      template.style = nil
32
    elseif m == "noblank" then
33
      template.noblank = true
34
    elseif m == "repeat" or m == "loop" then
35
      local times, t = string.headtail(rest)
36
      template.loops = tonumber(times)
37
      if not template.loops then
38
        aegisub.debug.out(3, "Failed reading this repeat-count to a number: %s\nIn template code line: %s\nEffect field: %s\n\n", times, line.text, line.effect)
39
        template.loops = 1
40
      else
41
        rest = t
42
      end
43
    else
44
      aegisub.debug.out(3, "Unknown modifier in code template: %s\nIn template code line: %s\nEffect field: %s\n\n", m, line.text, line.effect)
45
    end
46
  end
47

48
  if not inserted then
49
    aegisub.debug.out(5, "Found implicit run-once code line: %s\n", line.text)
50
    table.insert(templates.once, template)
51
  end
52
end

1
-- List of reserved words that can't be used as "line" template identifiers
2
template_modifiers = {
3
  "pre-line", "line", "syl", "furi", "char", "all", "repeat", "loop",
4
  "notext", "keeptags", "noblank", "multi", "fx", "fxgroup"
5
}
6

7
function parse_template(meta, styles, line, templates, mods)
8
  local template = {
9
    t = "",
10
    pre = "",
11
    style = line.style,
12
    loops = 1,
13
    layer = line.layer,
14
    addtext = true,
15
    keeptags = false,
16
    fxgroup = nil,
17
    fx = nil,
18
    multi = false,
19
    isline = false,
20
    perchar = false,
21
    noblank = false
22
  }
23
  local inserted = false
24

25
  local rest = mods
26
  while rest ~= "" do
27
    local m, t = string.headtail(rest)
28
    rest = t
29
    m = m:lower()
30
    if (m == "pre-line" or m == "line") and not inserted then
31
      aegisub.debug.out(5, "Found line template '%s'\n", line.text)
32
      -- should really fail if already inserted
33
      local id, t = string.headtail(rest)
34
      id = id:lower()
35
      -- check that it really is an identifier and not a keyword
36
      for _, kw in pairs(template_modifiers) do
37
        if id == kw then
38
          id = nil
39
          break
40
        end
41
      end
42
      if id == "" then
43
        id = nil
44
      end
45
      if id then
46
        rest = t
47
      end
48
      -- get old template if there is one
49
      if id and templates.line[id] then
50
        template = templates.line[id]
51
      elseif id then
52
        template.id = id
53
        templates.line[id] = template
54
      else
55
        table.insert(templates.line, template)
56
      end
57
      inserted = true
58
      template.isline = true
59
      -- apply text to correct string
60
      if m == "line" then
61
        template.t = template.t .. line.text
62
      else -- must be pre-line
63
        template.pre = template.pre .. line.text
64
      end
65
    elseif m == "syl" and not template.isline then
66
      table.insert(templates.syl, template)
67
      inserted = true
68
    elseif m == "furi" and not template.isline then
69
      table.insert(templates.furi, template)
70
      inserted = true
71
    elseif (m == "pre-line" or m == "line") and inserted then
72
      aegisub.debug.out(2, "Unable to combine %s class templates with other template classes\n\n", m)
73
    elseif (m == "syl" or m == "furi") and template.isline then
74
      aegisub.debug.out(2, "Unable to combine %s class template lines with line or pre-line classes\n\n", m)
75
    elseif m == "all" then
76
      template.style = nil
77
    elseif m == "repeat" or m == "loop" then
78
      local times, t = string.headtail(rest)
79
      template.loops = tonumber(times)
80
      if not template.loops then
81
        aegisub.debug.out(3, "Failed reading this repeat-count to a number: %s\nIn template line: %s\nEffect field: %s\n\n", times, line.text, line.effect)
82
        template.loops = 1
83
      else
84
        rest = t
85
      end
86
    elseif m == "notext" then
87
      template.addtext = false
88
    elseif m == "keeptags" then
89
      template.keeptags = true
90
    elseif m == "multi" then
91
      template.multi = true
92
    elseif m == "char" then
93
      template.perchar = true
94
    elseif m == "noblank" then
95
      template.noblank = true
96
    elseif m == "fx" then
97
      local fx, t = string.headtail(rest)
98
      if fx ~= "" then
99
        template.fx = fx
100
        rest = t
101
      else
102
        aegisub.debug.out(3, "No fx name following fx modifier\nIn template line: %s\nEffect field: %s\n\n", line.text, line.effect)
103
        template.fx = nil
104
      end
105
    elseif m == "fxgroup" then
106
      local fx, t = string.headtail(rest)
107
      if fx ~= "" then
108
        template.fxgroup = fx
109
        rest = t
110
      else
111
        aegisub.debug.out(3, "No fxgroup name following fxgroup modifier\nIn template linee: %s\nEffect field: %s\n\n", line.text, line.effect)
112
        template.fxgroup = nil
113
      end
114
    else
115
      aegisub.debug.out(3, "Unknown modifier in template: %s\nIn template line: %s\nEffect field: %s\n\n", m, line.text, line.effect)
116
    end
117
  end
118

119
  if not inserted then
120
    table.insert(templates.syl, template)
121
  end
122
  if not template.isline then
123
    template.t = line.text
124
  end
125
end

1
  -- the environment the templates will run in
2
  local tenv = {
3
    meta = meta,
4
    -- put in some standard libs
5
    string = string,
6
    math = math,
7
    _G = _G
8
  }
9
  tenv.tenv = tenv

1
  tenv.retime = function(mode, addstart, addend)
2
    local line, syl = tenv.line, tenv.syl
3
    local newstart, newend = line.start_time, line.end_time
4
    addstart = addstart or 0
5
    addend = addend or 0

1
    if mode == "syl" then
2
      newstart = line.start_time + syl.start_time + addstart
3
      newend = line.start_time + syl.end_time + addend

1
    elseif mode == "presyl" then
2
      newstart = line.start_time + syl.start_time + addstart
3
      newend = line.start_time + syl.start_time + addend

1
    elseif mode == "postsyl" then
2
      newstart = line.start_time + syl.end_time + addstart
3
      newend = line.start_time + syl.end_time + addend

1
    elseif mode == "line" then
2
      newstart = line.start_time + addstart
3
      newend = line.end_time + addend

1
    elseif mode == "preline" then
2
      newstart = line.start_time + addstart
3
      newend = line.start_time + addend

1
    elseif mode == "postline" then
2
      newstart = line.end_time + addstart
3
      newend = line.end_time + addend

1
    elseif mode == "start2syl" then
2
      newstart = line.start_time + addstart
3
      newend = line.start_time + syl.start_time + addend

1
    elseif mode == "syl2end" then
2
      newstart = line.start_time + syl.end_time + addstart
3
      newend = line.end_time + addend

1
    elseif mode == "set" or mode == "abs" then
2
      newstart = addstart
3
      newend = addend

1
    elseif mode == "sylpct" then
2
      newstart = line.start_time + syl.start_time + addstart*syl.duration/100
3
      newend = line.start_time + syl.start_time + addend*syl.duration/100

1
    -- wishlist: something for fade-over effects,
2
    -- "time between previous line and this" and
3
    -- "time between this line and next"
4
    end

1
    line.start_time = newstart
2
    line.end_time = newend
3
    line.duration = newend - newstart
4
    return ""
5
  end

1
  tenv.fxgroup = {}

1
  tenv.relayer = function(layer)
2
    tenv.line.layer = layer
3
    return ""
4
  end

1
  tenv.restyle = function(style)
2
    tenv.line.style = style
3
    tenv.line.styleref = styles[style]
4
    return ""
5
  end

1
  tenv.maxloop = function(newmaxj)
2
    tenv.maxj = newmaxj
3
    return ""
4
  end
5
  tenv.maxloops = tenv.maxloop

1
  tenv.loopctl = function(newj, newmaxj)
2
    tenv.j = newj
3
    tenv.maxj = newmaxj
4
    return ""
5
  end

1
  tenv.recall = {}
2
  setmetatable(tenv.recall, {
3
    decorators = {},

1
    __call = function(tab, name, default)
2
      local decorator = getmetatable(tab).decorators[name]
3
      if decorator then
4
        name = decorator(tostring(name))
5
      end
6
      aegisub.debug.out(5, "Recalling '%s'\n", name)
7
      return tab[name] or default
8
    end,

1
    decorator_line = function(name)
2
      return string.format("_%s_%s", tostring(tenv.orgline), name)
3
    end,
4
    decorator_syl = function(name)
5
      return string.format("_%s_%s", tostring(tenv.syl), name)
6
    end,
7
    decorator_basesyl = function(name)
8
      return string.format("_%s_%s", tostring(tenv.basesyl), name)
9
    end
10
  })

1
  tenv.remember = function(name, value, decorator)
2
    getmetatable(tenv.recall).decorators[name] = decorator
3
    if decorator then
4
      name = decorator(tostring(name))
5
    end
6
    aegisub.debug.out(5, "Remembering '%s' as '%s'\n", name, tostring(value))

1
    tenv.recall[name] = value
2
    return value
3
  end

1
{\t(!remember("time", math.random(10,20)*10)!, !line.duration!, !recall.time!}

1
  tenv.remember_line = function(name, value)
2
    return tenv.remember(name, value, getmetatable(tenv.recall).decorator_line)
3
  end
4
  tenv.remember_syl = function(name, value)
5
    return tenv.remember(name, value, getmetatable(tenv.recall).decorator_syl)
6
  end
7
  tenv.remember_basesyl = function(name, value)
8
    return tenv.remember(name, value, getmetatable(tenv.recall).decorator_basesyl)
9
  end

1
  tenv.remember_if = function(name, value, condition, decorator)
2
    if condition then
3
      return tenv.remember(name, value, decorator)
4
    end
5
    return value
6
  end

1
  -- 运行所有的 code once 代码片段
2
  for k, t in pairs(templates.once) do
3
    assert(t.code, "WTF, a 'once' template without code?")
4
    run_code_template(t, tenv)
5
  end

1
function run_code_template(template, tenv)
2
  local f, err = loadstring(template.code, "template code")
3
  if not f then
4
    aegisub.debug.out(2, "Failed to parse Lua code: %s\nCode that failed to parse: %s\n\n", err, template.code)

1
  else
2
    local pcall = pcall
3
    setfenv(f, tenv)
4
    for j, maxj in template_loop(tenv, template.loops) do

1
-- 迭代器函数，返回一个以 tenv.j 和 tenv.maxj 控制的迭代器
2
function template_loop(tenv, initmaxj)
3
  local oldmaxj = initmaxj
4
  tenv.maxj = initmaxj
5
  tenv.j = 0
6
  local function itor()
7
    if tenv.j >= tenv.maxj or aegisub.progress.is_cancelled() then
8
      return nil
9
    else
10
      tenv.j = tenv.j + 1
11
      if oldmaxj ~= tenv.maxj then
12
        aegisub.debug.out(5, "Number of loop iterations changed from %d to %d\n", oldmaxj, tenv.maxj)
13
        oldmaxj = tenv.maxj
14
      end
15
      return tenv.j, tenv.maxj
16
    end
17
  end
18
  return itor
19
end

1
      local res, err = pcall(f)
2
      if not res then
3
        aegisub.debug.out(2, "Runtime error in template code: %s\nCode producing error: %s\n\n", err, template.code)
4
      end
5
    end
6
  end
7
end

1
  -- 开始处理行
2
  local i, n = 0, #subs
3
  while i < n do
4
    aegisub.progress.set(i/n*100)
5
    i = i + 1

1
    local l = subs[i]
2
    if l.class == "dialogue" and ((l.effect == "" and not l.comment) or l.effect:match("[Kk]araoke")) then

1
        l.i = i
2
        l.comment = false
3
        karaskel.preproc_line(subs, meta, styles, l)

1
      if apply_line(meta, styles, subs, l, templates, tenv) then
2
        -- 有样式应用到这行了 将其标记为 karaoke 行
3
        l.comment = true
4
        l.effect = "karaoke"
5
        subs[i] = l
6
      end
7
    end
8
  end
9
end

1
-- 预计算行的一些信息
2
-- 会修改 line 参数
3
function karaskel.preproc_line(subs, meta, styles, line)
4
  -- subs 参数不会用到 并且可能永远不会用到
5
  -- (哪一行突然改变 index 这件事情就不大对)
6
  -- 随便传入，但小心直接调用 preproc_line_pos，函数签名可能会变
7
  karaskel.preproc_line_pos(meta, styles, line)
8
end