Files
Marcos Paulo b32650767c
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs and briefs for smart folders, version diff, media timestamps, clean paste, link cards, spaced repetition
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 12:18:00 -03:00

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)

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

  1. [[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.
  2. An embed with #t= starts at that offset when played.
  3. 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).
  4. Link display shows a clock icon and rec.mp3 @ 04:12 when 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 send AudioCommand::Play { path, from } (audio) or the video equivalent. Open the exact function with git grep -n "link clicked\|LinkClicked\|open_file" crates/ui-egui/src/shell/app.
  • Embed: views/media_view/audio/embed.rs and 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 in shell/hotkeys/commands.rs; strings in [ui.media] (find with git 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

  1. parse_time_fragment("t=04:12") = 252 000 ms; t=252, t=1:02:03, t=npt:10.5, t=10,20 ok; t=99:99, t=, t=-1, t=1e3, 65-byte subpath, t=360001 (over 100 h) are None.
  2. Clicking [[rec.mp3#t=04:12]] starts playback at 252 s (unit test on the pure "link to command" function; kittest sees AudioCommand::Play{from:252.0} in the bus).
  3. [[rec.mp3#t=xx]] opens the file without seek and without error.
  4. Lint reports no broken-anchor warning for a valid t=; still reports a real missing heading.
  5. Copy timestamp link at position 125.4 s yields [[rec.mp3#t=2:05]].
  6. Rename of rec.mp3 rewrites links and keeps the #t= suffix (existing rename code; add a test).

Open questions

  • Q1: canonical written form #t=4:12 vs #t=00:04:12; proposal: write M: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 -ss argument there.

Feature ideas (researched, ranked)

  1. Ranges t=10,20 loop or stop at end (Media Fragments t=start,end); chapters list from a note's timestamp links shown under the player.
  2. 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.
  3. Transcript sidecar rec.mp3.vtt/.srt shown under the waveform, click a cue to seek; cue text searchable (pairs with agy gap 4, Whisper, not specified here).
  4. Backlinks panel shows the timestamp next to each reference; 5. PDF page links share the same click router (#page=).