Skip to content

视频时间点笔记功能实现总结

1. 编辑方式

点击编辑之后,会用 Obsidian 打开。Obsidian 使用 Media Extended 插件来管理视频时间点笔记,非常好的插件。

在 Obsidian 中编辑的情况如下。视频上面那几个按钮可以快速定位笔记之类的,挺好的一个插件:

Obsidian 编辑视图

在浏览器中的情况如下。左侧上方是视频,左侧下方是笔记概览,右侧是笔记的具体内容,中间可以拉动分割线调整宽度:

浏览器视图

2. 文件组织方式

Media Extended 插件的组织方式如下。它会在主目录里加一个 media-lib 文件夹:

D:/Blog/done/
├── media-lib/
│   ├── index.base
│   └── 01_SpanTree_介绍.md
├── 系统性知识/Computer-Network/02.DataLink_Layer/04.SpanTree/
│   └── 01_SpanTree_介绍.mp4

media-lib 文件夹里面就是笔记文件,如下所示:

---
mx-uid: kvkq44gk4jogkal6uo08pgfx
video: "[[01_SpanTree_介绍.mp4]]"
duration: 787.64
aspect_ratio: 4 / 3
---
- [[01_SpanTree_介绍.mp4#t=00:02.29|00:02]] 标题一
这里面是详细解释,但不是一个单独文件

- [[01_SpanTree_介绍.mp4#t=00:03.98|00:03]] 标题二
[[04.添加问答样式]]

3. 解析细节

这部分由 media_notes.py 实现。

3.1 判断某个视频有没有笔记

很简单,就扫描 media-lib 文件夹下面的所有笔记文件,然后判断有没有 mx-uid 和 video 字段。其中 mx-uid 是 Media Extended 插件生成的唯一 ID,我们直接拿来用了,第 4 节会详细介绍它的作用。

mx-uid: kvkq44gk4jogkal6uo08pgfx
video: "[[01_SpanTree_介绍.mp4]]"

随后把 [[01_SpanTree_介绍.mp4]] 解析为实际视频路径:

链接形式 查找方式
绝对路径 检查该路径是否存在并允许处理
带目录的路径 分别检查以 done 根目录、以当前笔记目录为基准的路径;有多个有效目标则报歧义
只有文件名 优先查笔记所在目录;本目录没有时,查全局文件名索引中的唯一目标

找到后,内存中会保存两种映射:

notes[笔记绝对路径]    → MediaNote 记录
by_video[视频绝对路径] → 同一条 MediaNote 记录

所以,检查某个已解析的视频有没有媒体笔记,就是查询 by_video。

3.2 识别时间点

无非就是解析下面的格式,得到标题、时间、正文等:

- [[01_SpanTree_介绍.mp4#t=00:02.29|00:02]] 标题一
这里是解释

- [[01_SpanTree_介绍.mp4#t=00:03.98|00:03]] 标题二
[[04.添加问答样式]]

会得到如下结构(省略概述和警告):

[
    {'time': 2.29, 'title': '标题一', 'body': '这里是解释'},
    {'time': 3.98, 'title': '标题二', 'body': '[[04.添加问答样式]]'},
]

3.3 变成网页第一步:转 Markdown 文件

前面的解析已经得到时间、标题、正文。接下来,render() 把它们写进生成文件,大致如下,省略无关字段:

---
media_notes:
  entries:
    - time: 2.29
      title: 标题一
    - time: 3.98
      title: 标题二
---

<!--blog-media-note-0-->

这里是解释,**这句话是重点**。

<!--blog-media-note-end-0-->

<!--blog-media-note-1-->

**引用:** [About/04.添加问答样式.md](D:/Blog/done/About/04.添加问答样式.md)

# 添加问答样式

如图所示,样式如下:

![](D:/Blog/done/About/images/20260427180832.png)

……

<!--blog-media-note-end-1-->

比如视频叫 test.mp4,最后生成的文章就是 test.mp4.md。其实这一步即使没有笔记,也会生成这个文件,我们现在做的只是把一些笔记内容写进去。

视频如果没有笔记,就会生成如下内容(实际并不是这样,比如视频链接不是这种写法。不过这不在讨论范围内,这样写只是为了方便理解):

# 没有笔记的视频文件

![xxx](xxx.mp4)

3.4 变成网页第二步:转网页

然后 mkdocs 站点构建器开始把这份 Markdown 变成网页。

首先用的是 resource-content.html 模板。这个模板会判断 Markdown 头部有没有 media_notes 字段,有的话再进一步处理。

{% set rendered = namespace(content=page.content) %}

<!-- 这里是处理资源卡片,这个是其他设计,不在本文讨论范围内 -->
{% for resource in page.meta.resource_cards | d([]) %}
  {% set card %}{% include "partials/resource-card.html" %}{% endset %}
  {% set rendered.content = rendered.content | replace(resource.marker, card) %}
{% endfor %}

<!-- 这里是关键,如果有 media_notes,那么会调用 media-notes.html 模板 -->
{% if page.meta.media_notes %}{% include "partials/media-notes.html" %}{% endif %}
{{ rendered.content | safe }}

有 media_notes 字段时,就调用 media-notes.html。它的内容如下:

{# 1. 页面开头:打开总容器、左栏和播放器容器。 #}
{% set opening %}
<div class="blog-media-notes" data-media-notes="{{ notes.uid }}">
  <aside class="blog-media-left">
    <div class="blog-media-player">
{% endset %}

{# 2. 播放器之后:左侧目录和本地入口,然后打开右侧详情区。 #}
{% set middle %}
  <!-- ... 这里忽略 ... -->
{% endset %}

{# 3. 页面结尾:翻页按钮、状态提示,关闭右栏和总容器。 #}
{% set closing %}
  <!-- ... 这里忽略 ... -->
{% endset %}

{# 将三个布局片段放入正文的对应位置。播放器 HTML 已由资源模板插入。 #}
{% set rendered.content = rendered.content
  | replace('<!--blog-media-start-->', opening)
  | replace('<!--blog-media-player-end-->', middle)
  | replace('<!--blog-media-end-->', closing)
%}

{# 为每条已渲染的笔记正文加上详情容器和标题,供前端切换显示。 #}
{% for entry in notes.entries %}
  {% set panel %}
    <section
      class="blog-media-detail"
      id="media-note-{{ loop.index0 }}"
      aria-label="{{ entry.title }}"
    >
      <h2>{{ entry.title }}</h2>
  {% endset %}

  {% set start_marker = '<!--blog-media-note-' ~ loop.index0 ~ '-->' %}
  {% set end_marker = '<!--blog-media-note-end-' ~ loop.index0 ~ '-->' %}

  {% set rendered.content = rendered.content
    | replace(start_marker, panel)
    | replace(end_marker, '</section>')
  %}
{% endfor %}

其实最关键的一点,就是把 Markdown 里面的注释,也就是 blog-media-note,直接替换成 <section> 这类 HTML。

最终 HTML 的结构大致是:

<!-- 左侧目录 -->
<button>00:02.29</button>
<button>标题一</button>

<!-- 右侧详情 -->
<section id="media-note-0">
  <h2>标题一</h2>
  <p>这里是解释,<strong>这句话是重点</strong>。</p>
</section>

播放器、左右布局、拖动分界线、上一条和下一条,也都由模板和样式组合而成。

4. 持续维护

剩下的就是持续维护,即视频和笔记以后改名或移动之后,系统怎样继续记住它们的关系。

首次构建时,记下一份关联记录

系统从笔记头部找到视频后,会把结果保存到 media_notes.json 这个文件中。

{
  "kvkq44gk4jogkal6uo08pgfx": {
    "note_path": "media-lib/01_SpanTree_介绍.md",
    "source_link": "01_SpanTree_介绍.mp4",
    "video_path": "系统性知识/Computer-Network/02.DataLink_Layer/04.SpanTree/01_SpanTree_介绍.mp4",
    "video_sha256": "f1d745dc2a958759ff3b3c317c60a9bb876f7dc282969d284aaaf620a34e3711",
    "size": 22175522,
    "mtime_ns": 1694318621397934300,
    "dependencies": [
      "About/04.添加问答样式.md",
      "About/images/20260427180832.png",
      "media-lib/01_SpanTree_介绍.md"
    ]
  }
}

其中的键就是 mx-uid,是 Media Extended 给每个笔记生成的 ID,用来回答:这是哪一份笔记?

而 video_sha256 用来回答:视频内容和之前是否相同?只要视频字节没有改变,Hash 就保持一致。

视频改名后,怎么找回来

运行 UpdateBlog 时,正如第 3 节所说,脚本会扫描 media-lib 文件夹下面的所有笔记文件。每个文件如果顺利,会根据 video 字段找到原来的文件。

mx-uid: kvkq44gk4jogkal6uo08pgfx
video: "[[01_SpanTree_介绍.mp4]]"

假设把视频从 01_SpanTree_介绍.mp4 改成 生成树介绍.mp4,笔记里仍写着旧名字,按旧名字就找不到文件,于是流程是:

按笔记中的旧名字查找
    ↓ 找不到
根据 mx-uid 在 media_notes.json 中读取之前的关联记录
    ↓
在允许扫描的视频中,先筛选文件大小相同的候选
    ↓
比较候选视频与旧记录的 Hash
    ↓ 唯一匹配
找回视频,使用新路径生成学习页并更新登记表

找回视频后,修复笔记里的链接

上面这一步只找回视频,用来生成学习页并更新登记表,不会改笔记原文。笔记里的旧链接要另外修复。在 scripts/web 下运行:

python media_notes.py --repair-links
python media_notes.py --repair-links --apply

第一条只预览,第二条备份后写回原文。代码块里的链接不会改。

假设视频改名了,程序通过 Hash 找到了它,但笔记仍写着旧名称:

---
video: "[[01_SpanTree_介绍.mp4]]"
---

- [[01_SpanTree_介绍.mp4#t=00:02.29|00:02]] 标题一
这里是笔记正文。

假设找回的视频位于 课程/生成树介绍.mp4,修复后的原文就是:

---
video: "[[课程/生成树介绍.mp4]]"
---

- [[课程/生成树介绍.mp4#t=00:02.29|00:02]] 标题一
这里是笔记正文。

Comments

本文阅读 Loading 次 本站访问 Loading 次 访客 Loading 人