映阅 Lumen

在 Obsidian 中集中浏览图片、视频、音频、文档、电子书和数据文件，并把观看与阅读过程接到笔记中。

A local media library and multi-format viewer for Obsidian, with a vault-wide sidebar, native folder navigation, image tools, subtitle playback, and attachment notes. The interface currently focuses on Chinese.

下载最新安装包 · 功能与边界 · 验收记录 · 提交问题 · 参与开发

当前公开版本为 0.3.0，通过 GitHub Releases 分发；尚未上架 Obsidian 社区插件目录。

这是基于 Omni Viewer 0.9.0 的 MIT 开源分支。基础版本固定为 85c278e90704dc6cd8cf038c03bd611f9fa2a5d4，解析核心固定为 omni-viewer-core 0.17.0。中文媒体库、媒体交互、图片工具、附件笔记、EPUB/ODF 整合和阅读状态管理为本分支新增。

开始使用

1. 原生文件夹树照常使用：展开目录，点击图片、视频、音频、PDF、Office、电子书等支持的附件即可打开。Markdown 笔记仍进入 Obsidian 原生编辑器。
2. 点击文件夹树上方「映阅全仓库面板」，在中间打开整个仓库的附件网格，左侧文件夹树继续保留。右键文件夹还能选择「用映阅浏览此文件夹（含子文件夹）」。
3. 若文件已由 Obsidian 或其他插件接管，右键文件，选择「用映阅打开」。
4. 查看器上方可以收藏、添加标签、摘录、打开附件笔记，或在「更多」菜单调用系统程序。
5. 仓库中的 fixtures/映阅体验/ 提供独立样例，可复制到自己的测试仓库体验；安装包不自动添加这些文件。

需要紧凑附件列表时，点击最左侧竖栏顶部带「映阅」文字的光圈图标，或按 Ctrl+P 搜索「映阅」，选择「打开左侧栏（全仓库附件）」。侧栏支持类型、名称、路径和标签筛选，点击结果在中间打开，已有文件复用标签页。

附件侧栏顶部「返回文件夹」可回到原生文件夹树；完整媒体库右上方「文件夹」按钮也可切回。侧栏底部「打开完整媒体库」保留当前搜索和分类；文件夹树上的全仓库入口和命令面板的完整媒体库命令则恢复全部范围。

启动时默认恢复上次使用的导航模式。可在映阅设置的「启动时的左侧导航」选择始终打开文件夹树或附件侧栏。图片、音视频、PDF 的自动切换可单独关闭；其他插件已占用的非原生查看器不会被强制替换。

「整个仓库」指当前打开的 Obsidian 仓库，包含任意层级的附件以及映阅生成的截图，不需要移动原文件。Markdown、Canvas 和 Base 文件继续使用 Obsidian 原生入口，不列入附件目录；隐藏配置目录和仓库外的文件也不属于附件范围。新增、修改、重命名和删除附件会自动刷新列表。

已有能力

• 原生文件夹：保留目录树与排序，支持常见附件直接打开；树上方全仓库入口、文件夹右键浏览、与附件侧栏双向切换，启动恢复上次模式。
• 全仓库侧栏：固定左侧入口、类型与数量、搜索、最近打开、收藏、四种排序、图片缩略图、所在路径、文件大小、实时刷新、分批显示，适配 Obsidian 明暗主题。
• 完整媒体库：默认整个仓库，可选文件夹；分类、最近打开、收藏、标签搜索、排序、网格/列表、拖放或选择文件导入。
• 视频与音频：原生流式播放、同目录队列、前后切换、可选连续播放、断点续播、倍速、音量、循环、A–B 循环、书签、快捷键。视频支持画中画与全屏。
• 字幕与笔记：同名 SRT/VTT 自动加载、手动选择、字幕搜索和点击定位、时间戳链接、截图到笔记。默认不自动播放声音。
• 图片：缩放、拖动、适应窗口、原尺寸、旋转、翻转、全屏、EXIF、缩略图、幻灯片、亮度和对比度、裁剪并导出副本、复制图片、固定到分栏。
• 文档：保留上游 DOC/DOCX、PPT/PPTX、XLS/XLSX、PDF 等查看器；新增 ODT/ODP 内容预览与 ODS 入口。Office 常见内容本地解析。
• PDF：缩放、翻页、页码链接、文本选择、高亮/下划线/删除线、文本批注、签名、页序、合并、保存/另存。未保存批注以插件草稿方式恢复。
• EPUB：章节导航、字号、纸张/明亮/夜读主题、当前章节查找、摘录及阅读位置恢复。
• 数据：CSV、JSON、YAML、TOML 等上游查看和编辑工具；压缩包目录与条目预览；多种专业格式的上游模块仍保留。
• 附件管理：附件笔记、重命名、移动、移到回收站、自定义文本扩展名、系统应用打开。
• 在线内容：公开的直接音视频地址及 YouTube、Vimeo、哔哩哔哩嵌入入口。云端分享是可选项，默认关闭，每次上传前单独确认。

