README file from
GithubHymns(诗歌)Obsidian 插件
诗歌浏览、搜索、播放与收藏插件:按编号(如 D116)或关键词(空格分隔,如 恩典 耶稣)实时搜索,预览 PDF,播放 MP3,收藏与播放列表。桌面端与移动端通用。仅支持大本诗歌 / 补充诗歌 / 唱诗人 / 新歌颂咏 / 儿童诗歌 / 青年诗歌 / 特会诗歌
注意:插件本体约 1.5 MB,由于诗歌PDF(约 535 MB)与 MP3(约 3.79 GB)体积较大,请到 QQ 群 1128049033 另行下载,解压到你 Obsidian 仓库的任意位置。obsidian启动时,插件会自动扫描仓库中的诗歌PDF与MP3,并自动创建诗歌索引和歌词索引。
功能
- 启用即在侧边栏:插件一开启就自动生成诗歌面板,不用再点功能区图标;设置里可以关掉,也不会顶掉 Bible 的面板。
- 实时搜索:按编号或关键词即时过滤,分组展示(大本诗歌 / 补充诗歌 / 唱诗人 / 新歌颂咏 / 儿童诗歌 / 青年诗歌 / 特会诗歌 / 其他)。
- PDF 预览:单击诗歌在侧边栏查看;双击诗歌、预览时按
],或点预览工具栏的「在新标签打开 PDF」,都会用系统自带的 PDF 阅读器在新标签页打开。 - 右上角按钮,三种打开方式:点一下会列出「窗口投影 / 全屏投影 / 标签页面板」。按
[是诗歌标签页的开关:按一下切过去、再按一下关掉;切回来时正在看的诗歌和搜索内容都保留(最多只开一个,不用先打开侧边栏)。- 窗口够宽时自动变双列:左列放诗歌列表 / 搜索结果 / PDF 预览;右列自上而下是「最近打开 / 播放列表」→ 搜索栏或预览按钮(看当前是浏览还是预览)→ MP3 播放。
- 窗口变窄自动回到单列,与侧边栏的界面完全一致。拖动窗口大小、手机横竖屏切换都会实时变化(手机横屏一般就是双列,竖屏是单列)。
- MP3 播放:一键播放诗歌音频,支持顺序 / 单曲循环 / 列表循环;可切换音频来源。
- 收藏与播放列表:收藏诗歌;内置 7 个主题歌单(倪柝声 / 李常受 / 余洁麟 / 和受恩 / 霍华德 / 以撒·华滋 / 约翰·牛顿),也可自建歌单。
- 联动:可在底部播放栏「联动」里勾选 MP3 随 PDF 切换以及 PDF 随 MP3 切换。
- 复制链接或嵌入笔记:可将诗歌 PDF 或 MP3 嵌入笔记,或者复制链接到笔记。
- 分享 / 复制文件:在诗歌右边的「⋯」菜单里点「分享 PDF」或「分享 MP3」,就能把文件交给其它软件。
- 手机(安卓 / iOS):弹出系统分享面板,直接选微信、QQ 等发出去。
- 电脑:因为电脑没有系统分享面板,所以改成复制文件本身——点一下,文件就进了剪贴板(等同于在文件夹里选中它按
Ctrl+C),再到微信 / QQ 窗口按Ctrl+V(⌘V)粘贴即可。 - 万一某台电脑复制不了,会自动打开这个文件所在的文件夹并选中它,按
Ctrl+C就能复制;同时也会把文件的完整路径复制好。
- 长按定位:搜索结果里长按一首诗歌,跳到它在分类中的位置;搜索框右侧出现返回按钮,点击回到原搜索界面(位置保留),重新输入检索则自动消失。
- PDF 滑动切歌:侧边栏预览 PDF 时左右滑动(或鼠标拖拽)即可切到上一首 / 下一首。
- 投影:Obsidian 一启动就能按
P开诗歌窗口投影、按O开诗歌全屏投影,不用先打开诗歌面板;也可以点右上角按钮选。没在预览诗歌时照样能打开,画面会提示怎么选一首。打开后再按同一个键就关闭,按另一个键则在两种投影间切换;无论当前是什么状态,P恒窗口、O恒全屏。- 切模式:点左上角模式按钮,可选「诗歌全屏 / 诗歌窗口」,或切到经文的逐节 / 并列 / 混合投影;没装 Bible Search and Reader 时经文项会置灰说明。点当前模式只收起菜单,不会关掉投影。
- 翻页 / 换诗歌:
↑↓翻节(PageUp / PageDown、鼠标滚轮同样),Home/End跳首末页;←→(及左右滑动)在你点进来的那份列表里换上一首 / 下一首——从搜索结果点进的就在这批结果里翻,从播放列表 / 诗歌选择面板点进的就在该列表里翻,没设来源时按「最近打开」走。滑动方向:从右往左=下一首,从左往右=上一首(鼠标横拖同效)。方向:历史记录从上往下是上一首,搜索结果 / 播放列表 / 诗歌列表从上往下是下一首。 - 最近打开=投影历史:投影里打开过的诗歌与侧边栏的「最近打开」是同一份记录,会写进插件数据、重启 Obsidian 后仍在;默认保留 50 首,可在「设置 → Hymns → 最近打开记录数」改成 1–200(调小会立即裁剪旧记录)。在侧边栏预览或播放过的诗歌,投影里按
←→也能翻到。在「最近打开 / 历史」里点一首只是回看,不会把它顶到最上、也不刷新面板位置;只有从搜索、列表或别处播放它时,顺序与位置才会更新。 - 找诗歌:顶部搜索框输入编号 / 歌名 / 歌词,点候选直接切;焦点不在搜索框时按
Enter就把焦点交给它。长按搜索框(或长按Enter确定键)打开「诗歌选择」面板——左边选诗歌分类,右边按首数分组(0=1–99、1=100–199 …… S=附录),再点分组看该组诗歌;↑ ↓ 选择、→确认并投出、←逐级返回,关掉再开仍停在原处,重启 Obsidian 才回默认。 - 历史记录 / 播放列表按钮:播放 ▶ 与 ⛶ 之间多了两个按钮。点「🕘 最近打开」看完整记录(正在投影的那首会高亮),点任意一条立即投影;点「🎵 播放列表」先选一张列表(含「当前播放列表(实时)」),再点列表里的诗歌投影,不会改动当前播放列表。两个面板都在投影层内,整屏时也看得见;列表可用鼠标滚轮滚动,也能用
↑↓/PageUpPageDown移动高亮、Home/End跳首尾、Enter(确定键)直接选中当前诗歌。点过的那首再回来看会被标出来,方便接着看下一首。面板打开期间其它投影快捷键一律让行;Esc先收面板,再按一次才关投影。 - 诗歌选择面板:上面那两个按钮之外的第三个入口——**长按搜索框(或长按
Enter)**打开。左边选诗歌分类,右边按首数分组(0=1–99、1=100–199 …… S=附录),点分组看该组诗歌,←逐级返回。这个面板里↑↓选择、→确认并投出、←返回,按确定键不会确认(避免误投);焦点点回搜索框时面板自动收起。左栏对齐搜索框左侧,重开停在原处,重启 Obsidian 才回默认。 - 与经文投影互切:搭配「Bible Search and Reader」5.2.0 或更新版时,按
Q/W/E切到经文投影,再按O/P回来,原来那首诗歌连第几节都还在;从诗歌全屏切过去仍是经文全屏,从诗歌窗口切过去仍是经文窗口,连续来回切换也不会串状态。 - 播放:右上角 ▶ 或空格键打开底部播放条并播放这首诗歌的 MP3,可暂停 / 拖进度 / 看时间;播放条会让出下方空间并让页面重新排版,绝不挡住 PDF 的字。
- 窗口模式(默认):只占满 Obsidian 窗口;左上角模式按钮、搜索框和七个操作按钮都在顶部同一行,窄屏自动排成两行。桌面端按住顶部空白处拖动的是整个 Obsidian 窗口,移动端不会拖动投影图层;
Esc或点右上角 ✕ 都能退出。 - 整屏投影(桌面端):
O一步进整屏,整屏里再按O关闭、按P切回窗口;Esc随时退出整个投影。右上角 ⛶ 按钮同效,移动端不支持整屏。 - 页面自动等比适配:区域偏宽时适应高度(左右留黑边),区域偏高时适应宽度(上下留黑边),任何比例下都不会超出界面或被裁切。
- 文件名不带歌名也能显示歌名:儿童诗歌(
E001)、新歌颂咏(X001)这类只叫编号的 PDF,歌名只印在 PDF 正文里;插件会用歌词索引里从正文抽出的标题自动补齐,列表、搜索、歌词页都会显示真正的歌名。扫描版(无文本层)的 PDF 抽不出标题,仍显示分类名。 - 可自行更换 PDF 和 MP3:如果你有更好的 PDF 或 MP3 资源,可自行替换原始文件,也可新增文件,只要按照命名规律改名字即可。
文件命名与配对规则
插件靠文件名把 PDF 和 MP3 配成一对:
| 对应 MP3 | 说明 | |
|---|---|---|
D001.…pdf |
d001.mp3 |
正歌:字母 + 补零编号 |
Ds1.…pdf / C附2…pdf |
d-1.mp3 / c-2.mp3 |
附录(短歌、补充):MP3 用字母 + 横杠 + 数字 |
D388-1…pdf(第 2 版) |
d388-2.mp3 |
同编号多版本:横杠在数字之后表示第几版 |
附录到底写成 s(如 Ds1)还是「附」(如 Q附1),以你仓库里 PDF 的实际写法为准——MP3 只要写成 d-1 / q-1 就能对上。
- 自动检测更新:启动时比对云端版本,发现新版本弹通知,更新后展示更新说明并可查看历史。
安装
方式一:Obsidian社区安装
1.插件市场搜索、安装、启用Hymns(约 1.5 MB,可能需要科学上网)
2.由于诗歌PDF与 MP3体积较大(约 4 GB),请到 QQ 群 1128049033 另行下载,解压到你 Obsidian 仓库的任意位置。obsidian启动时,插件会自动扫描仓库中的诗歌PDF与MP3,并自动创建诗歌索引和歌词索引。下载好之后,所有的功能均在本地实现。
方式二:手动安装(GitHub)
- 下载本仓库
main.js/styles.css/manifest.json三个文件 - 在 Obsidian 库里新建文件夹
.obsidian/plugins/hymns/,把三个文件放进去。 - 重启 Obsidian,在「设置 → 第三方插件」中启用 Hymns。
- 首次使用在插件设置里指定 PDF 文件夹与 MP3 文件夹(留空 = 扫描整个仓库)。 5.由于诗歌PDF与 MP3体积较大(约 4 GB),请到 QQ 群 1128049033 另行下载,解压到你 Obsidian 仓库的任意位置。obsidian启动时,插件会自动扫描仓库中的诗歌PDF与MP3,并自动创建诗歌索引和歌词索引。下载好之后,所有的功能均在本地实现。
方式三:BRAT
- 在 BRAT 中添加本仓库
ViaCai/Hymns即可。 2.由于诗歌PDF与 MP3体积较大(约 4 GB),请到 QQ 群 1128049033 另行下载,解压到你 Obsidian 仓库的任意位置。obsidian启动时,插件会自动扫描仓库中的诗歌PDF与MP3,并自动创建诗歌索引和歌词索引。下载好之后,所有的功能均在本地实现。
设置
- PDF 文件夹 / MP3 文件夹:留空 = 扫描整个仓库。诗歌靠文件名编号识别(如
D116、E836(补充版))。 - 重建索引 / 歌词索引:改了文件夹或新增诗歌后重建。
- 更新:自动检查更新开关、立即检查更新、查看当前版本说明、查看历史更新。
发布(提交 Obsidian 官方插件市场)
本仓库采用「打 tag 自动出 Release」的流程,无需手动在 GitHub 建 Release。
- 在
CHANGELOG.md顶部写好新版本的更新内容(按## [x.y.z] - 日期格式)。 - 运行一键发版脚本(会自动改
manifest.json/versions.json、提交、打 tag、推送):node scripts/release.mjs 1.0.1首次发布当前 1.0.0 时,直接打 tag 即可:
git tag 1.0.0 && git push origin 1.0.0 - GitHub Actions 会自动创建 Release,并附上
main.js/styles.css/manifest.json。 - 到 obsidianmd/obsidian-releases 提 PR,在
community-plugins.json加入:{ "id": "hymns", "name": "Hymns", "author": "ViaCai", "repo": "ViaCai/Hymns" }
插件自身的自动检测更新读取的是 main 分支的原始文件,与官方市场的 Release 分发互不冲突,二者可同时生效。
目录结构
hymns/
├── main.js # 插件主体
├── styles.css # 样式
├── manifest.json # 插件元信息
├── lib/ # 开发用:PDF.js 源文件(发布版已内联进 main.js,安装时不需要此目录)
├── versions.json # 各版本最低 Obsidian 版本
├── CHANGELOG.md # 更新日志
└── README.md
English
Hymns — an Obsidian hymnal plugin
Browse, search, play and bookmark hymns: instant search by number (e.g. D116) or keywords, PDF preview, MP3 playback, favourites and playlists. Works on desktop and mobile.
Supported hymn series
The plugin recognizes the following hymn series by their file-name prefix and groups them accordingly:
- Great Hymns (大本诗歌,
D) - Supplementary Hymns (补充诗歌,
B) - Hymn Writers (唱诗人,
C) - New Songs of Praise (新歌颂咏,
X) - Children's Hymns (儿童诗歌,
E) - Youth Hymns (青年诗歌,
Q) - Special Meeting Hymns (特会诗歌,
T) - Other Hymns (其他诗歌,
O) — a catch-all group for anything that does not match the series above
Installation
Manual installation:
- Download
main.js,styles.cssandmanifest.jsonfrom the latest release. - Create the folder
<your-vault>/.obsidian/plugins/hymns/. - Put the three files into that folder. These three files are all you need — PDF.js is bundled inside
main.js. - Reload Obsidian, then enable Hymns in Settings → Community plugins.
Via BRAT: add ViaCai/Hymns in the BRAT plugin and let it install the latest release.
Usage
- Put your hymn PDF/MP3 files anywhere inside your vault. The folder names are configurable in the plugin settings — leave them empty to scan the whole vault.
- Hymn numbers are detected from file names, e.g.
D116 <title>.pdforD116-<title>.mp3. - On every startup the plugin scans the vault and builds the hymn index and the lyrics index automatically.
- Open the Hymns view from the ribbon, then search, preview the PDF and play the MP3. In the sidebar, click the icon at the far right of the panel title bar to open a second, full-size Hymns panel in a new tab (the button is not shown inside the tab itself). The tab switches between a two-column layout and the single-column sidebar layout according to the window width (phone landscape is usually two-column, portrait single-column). In two-column mode the left column holds the list / search results / PDF preview; the right column runs top to bottom: "Recently opened" & "Playlists" → the search bar (while browsing) or the preview buttons (while previewing a PDF) → the MP3 player.
- Copy a link or embed to your note — on any hymn, open the "more" (⋯) menu and copy a wiki link or an embed for its PDF or MP3, e.g.
[[D116.pdf]]or![[D116.pdf]](and the same for MP3). Paste them straight into any note. - Long-press to locate — long-press a hymn in the search results to jump to its position in the category list; a back button appears next to the search box to return to the original search view (previous position kept). Typing a new search dismisses the button.
- Swipe in the PDF preview — swipe left/right (or drag with the mouse) in the sidebar PDF preview to go to the previous / next hymn. Vertical scrolling is unaffected.
- Replace or add your own PDF/MP3 — if you have better audio or scanned PDFs, just replace the existing files or drop in new ones following the same naming rule. The plugin re-indexes on the next startup, or you can trigger it with Rebuild index in the settings.
- Share or copy a file — open the "more" (⋯) menu on any hymn and choose Share PDF / Share MP3 (shown as Copy PDF file / Copy MP3 file on desktop).
- On phones (Android / iOS) the system share sheet opens, so you can send the file straight to WeChat, QQ, etc.
- On desktop there is no system share sheet, so the file itself is copied to the clipboard — just press
Ctrl+V(⌘V) in the target app. - If copying is not possible on that machine, the file's folder is opened with the file selected, so you can still press
Ctrl+C; the full file path is copied as well.
Settings
- PDF folder / MP3 folder — leave empty to scan the whole vault.
- Link PDF and MP3 — follow the current hymn in both viewers.
- Rebuild index / Rebuild lyrics index — rebuild after adding or moving files.
- Updates — toggle the automatic update check, check for updates now, view the current changelog and the update history.
Notes on plugin behavior
- Vault enumeration — the plugin lists the files in your vault in order to locate hymn PDF/MP3 files. This is required so that you do not have to configure each file manually.
- Clipboard access — used when you click "Copy lyrics", or when you use "Share / Copy file" for a PDF or MP3.
- External commands (desktop only) — clicking "Copy PDF file" / "Copy MP3 file" runs a built-in OS command to place that one file on the system clipboard:
powershellon Windows,osascripton macOS,xclip(orwl-copy) on Linux. Only the absolute path of the selected hymn's file is passed as an argument; the command runs solely in response to your click, nothing is downloaded, and no other command is ever executed. - Dynamic code execution — the bundled PDF.js library is evaluated with
new Functioninside an isolated sandbox object (evalPdfLibIsolated). This keeps the library out of the global scope and allows PDF rendering to work on mobile without a Web Worker. All code is bundled locally insidemain.js— nothing is downloaded or executed from the network.
License
MIT — see LICENSE.
This plugin bundles PDF.js v3.11.174 (Apache License 2.0); its copyright and license notice are preserved inline in main.js.
许可证
MIT License(见 LICENSE)
本插件内联打包了 PDF.js v3.11.174(Apache License 2.0),其版权与许可声明随源码一并保留在 main.js 中。
☕ 如果觉得这款插件对您有帮助,也可以支持我的项目
加6:10 所以我们有了时机,就当向众人行善,尤其是向信仰之家的人。