libass简明教程
[时间：2019-05] [状态：Open]
[关键词：字幕，libass，字幕渲染，ffmpeg, subtitles, video filter]
0 引言
libass库则是一个轻量级的对ASS/SSA格式字幕进行渲染的开源库。该库使用C编写，效率较高。据官方说明，libass和VSFilter兼容性最好~
libass依赖的第三方库是FreeType，FriBidi，NASM，Fontconfig（可选），HarfBuzz（可选）。
FreeType是libass使用的通用字体渲染库,也是很强大的库,作用是把系统的字库渲染成单张位图。
虽然官方源码提供的说明已经相对来说足够了，我编写此文主要的目的是学习下如何使用该库，并了解其基本构成。本文将包括：
- libass如何编译
- libass中demo源码解读
- libass主要对外接口
- ffmpeg中libass调用
1 libass编译
1.1 libass编译
首先从https://github.com/libass/libass.git中下载对应源码。
进入git所在的根目录，对应的可执行文件只有一个，autogen.sh，执行之。
这样会在当前目录下生成configure脚本，运行下面命令：
./configure
我的ubuntu（18.04）主机上遇到下面问题：
configure: error: Package requirements (fribidi >= 0.19.0) were not met:
No package 'fribidi' found
好吧。貌似是没有fribidi这个库，可以从https://github.com/fribidi/fribidi中下载对应源码，然后编译，命令类似：
./autogen.sh
./configure
make
sudo make install
然后重新运行以下命令：
./configure
make
这样基本编译完成。最终生成的libass.a位于./libass/.libs/目录下。
1.2 测试demo编译
当然在./test目录下还提供了一个libass库测试demo。为了编译之，我们需要将之前生成的libass.a拷贝到./test/.lib/目录下，并在./test目录下执行make命令，这样就会生成最后的可验证的测试程序（默认名字为test）。当然如果在编译中遇到错误，请按照错误提示添加确实的依赖项。比如我的主机遇到以下编译错误：
test-test.o: In function `write_png':
./test/test.c:53: undefined reference to `png_create_write_struct'
./test/test.c:54: undefined reference to `png_create_info_struct'
./test/test.c:57: undefined reference to `png_set_longjmp_fn'
./test/test.c:58: undefined reference to `png_destroy_write_struct'
./test/test.c:69: undefined reference to `png_init_io'
./test/test.c:70: undefined reference to `png_set_compression_level'
./test/test.c:72: undefined reference to `png_set_IHDR'
./test/test.c:76: undefined reference to `png_write_info'
./test/test.c:78: undefined reference to `png_set_bgr'
./test/test.c:84: undefined reference to `png_write_image'
./test/test.c:85: undefined reference to `png_write_end'
./test/test.c:86: undefined reference to `png_destroy_write_struct'
collect2: error: ld returned 1 exit status
Makefile:366: recipe for target 'test' failed
make: *** [test] Error 1
只要在Makefile中添加上png库的引用即可，即在LIBS最后添加-lpng。
执行test程序，有以下输出：
$ ./test
usage: ./test <image file> <subtitle file> <time>
这三个参数中第一个是输出png的路径，第二个是ass字幕文件路径，第三个time是渲染字幕文件中指定时间点，浮点数，单位为秒。
我们可以使用下面ass字幕作为测试，我将其保存在test同目录下，命名为a.ass
[Script Info]
; Script generated by FFmpeg/Lavc58.14.100
ScriptType: v4.00+
PlayResX: 384
PlayResY: 288
[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,16,&Hffffff,&Hffffff,&H0,&H0,0,0,0,0,100,100,0,0,1,1,0,2,10,10,10,0
[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.10,0:00:00.20,Default,,0,0,0,,1st just ass text
Dialogue: 0,0:00:00.20,0:00:00.30,Default,,0,0,0,,2nd info to show
Dialogue: 0,0:00:00.30,0:00:00.40,Default,,0,0,0,,3rd for order check
Dialogue: 0,0:00:07.25,0:00:14.45,Default,,0,0,0,,4th for time check
Dialogue: 0,0:00:15.22,0:00:23.30,Default,,0,0,0,,5th endline
然后我们执行下面命令将会看到字幕渲染之后的png。
./test out.png a.ass 0 # 0s无字幕，生成灰色空白图
./test out.png a.ass 0.15 # 0.15s有字幕，图片下方居中显示第一行字幕
./test out.png a.ass 0.5 # 0.5s无字幕，生成灰色空白图
./test out.png a.ass 7.26 # 7.26s有字幕，图片下方显示第四行字幕
具体效果图建议实际尝试下，这里不截图了。
2 demo源码解析
libass库中的test/test.c整体逻辑比较简单，总共200行左右代码量。主要完成了三部分内容：
- ass解析
- 文本-->图形转换
- 多图像叠加，rgb转png
具体实现代码如下：
// 初始化libass库
init(frame_w, frame_h);
// ASS文件读取并解析
ASS_Track *track = ass_read_file(ass_library, subfile, NULL);
// 渲染指定时间点的字幕，结果保存在img中，这可能是一个图片列表
ASS_Image *img = ass_render_frame(ass_renderer, track, (int) (tm * 1000), NULL);
// 多个ASS_Image合成为一个图片中
image_t *frame = gen_image(frame_w, frame_h);
blend(frame, img);
// 反初始化
ass_free_track(track);
ass_renderer_done(ass_renderer);
ass_library_done(ass_library);
// rgb保存为png
write_png(imgfile, frame);
free(frame->buffer);
free(frame);
3 libass库接口分析
libass库主要功能有两个：
- ass解析
- 字幕渲染
接口分为三类：
3.1 全局性接口
此类接口主要与ASS_Library相关，这是使用libass库必须打交道的结构体。主要包括以下几个常用接口：
int ass_library_version(void); // 获得库的版本号
// 这是使用ass库必须调用的第一个函数
ASS_Library *ass_library_init(void);
// ass库卸载函数，一般在程序退出时调用
void ass_library_done(ASS_Library *priv);
// 注册ass库消息回调函数
void ass_set_message_cb(ASS_Library *priv,
void (*msg_cb)(int level, const char *fmt, va_list args, void *data),
void *data);
// 获取可用的字体库
void ass_get_available_font_providers(ASS_Library *priv,
ASS_DefaultFontProvider **providers,
size_t *size);
3.2 ass解析接口
此类接口与ASS_Track直接相关，我们可以称之为字幕轨，具体相关接口如下：
// 创建和释放ASS_Track
ASS_Track *ass_new_track(ASS_Library *);
void ass_free_track(ASS_Track *track);
// 创建和释放style/event
int ass_alloc_style(ASS_Track *track);
int ass_alloc_event(ASS_Track *track);
void ass_free_style(ASS_Track *track, int sid);
void ass_free_event(ASS_Track *track, int eid);
// 解析ASS中的chunk数据
void ass_process_data(ASS_Track *track, char *data, int size);
void ass_process_chunk(ASS_Track *track, char *data, int size,
long long timecode, long long duration);
// 清空所有event
void ass_flush_events(ASS_Track *track);
// 使用本地文件或内存数据作为源创建ASS_Track
ASS_Track *ass_read_file(ASS_Library *library, char *fname,
char *codepage);
ASS_Track *ass_read_memory(ASS_Library *library, char *buf,
size_t bufsize, char *codepage);
3.3 字幕渲染接口
此类接口主要与ASS_Renderer有关，最终生成RGBA格式的ASS_Image。主要接口如下：
// 初始化及渲染结束
ASS_Renderer *ass_renderer_init(ASS_Library *);
void ass_renderer_done(ASS_Renderer *priv);
// 给定时间点渲染文本为图片格式
ASS_Image *ass_render_frame(ASS_Renderer *priv, ASS_Track *track,
long long now, int *detect_change);
最后一个结构体是ASS_Image，我们需要理解其具体构成才能使用其中存储的数据，其定义如下：
// 由ass renderer产生的图像链表
typedef struct ass_image {
int w, h; // Bitmap width/height
int stride; // Bitmap stride
unsigned char *bitmap; // 1bpp stride*h alpha buffer
// Note: the last row may not be padded to
// bitmap stride!
uint32_t color; // Bitmap color and alpha, RGBA
int dst_x, dst_y; // Bitmap placement inside the video frame
struct ass_image *next; // Next image, or NULL
enum {
IMAGE_TYPE_CHARACTER,
IMAGE_TYPE_OUTLINE,
IMAGE_TYPE_SHADOW
} type;
} ASS_Image;
4 ffmpeg中libass的使用
ffmpeg中有两个video filter是与libass库相关的，分别是ass和subtitles。前者仅支持ass格式字幕，后者支持所有格式字幕（实际上是subtitles filter将其他格式字幕转化为ass字幕，然后调用libass库）。
此处以ass filter为例说明下。
相关源码位于libavfilter/vf_subtitles.c中。ass filter定义如下：
AVFilter ff_vf_ass = {
.name = "ass",
.description = NULL_IF_CONFIG_SMALL("Render ASS subtitles onto input video using the libass library."),
.priv_size = sizeof(AssContext),
.init = init_ass,
.uninit = uninit,
.query_formats = query_formats,
.inputs = ass_inputs,
.outputs = ass_outputs,
.priv_class = &ass_class,
};
其实这个filter的代码只有两个主要的函数，init_ass和uninit。下面我们依次查看下其实现代码：
uninit函数很简单，代码如下：
static av_cold void uninit(AVFilterContext *ctx)
{
AssContext *ass = ctx->priv;
// 全部是关于ass资源释放的逻辑
if (ass->track)
ass_free_track(ass->track);
if (ass->renderer)
ass_renderer_done(ass->renderer);
if (ass->library)
ass_library_done(ass->library);
}
init_ass函数代码如下：
static av_cold int init_ass(AVFilterContext *ctx)
{
AssContext *ass = ctx->priv;
int ret = init(ctx);// 这个函数完成libass初始化
if (ret < 0)
return ret;
/* 初始化字体 */
ass_set_fonts(ass->renderer, NULL, NULL, 1, NULL, 1);
// 读取ass文件
ass->track = ass_read_file(ass->library, ass->filename, NULL);
if (!ass->track) {
av_log(ctx, AV_LOG_ERROR,
"Could not create a libass track when reading file '%s'\n",
ass->filename);
return AVERROR(EINVAL);
}
return 0;
}
static av_cold int init(AVFilterContext *ctx)
{
AssContext *ass = ctx->priv;
if (!ass->filename) {
av_log(ctx, AV_LOG_ERROR, "No filename provided!\n");
return AVERROR(EINVAL);
}
// 下面初始化基本上是使用libass库必须的
ass->library = ass_library_init();
if (!ass->library) {
av_log(ctx, AV_LOG_ERROR, "Could not initialize libass.\n");
return AVERROR(EINVAL);
}
ass_set_message_cb(ass->library, ass_log, ctx);
ass_set_fonts_dir(ass->library, ass->fontsdir);
ass->renderer = ass_renderer_init(ass->library);
if (!ass->renderer) {
av_log(ctx, AV_LOG_ERROR, "Could not initialize libass renderer.\n");
return AVERROR(EINVAL);
}
return 0;
}
还有两个重要的函数隐藏在ass_inputs数组中，定义如下：
static const AVFilterPad ass_inputs[] = {
{
.name = "default",
.type = AVMEDIA_TYPE_VIDEO,
.filter_frame = filter_frame,
.config_props = config_input,
.needs_writable = 1,
},
{ NULL }
};
第一个是config_input函数，用于设置ass字幕输出格式，实现如下：
static int config_input(AVFilterLink *inlink)
{
AssContext *ass = inlink->dst->priv;
ff_draw_init(&ass->draw, inlink->format, ass->alpha ? FF_DRAW_PROCESS_ALPHA : 0);
ass_set_frame_size (ass->renderer, inlink->w, inlink->h);
if (ass->original_w && ass->original_h)
ass_set_aspect_ratio(ass->renderer, (double)inlink->w / inlink->h,
(double)ass->original_w / ass->original_h);
if (ass->shaping != -1)
ass_set_shaper(ass->renderer, ass->shaping);
return 0;
}
第二个是filter_frame函数，用于获得字幕帧。实现如下：
static void overlay_ass_image(AssContext *ass, AVFrame *picref,
const ASS_Image *image)
{
for (; image; image = image->next) {
uint8_t rgba_color[] = {AR(image->color), AG(image->color), AB(image->color), AA(image->color)};
FFDrawColor color;
ff_draw_color(&ass->draw, &color, rgba_color);
ff_blend_mask(&ass->draw, &color,
picref->data, picref->linesize,
picref->width, picref->height,
image->bitmap, image->stride, image->w, image->h,
3, 0, image->dst_x, image->dst_y);
}
}
static int filter_frame(AVFilterLink *inlink, AVFrame *picref)
{
AVFilterContext *ctx = inlink->dst;
AVFilterLink *outlink = ctx->outputs[0];
AssContext *ass = ctx->priv;
int detect_change = 0;
double time_ms = picref->pts * av_q2d(inlink->time_base) * 1000;
ASS_Image *image = ass_render_frame(ass->renderer, ass->track,
time_ms, &detect_change);
if (detect_change)
av_log(ctx, AV_LOG_DEBUG, "Change happened at time ms:%f\n", time_ms);
overlay_ass_image(ass, picref, image);
return ff_filter_frame(outlink, picref);
}
相信在了解libass对外接口及demo逻辑之后，直接阅读上述代码并没有什么难度。
5 小结
看完libass的头文件，发现libass库本身很清晰，对外接口简单易懂，值得推荐。如果有任何不对的地方，欢迎指正。
本文整理并介绍了如何编译libass库，及其主要对外接口，并说明了ffmpeg中如何使用libass库的。仅供后续参考。
6 参考资料
----------------------------------------------------------------------------------------------------------------------------
本文作者：Tocy e-mail: zyvj@qq.com
版权所有@2015-2020，请勿用于商业用途，转载请注明原文地址。本人保留所有权利。