在笔记里插入画廊

用 lumen 代码块，逐行写附件链接：

[[映阅体验/01 图片/山野来信.png]]
[[映阅体验/02 影音/花开的片刻.mp4]]

轮播可以使用 media-slider 代码块，也可以在 lumen 中加入 mode: slides：

[[映阅体验/01 图片/山野来信.png]]
[[映阅体验/01 图片/矢量图形.svg]]
[[映阅体验/02 影音/花开的片刻.mp4]]

也支持 folder: 映阅体验/01 图片。这是本分支支持的语法，不承诺原插件所有历史语法完全兼容。

文件和状态在哪里

• 插件文件：仓库下 .obsidian/plugins/lumen-viewer/。
• 收藏、标签、进度和批注草稿：插件目录的 data.json。
• 附件笔记：默认在 映阅笔记/；设置中可修改。
• 截图和裁剪副本：映阅笔记/截图/。原图保持原样。
• 导入的文件：映阅导入/；重名自动生成新名称。
• 时间戳和页码使用 obsidian://lumen-open 链接；需要目标仓库已安装本插件。

范围与兼容性

这版的实际功能对照见 FEATURES.md。它没有把调查中的 16 个插件所有高级功能都等量复刻。尚未包含 yt-dlp 下载器、PDF++ 的完整反向链接覆盖层、移动端后台播放、任意外部程序映射和专有站点登录工作流。

格式扩展名不等于解码保证。音视频取决于 Chromium 和系统编解码器；HEIC 与相机 RAW 没有新增解码器；ODT/ODP 为内容预览，复杂排版建议使用系统应用。上游部分旧 Office、压缩包和音频转换能力需要本机转换程序。

最低 Obsidian 版本为 1.7.2。验收环境为 Windows 上的 Obsidian 1.13.7。移动端、在线站点、云端分享和所有专业格式没有逐项实测。查看 TESTING.md、qa/obsidian-results.json 和 qa/sidebar-results.json 获取实际结果，不能用样例通过推断所有真实文件都兼容。

手动安装

1. 打开 Releases，下载 lumen-viewer-0.3.0.zip，而不是 GitHub 自动生成的 Source code 压缩包。
2. 解压后，将其中的 lumen-viewer 文件夹放到目标仓库的 .obsidian/plugins/ 下。最终应能看到 .obsidian/plugins/lumen-viewer/manifest.json、main.js 和 styles.css。
3. 重新打开 Obsidian，进入「设置 → 第三方插件 / 社区插件」，按 Obsidian 的提示允许第三方插件，启用「映阅 Lumen」。
4. 从原生文件夹树上方的「映阅全仓库面板」、最左侧「映阅」图标，或命令面板中搜索「映阅」开始使用。

升级前备份 data.json；更新代码时保留它。禁用插件即可恢复使用其他查看器，生成的 Markdown 笔记仍可正常阅读。发行页同时提供独立运行文件、许可文件及 SHA256SUMS.txt。

本地构建

需要 Node.js 22 与 npm。所有依赖版本由 package-lock.json 固定；常规构建使用已纳入仓库的 WASM 资源，不需要额外安装编译器。

npm ci
npm run build
npm test
node scripts/package-lumen.mjs

默认构建不包含开发测试协议。开发构建设置环境变量 LUMEN_QA=1 后，可在本地 Obsidian 运行「检查体验文件（开发版）」，只检查 映阅体验/ 下的样例并在插件目录写验收记录。不要用测试动作处理重要文件。

开发版侧栏检查通过 obsidian://lumen-qa-sidebar?vault=<已编码仓库名> 运行，核对全仓库附件清单和侧栏交互，并仅在体验目录创建、修改、重命名及删除自己的临时样例。结果写入插件目录 sidebar-results.json。

开发版原生文件夹检查通过 obsidian://lumen-qa-explorer?vault=<已编码仓库名> 运行，验证文件夹入口、面板切换、原生文件打开流程及 Markdown 编辑器保留，结果写入插件目录 explorer-results.json。它使用自己的临时标签页读取体验文件，不改写样例内容。

许可证与来源

本分支为 MIT。上游版权保留在 LICENSE；运行时依赖的具体许可在 LICENSES.txt 和 THIRD_PARTY_NOTICES.md。没有使用 Media Extended v4 的闭源实现，也没有使用其他产品的图标、品牌或截图作为界面资产。

测试视频来自 MDN 的 CC0 flower.mp4，其他体验文件为本次生成的合成样例。上游原始说明保存在 UPSTREAM_README.md。