Mnemosyne渲染管线揭秘:从Render Chain到过滤器,富媒体闪卡如何呈现
Mnemosyne渲染管线揭秘:从Render Chain到过滤器,富媒体闪卡如何呈现
Mnemosyne 是一款基于间隔重复算法的开源数字闪卡软件,支持图片、音频、视频、LaTeX 公式等富媒体卡片。本文带你快速搞懂它的核心机制——渲染管线(Render Chain):一张闪卡从数据库中的原始文本,到界面上带公式图片、音频播放器、CSS 样式的完整页面,究竟经历了哪些"加工工序"。
什么是 Mnemosyne 渲染管线?
Mnemosyne 把"原始卡片数据 → 可显示内容"的过程拆成了两个可插拔的组件层 🧩:
| 组件 | 职责 | 源码位置 |
|---|---|---|
| Filter(过滤器) | 对文本字符串做通用加工,如路径展开、HTML 转义 | filters/ |
| Renderer(渲染器) | 把加工后的字段拼装成最终格式(HTML 页面、纯文本等) | renderers/ |
| RenderChain(渲染链) | 定义"用哪些过滤器、按什么顺序、配哪个渲染器" | render_chain.py |
一句话概括:过滤器管"通用加工",渲染器管"按卡片类型排版"。一条渲染链 = 一串过滤器 + 一个渲染器,这正是富媒体闪卡得以灵活呈现的基础。
渲染管线三步走
每张卡片被提问/揭答案时,render_question / render_answer 会触发以下流程:
- 取原始数据:从卡片的 fact_view 中取出问题或答案对应的字段(fact_keys),得到纯文本数据;
- 逐字段过过滤器:文本按链中顺序依次穿过 Latex → EscapeToHtml → ExpandPaths 等过滤器;
- 渲染器拼装:Renderer 按卡片类型把各字段组装成完整 HTML 页面。
这里有个值得称道的性能设计:源码注释 明确说明——过滤器只作用于原始字段数据,而不是渲染器生成的完整 HTML。因为完整 HTML 体积大得多,逐字符过滤会慢得多。
内置过滤器逐个看:富媒体卡片的关键工序
默认的过滤器序列定义在 DefaultRenderChain,共 8 个过滤器,各显神通:
| 过滤器 | 干什么 | 典型效果 |
|---|---|---|
Latex |
把 <latex>、<$>、<$$> 标签调用 latex + dvipng 编译成公式图片 |
数学/化学卡片显示公式 📐 |
EscapeToHtml |
换行转 <br>,转义未闭合的 < |
纯文本卡片排版正常,不被误当标签 |
ExpandPaths |
把 src/data 中的相对路径展开为 file:// 绝对路径 |
<img src="cat.png"> 能真正加载本地图片 |
Html5Audio / QtAudio |
把 <audio> 标签升级为带自动播放、可续播的多文件播放器 |
听力卡片自动播放发音 🎧 |
Html5Video / QtVideo |
处理 <video> 标签 |
卡片内嵌视频片段 |
RTLHandler |
处理从右向左书写的语言(阿拉伯语、希伯来语等) | 文字方向正确 |
Furigana |
把 漢字[かんじ] 写法转成 <ruby> 注音标签 |
日语卡片带振假名 |
NonLatinFontSizeIncrease |
按配置给非拉丁字符(汉字、假名等)自动加大字号 | 中文/日文卡片更醒目 |
几个有趣的细节:
- LaTeX 图片带缓存:Latex 过滤器 用"公式 + 配置"的 MD5 值作为图片文件名,同一公式只编译一次,存在媒体目录的
_latex子目录里。配置改了、缓存删了也能自动重建。 - 过滤器顺序有讲究:
DefaultRenderChain的文档字符串特意注明——ExpandPaths和EscapeToHtml必须跑在Latex之后,因为 LaTeX 会生成带相对路径的<img>标签,需要由 ExpandPaths 补全。 - PyQt 界面换了音频/视频方案:桌面版 PyQtRenderChain 用 QtAudio/QtVideo 替代了 Web 版的 Html5Audio/Html5Video,其余过滤器保持一致。
从字段到整页:Renderer 如何拼装
过滤器加工完毕后,轮到渲染器上场。核心是 HtmlCss 渲染器:
- 按卡片类型生成 CSS:对齐方式、背景色、每个字段的字体/字号/颜色,都来自卡片类型属性(可在"管理卡片类型"里设置),并对生成的 CSS 做缓存,在手机上也不卡;
- 每个字段包进独立的
<div class="字段名">,卡片里写的表格等自定义 HTML 也能保留段落样式; - 页面内置
scroll_to_answer()脚本,点击"显示答案"时自动滚动到答案分隔线处。
除了 HTML,Mnemosyne 还内置了 PlainText 渲染器,只把各字段按序用换行拼接——导出文本文件时用的就是它。
多套渲染链:不同场景用不同配方
同一份卡片数据,在不同出口要用不同的"配方"。Mnemosyne 内置了 5 条渲染链:
| 渲染链(id) | 场景 | 过滤器 | 渲染器 |
|---|---|---|---|
default |
学习/浏览卡片 | 完整 8 个 | HtmlCss |
plain_text |
导出纯文本 | 无 | PlainText |
card_browser |
卡片浏览器列表 | 浏览器版转义 + RTL | HtmlCssCardBrowser |
sync_to_card_only_client |
同步给"只懂卡片"的客户端 | 转义 + Latex | HtmlCss |
web_server |
内置 Web 服务器远程学习 | Latex、转义、音频、视频等 | WebServerRenderer |
对应源码分别在 plain_text_chain.py、card_browser_render_chain.py、sync_to_card_only_client.py 和 web_server_render_chain.py。
注意 never_join_q_to_a 这个开关:卡片浏览器和纯文本链设为 True,禁止把问题拼进答案页面——因为在列表里预览答案时,合并显示没有意义。
QA_split 设置:问题与答案如何同屏
Mnemosyne 的"卡片布局"设置(QA_split)直接影响渲染:
- 选择单窗口(single_window)时,render_answer 会把问题字段和答案字段一起送进管线,中间插入
<hr id="answer">分隔线,一次渲染出完整页面; - 选择分窗口时,问题和答案各渲染各的,界面分别放进两个区域。
这也是渲染链与界面(ReviewWidget)解耦的方式:界面只负责调用 set_question / set_answer 接收成品 HTML,完全不知道过滤器是怎么工作的。
插件作者视角:如何给渲染管线加料
这套设计对插件非常友好。RenderChain 提供了运行时注册接口:
register_filter_at_front/register_filter_at_back:把自定义过滤器插到链头/链尾(可用类名字符串指定"插在某过滤器之后/之前",插件作者无需 import 官方过滤器);register_renderer:为新卡片类型注册专用渲染器,通过used_for属性声明适配的 CardType;- 若渲染逻辑实在不适配该模式,还可以直接在 CardType 子类里重写
render_question/render_answer。
小结
Mnemosyne 的渲染管线用"过滤器 + 渲染器 + 渲染链"三层结构,把富媒体闪卡的呈现问题拆解得清清楚楚:
- 过滤器负责通用文本加工:LaTeX 公式、媒体路径、HTML 转义、字体字号……按固定顺序流水线式执行;
- 渲染器负责按卡片类型拼装最终格式,并对样式做缓存;
- 渲染链为不同出口(学习、浏览器、导出、同步、Web)提供不同配方,且插件可随时增删工序。
理解了这套管线,你不仅能解释"Mnemosyne 为什么能把图片和公式塞进闪卡",还能动手写插件扩展它——比如加一个高亮关键词的过滤器,只需实现一个 run(text, card, fact_key) 方法即可。
更多源码细节可参考核心组件文档:libmnemosyne/docs/source/