Mnemosyne渲染管线揭秘:从Render Chain到过滤器,富媒体闪卡如何呈现

原创2026-11-16 11:45:582,341 阅读

Mnemosyne渲染管线揭秘:从Render Chain到过滤器,富媒体闪卡如何呈现

Mnemosyne 是一款基于间隔重复算法的开源数字闪卡软件,支持图片、音频、视频、LaTeX 公式等富媒体卡片。本文带你快速搞懂它的核心机制——渲染管线(Render Chain):一张闪卡从数据库中的原始文本,到界面上带公式图片、音频播放器、CSS 样式的完整页面,究竟经历了哪些"加工工序"。

什么是 Mnemosyne 渲染管线?

Mnemosyne 把"原始卡片数据 → 可显示内容"的过程拆成了两个可插拔的组件层 🧩:

组件 职责 源码位置
Filter(过滤器) 对文本字符串做通用加工,如路径展开、HTML 转义 filters/
Renderer(渲染器) 把加工后的字段拼装成最终格式(HTML 页面、纯文本等) renderers/
RenderChain(渲染链) 定义"用哪些过滤器、按什么顺序、配哪个渲染器" render_chain.py

一句话概括:过滤器管"通用加工",渲染器管"按卡片类型排版"。一条渲染链 = 一串过滤器 + 一个渲染器,这正是富媒体闪卡得以灵活呈现的基础。

渲染管线三步走

每张卡片被提问/揭答案时,render_question / render_answer 会触发以下流程:

  1. 取原始数据:从卡片的 fact_view 中取出问题或答案对应的字段(fact_keys),得到纯文本数据;
  2. 逐字段过过滤器:文本按链中顺序依次穿过 Latex → EscapeToHtml → ExpandPaths 等过滤器;
  3. 渲染器拼装: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 的渲染管线用"过滤器 + 渲染器 + 渲染链"三层结构,把富媒体闪卡的呈现问题拆解得清清楚楚:

  1. 过滤器负责通用文本加工:LaTeX 公式、媒体路径、HTML 转义、字体字号……按固定顺序流水线式执行;
  2. 渲染器负责按卡片类型拼装最终格式,并对样式做缓存;
  3. 渲染链为不同出口(学习、浏览器、导出、同步、Web)提供不同配方,且插件可随时增删工序。

理解了这套管线,你不仅能解释"Mnemosyne 为什么能把图片和公式塞进闪卡",还能动手写插件扩展它——比如加一个高亮关键词的过滤器,只需实现一个 run(text, card, fact_key) 方法即可。

更多源码细节可参考核心组件文档:libmnemosyne/docs/source/

登录后查看全文
mnemosyne