ai-zoomer/fork-from/tcax

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

Branch

Tag

bnc

refactor(效果引擎): 重构效果脚本时间窗口策略与层叠逻辑

857e5a60

15 commits

.codebuddy
doc
packages
test
tools
TCAX@f9860c66
.gitignore
.gitmodules
README.md
setup.bat
setup.sh

TINA Sub (Tcax In Node.js Architecture)

一个类似 TCAX 的特效字幕制作工具，用 TypeScript 从头重写。

项目结构

TCAX/                    # 原版 TCAX 参考
packages/
├── core/           # 纯 Node.js 字幕引擎（已完成）
├── web/            # React/Vue 前端 PWA（规划中）
└── electron/       # Electron 桌面客户端（可选）
tools/
└── ass-libass-screenshot/  # FFmpeg+libass 截图验证工具（全局命令: ass-sc）
test/                    # 测试用 TCC/ASS/字体文件
doc/                     # 项目文档

@tcax/core — 核心引擎

纯 TypeScript 实现，零原生依赖，可在无显示器的服务器上运行。

已完成功能

模块	状态	说明
ASS 解析/生成	✅ 完成	完整解析 Script Info / Styles / Events 三段式结构，支持 Format 行动态映射、时间转换、卡拉 OK 标签提取
SYL 音节解析	✅ 完成	三种 K Mode：syllable（逐字）/ word（原分段）/ advanced（两字一组），含翻译行去重与 Kar 时间矩阵
TCC 配置解析	✅ 完成	30+ 字段完整支持，round-trip 序列化，含默认配置工厂
特效脚本引擎	✅ 完成	动态 `import()` 加载用户 JS/TS 脚本，兼容 TCAX Python 命名约定（tcaxPy_Main/main），内置回退搜索机制
特效注册表	✅ 完成	6 大类别扫描（in/main/eft/out/ext/all）、元数据提取、运行时注册注销、多语言 i18n 搜索
渲染管线	✅ 完成	8 步流水线：TCC 解析 → ASS/SYL 构建 → 文本度量 → Init/Main/Fin 生命周期 → 排序输出
字体引擎	✅ 完成	双引擎架构：OpenTypeFont（fontkit，Node.js + 浏览器）+ CanvasFont（浏览器），支持 OS/2 修正、TTC 合集字库、Kerning 字距调整、逐字符定位缩放修正
TCAX API 层	✅ 完成	90+ 个 API 函数完全兼容 tcaxPy 命名：pos/move/fsc/frz/color/k/ko/kf/t/pix* 等
像素操作	✅ 纯 JS	9 个函数：pixPos/pixFromPoints/pixInvertA/pixR2A 等，Uint8Array 实现（暂无 WASM 加速）
CLI 命令行	✅ 基本完成	`tcax render <project.tcc>` + `--info` 模式
类型系统	✅ 完善	53 个 ValId 映射、i18n 元数据、EffectParamDef 支持 UI 编辑器
自动换行	✅ 完成	`auto wrap` 配置，超长行在词边界自动插入 `\N`
多行偏移	✅ 完成	同一时间戳多行字幕自动垂直偏移，避免重叠并防止超出边界

内置特效脚本

ID	类别	效果	多语言
`in_001`	入场	淡入 Fade In	zh/en/ja
`main_001`	主体验	静态显示 Static Display	zh/en/ja
`eft_001`	卡拉OK	变色 Color Change	zh/en/ja
`out_001`	出场	淡出 Fade Out	zh/en/ja

技术栈

TypeScript — ESM 模块，Node.js >= 18
@foliojs-fork/fontkit — 纯 JS OpenType 字体解析（唯一运行时依赖）

快速开始

# 方式一：一键安装（推荐）
bash setup.sh

# 方式二：手动安装
cd packages/core && npm install && npm run build && npm link
cd tools/ass-libass-screenshot && npm install && npm run build && npm link

# 渲染字幕项目
tcax render project.tcc -o output.ass -w ./workdir

# 查看项目配置信息
tcax render project.tcc --info

# 截图验证渲染效果（支持 MM:SS / H:MM:SS.cc / 秒小数 等格式）
ass-sc subtitle.ass --time 0:58 -o screenshot.png --fonts-dir ./fonts

TCC 项目文件格式

TCC 文件是 TCAX 的项目配置文件，纯文本格式，支持 ANSI/Unicode/UTF-8 编码。

配置字段详细说明： doc/parameters-vs-tcax.md（与原版 TCAX 差异）
从 Python 版本迁移要点： 见上述文档
示例测试文件： test/打上花火.tcc

部署方式

形态	说明
npx 直接运行	`npx @tcax/cli render project.tcc` 无需预安装
npm 全局安装	`npm i -g @tcax/cli && tcax render ...`
pkg 二进制	编译为单文件可执行，无需 Node.js 环境
Docker	`docker run tcax render ...`

tools/ass-libass-screenshot — 渲染验证工具（全局命令: `ass-sc`）

基于 FFmpeg + libass 的 ASS 字幕截图工具，产生与 mpv/VLC 像素级一致的渲染结果。用于验证 core 生成的 .ass 文件在播放器中的实际效果是否正确。

时间格式支持： MM:SS、H:MM:SS.cc、秒小数（58.5）、原始厘秒（整数）

# 全局命令使用（setup.sh 安装后）
ass-sc subtitle.ass --time 0:58 -o screenshot.png --fonts-dir ./fonts

# 或直接运行 node
node tools/ass-libass-screenshot/dist/index.js subtitle.ass -t 00:01:30 -o screenshot.png

开发计划

核心引擎已基本完成，下一步将开发 Web/PWA 前端编辑器。

测试用例

test/ 目录包含完整的端到端测试文件：

文件	说明
`打上花火.tcc`	TCC 项目配置（已从 Python 版迁移）
`打上花火j_k.ass`	K 时序 ASS 歌词文件
`msyh.ttc`	微软雅黑字体文件

运行测试：

# 渲染测试项目
tcax render test/打上花火.tcc -o test/output.ass -w ./test

# 验证渲染结果（截图指定时间点）
ass-sc test/output.ass --time 0:01:02.40 -o test/screenshot.png

# 列出所有字幕事件时间轴
ass-sc test/output.ass --list-times

# 合并命令
tcax render 打上花火.tcc -o 打上花火.ass ; ass-sc 打上花火.ass -o 打上花火.png -t 1.7