5.7 KiB
Media timestamp links [[rec.mp3#t=04:12]] (agy gap 23, roadmap 28)
Part of specs/plugins-parity/. No new crate: a pure parser in notescraft-markdown (L0), engine resolution, and UI seek through the existing AudioCommand::Play { path, from } (views/media_view/audio/bus.rs) and the video player (shell/app/video.rs).
Research (2026-10-21; agy claims checked)
- Obsidian core does not support time fragments on internal links (forum: https://forum.obsidian.md/t/link-to-timestamp-of-embedded-audio/7122 , notes the Media Fragments URI standard
#t=is what Chromium implements). Plugin: Media Extended adds timestamp links and media fragments (#t=); WARNING, the community listing says v4 will be closed source, v3 stays MIT: https://community.obsidian.md/plugins/media-extended , source https://github.com/kingfo/media-extended . Local-file users report the timestamp being ignored or needing a linked pane: the spec avoids that by seeking directly. - agy listed Logseq and RemNote: NOT verified here; dropped from this spec. Reference standard: W3C Media Fragments URI 1.0
t=npt:https://www.w3.org/TR/media-frags/ (agy claim "#t=MM:SS" is a Media Extended/NPT-like spelling;t=252,t=4:12,t=0:04:12.5are all accepted here). - Demand: forum threads above and https://forum.obsidian.md/t/timestamp-note-from-locally-within-the-vault-stored-video/42172 (timestamp notes from local video).
Problem
Meeting recordings and lecture videos are attached to notes, but a note cannot point at a moment. Users type "at 12:40 she says..." and hunt for it.
Goal
[[rec.mp3#t=04:12]],![[lecture.mp4#t=1:02:03]],[text](rec.mp3#t=252)are time links. Clicking opens the audio/video tab (or the embed player) and starts playing at that time.- An embed with
#t=starts at that offset when played. - In the audio/video tab bar a button "Copy timestamp link" puts
[[rec.mp3#t=MM:SS]]for the current position on the clipboard; palette command "Insert timestamp link" inserts it into the active note (when the player has a position). - Link display shows a clock icon and
rec.mp3 @ 04:12when no alias.
Non-goals (v1)
Ranges t=10,20 (parsed and kept, played from start only: Feature ideas 1); subtitles/transcripts; seek in PDFs (#page= exists separately); fetching remote media.
Design decisions
D1 Grammar (crates/markdown/src/timefrag.rs)
t= followed by [HH:]MM:SS[.fff] or plain seconds S[.fff], optional npt: prefix; optional ,end same grammar. Result TimeFragment { start_ms: u64, end_ms: Option<u64> }. Limits: 100 h, fraction up to 3 digits, whole subpath <= 64 bytes. Fields in range (MM and SS < 60 when a colon form is used). Invalid -> None (link still opens the file, no seek). pub fn parse_time_fragment(subpath: &str) -> Option<TimeFragment> and pub fn format_time(ms: u64) -> String (M:SS, or H:MM:SS from 1 h). Subpath comes from the existing LinkTarget.subpath (crates/markdown/src/links.rs).
D2 Index and lint
Index keeps the link as is. crates/index/src/lookup/resolve.rs and crates/lint must NOT report t=... as a missing heading/block: grep anchors_match / the broken-anchor rule and skip subpaths that parse_time_fragment accepts when the target is a media file (by extension list shared with widgets/tabs/kind.rs, AUDIO_EXTS, video list).
D3 UI
- Click path: the note view reports a clicked link target string (
views/note_view.rs:155); the shell resolves and opens it. Add: if the target path has a media extension and a valid fragment, open the tab and sendAudioCommand::Play { path, from }(audio) or the video equivalent. Open the exact function withgit grep -n "link clicked\|LinkClicked\|open_file" crates/ui-egui/src/shell/app. - Embed:
views/media_view/audio/embed.rsand the video embed take an optional start offset; a play press starts there. - Copy/insert button:
views/media_view/bar.rs(shared bar) + palette command inshell/hotkeys/commands.rs; strings in[ui.media](find withgit grep -n "ui.media" crates/i18n/locales/en.toml; append new keys at the END of that table).
D4 Engine
No command needed for v1. file.info (viewers) is unchanged. MCP exposure: none.
Acceptance criteria
parse_time_fragment("t=04:12")= 252 000 ms;t=252,t=1:02:03,t=npt:10.5,t=10,20ok;t=99:99,t=,t=-1,t=1e3, 65-byte subpath,t=360001(over 100 h) areNone.- Clicking
[[rec.mp3#t=04:12]]starts playback at 252 s (unit test on the pure "link to command" function; kittest seesAudioCommand::Play{from:252.0}in the bus). [[rec.mp3#t=xx]]opens the file without seek and without error.- Lint reports no broken-anchor warning for a valid
t=; still reports a real missing heading. - Copy timestamp link at position 125.4 s yields
[[rec.mp3#t=2:05]]. - Rename of
rec.mp3rewrites links and keeps the#t=suffix (existing rename code; add a test).
Open questions
- Q1: canonical written form
#t=4:12vs#t=00:04:12; proposal: writeM:SS/H:MM:SS, read all. - Q2: does the video player (
shell/app/video.rs, ffmpeg) support a start offset? If not, task 4 adds a-ssargument there.
Feature ideas (researched, ranked)
- Ranges
t=10,20loop or stop at end (Media Fragmentst=start,end); chapters list from a note's timestamp links shown under the player. - Timestamp note-taking mode (Media Extended): a hotkey inserts
- [[rec.mp3#t=..]]as a new list item while the audio plays; the highest-value follow-up for meetings. - Transcript sidecar
rec.mp3.vtt/.srtshown under the waveform, click a cue to seek; cue text searchable (pairs with agy gap 4, Whisper, not specified here). - Backlinks panel shows the timestamp next to each reference; 5. PDF page links share the same click router (
#page=).