中文文档

Changelog

🌟 About

Take notes for video and audio files in org-mode! Now supported:

• 🎥 both local and online medias are supported (requires installing yt-dlp, see Online Video).
• ⏯️ media control: seek backward/forward, control volume and playback speed …
• 🔗 new link types video, audio
  • Timestamp Link e.g. [[video:course.mp4#0:01:56][0:01:56]]
    • M-RET will auto insert current timestamp during playing media, if point at a list starting with an org-media-note link (e.g., - [[video:test.mp4#0:02:33][0:02:33]] note).
    • click link to jump to corresponding position
  • AB-Loop Link e.g. [[video:course.mp4#0:01:56-0:01:58][0:01:56-0:01:58]]
    • insert this kind of link when playing in a A-B loop
    • click link to jump to point A, and auto loop between A and B
• 📝 When taking notes, you can quickly:
  • insert timestamps or ab-loop links for intervals
  • insert current screenshots or GIFs
  • insert current subtitles
  • merge multiple notes, which is suitable for organizing after importing subtitles.
  • when inserting timestamps, you can customize:
    • Whether to automatically insert a screenshot of the current video.
    • Whether to automatically pause after inserting the timestamp.
• 🔄 import from:
  • Subtitle files: SRT, VTT, ASS.
  • Chapter list of current playing file.
  • PBF: generated by PotPlayer
  • TXT: exported by Noted
  • Timers

📚 Working with org-ref to get a better experience:

• 🤝 quick open related media file in org-ref note (file path is got from bib file)
• 🔗 new link types videocite, audiocite
  • e.g. [[videocite:key#0:01:56][0:01:56]] or [[videocite:key#0:01:56-0:01:58][0:01:56-0:01:58]]
  • you can chose to insert video or videocite link
  • click link to jump to corresponding position, or start A-B loop
  • show bib info when pointing at link
  • open org-ref action list

🎥 Demo

Open related media file in org-ref note，play on top，insert current timestamp and subtitle

Insert current screenshot. Also, you can customize to auto insert screenshot when create a new note item

Jump to the right position by clicking link

Open online video, then operate the same as local files!

🚀 QuickStart

ℹ️ Currently, you have to install this package from github.

• for doom users：
  1. Install

     (package! org-media-note :recipe (:host github :repo "yuchen-lea/org-media-note"))
             

  2. Config
     • don’t use org-ref

       (use-package! org-media-note
         :hook (org-mode .  org-media-note-mode)
         :bind (
                ("H-v" . org-media-note-show-interface))  ;; Main entrance
         :config
         (setq org-media-note-screenshot-image-dir "~/Notes/imgs/")  ;; Folder to save screenshot
         )
                   

     • use org-ref

       (use-package! org-media-note
         :init (setq org-media-note-use-org-ref t)
         :hook (org-mode .  org-media-note-mode)
         :bind (
                ("H-v" . org-media-note-show-interface))  ;; Main entrance
         :config
         (setq org-media-note-screenshot-image-dir "~/Notes/imgs/")  ;; Folder to save screenshot
         (setq org-media-note-use-refcite-first t)  ;; use videocite link instead of video link if possible
         )
                   

• for non-doom users: You can
  1. Manually download org-media-note, include it in your load-path, then refers to the above config
  2. Or use quelpa-use-package (thanks japhir for kindly providing this snippet)

     (use-package quelpa-use-package)  ;; to allow installation of github packages
     (use-package org-media-note
       :quelpa (org-media-note :fetcher github :repo "yuchen-lea/org-media-note")
       :hook (org-mode .  org-media-note-mode)
       :bind (("H-v" . org-media-note-show-interface))  ;; Main entrance
       :config
       (setq org-media-note-screenshot-image-dir "~/notes/imgs/"))
             

  3. If manually loading org-media-note without a package manager like package.el or straight, you need to (require 'org-media-note-org-ref).

Now, you can access all functions in org-media-note-show-interface.

ℹ️ Here, I use Hyper key H for keybinding. In this way, I can quickly access personal functions, and no major or minor modes will stamp on my keys. Look into this for more information: Emacs: How to Bind Super Hyper Keys. Or you can bind it to any other key you like. After all, it’s Emacs ;)

📖 Functions

All functions are accessible via org-media-note-show-interface. Depending on the value of the org-media-note-interface, org-media-note-pretty-hydra/body or org-media-note-transient will be called:

pretty-hydra ui

• Header：Display basic info, file path, volume, duration and so on
• File：Functions about media file
  • o Conditionally open media file in mpv. (org-media-note-play-smart) Priorities are as follows:
    1. When point at a file link, play it in mpv.
    2. When integrated with org-ref, calling this function in an org-ref note will open the media file described in bib entry.
       • Your media file will be auto opened if all of the following are true:
         • You’re under an org-ref note, which means the Custom_ID stores the entry key.
         • Files can be found by bibtex-completion-find-pdf. You should keep the value of bibtex-completion-pdf-field and the field which store files consistent.
         • Your media file extension is included in org-media-note--video-types or org-media-note--audio-types
    3. When media files found in org-attach-dir, open this file if there’s only one file, else, let user chose file from attach directory.
    4. Else, find the file by yourself.
  • j Cycle through subtitles
  • T Toggle video window on top of other windows
  • c Increase speed by 0.1
  • x Decrease speed by 0.1
  • z Toggle speed between 1.0 and last customized speed (org-media-note-mpv-toggle-speed)
• Playback：Functions about playing media file
  • <SPC> pause/unpause
  • l Set/clear A-B loop points, show points info if possible
  • g jump to the position found in current line, useful when you’re browsing related subtitles. If no timestamp found, manually input the timestamp.
  • <left> Forward 5s (default). Step can be customized by t <right>.
  • <right> Backward 5s (default). Step can be customized by t <right>.
  • C-<left> Skip to previous subtitle
  • C-<right> Skip to next subtitle
  • <prior> (<PgUp>) Previous chapter
  • <next> (<PgDown>) Next chapter
• Volume：Functions about volume
  • + add volume 5
  • - add volume -5
  • 0 Toggle volume between 100 and last customized volume (org-media-note-mpv-toggle-volume)
  • m mute/unmute
• Note：Functions about insert notes
  • i Insert current link, there’re several links according to customization and playing state: (org-media-note-insert-link)
    • A-B Loop?
      • If in an A-B Loop, which means Playback displays “Clear A-B loop (xxx - xxx)”, A-B Loop Link is inserted. The default link description is timestamp of A-timestamp of B, you can set this by org-media-note-ab-loop-link-format.
      • If not in an A-B Loop, Timestamp Link is inserted. The default link description is timestamp, you can set this by org-media-note-timestamp-link-format.
    • prefer ref key?
      • When prefers ref key, which means Toggle displays Use ref key instead of absolute path (*), videocite or audiocite link is inserted
      • else, video or audio link is inserted
    • 💡 When in a list like - [[video:video.mp4#00:03:24][00:03:24]] description, <M-return> will auto insert media link.
    • 💡 Video path format is consistent with org-link-file-path-type
    • 💡 When set org-media-note-cursor-start-position to before , move cursor to the start of link after insertion. This works for manual insertion only. Cursor is always at the end of link for those auto inserted by <M-return>.
  • a Adjust current link position to current playing position. Then, apply this offset to all links under current heading.
  • S If there is no ab-loop currently, insert the current video screenshot (org-media-note-insert-screenshot), otherwise insert the current ab-loop’s video clip or GIF (org-media-note-capture-ab-loop-and-insert).
    • ℹ️ variables related:
      • org-media-note-screenshot-save-method : customize the place to save screenshot
        • directory: save to org-media-note-screenshot-image-dir
        • attach: save to corresponding org-attach-dir.
      • org-media-note-screenshot-link-type-when-save-in-attach-dir when save screenshots to attach dir, use file link or attachment link
      • Screenshot path format is consistent with org-link-file-path-type in file: link
      • org-media-note-capture-ab-loop-functions-alist defines the list of functions for capturing ab-loop clips, with the default being capturing the original clip and converting it to GIF.
  • s Insert current subtitle text (org-media-note-insert-sub-text)
  • H-m Merge the selected items into one, keeping only the timestamp of the first item. Suitable for processing after importing subtitles. (org-media-note-merge-item)
• Import: Import notes from other format
  • I p Import from PotPlayer PBF file (org-media-note-insert-note-from-pbf)
  • I n Import from Noted TXT file (org-media-note-insert-note-from-noted)
  • I t Import from org-timer (org-media-note-convert-from-org-timer)
  • I s Import from srt (org-media-note-insert-note-from-srt)
  • I c Import from the chapter list (org-media-note-insert-note-from-chapter-list)
• Config：Customization
  • t m When in a list like - [[video:video.mp4#00:03:24][00:03:24]] description, <M-return> will auto insert media link if this toggles on. (org-media-note-toggle-auto-insert-item)
  • t s When on， <M-return> will auto insert both media link and current screenshot. (org-media-note-toggle-save-screenshot)
  • t S When on，save screenshot with subtitles (org-media-note-toggle-screenshot-with-sub)
  • t l Set the method for capturing ab-loop clips (org-media-note-set-ab-loop-capture-method)
  • t c When on，insert videocite or audiocite link instead of video or audio link if possible. (org-media-note-toggle-refcite)
  • t p When on，auto pause media after inserting media link. (org-media-note-toggle-pause-after-insertion)
  • t t Toggle timestamp format between hh:mm:ss and hh:mm:ss.fff (org-media-note-toggle-timestamp-pattern)
  • t M Set the separator to be used when merging the selected items. (org-media-note-set-separator)
  • t <right>: Set the step for controlling playback progress. Supports: seconds, percentage, or frames. (org-media-note-set-seek-method)

ℹ️ Corresponding function is in the brackets. Those without brackets usually call mpv commands directly. More info refers org-media-note-pretty-hydra.

transient ui

The transient interface has the same functions and key bindings as the pretty-hydra interface.

To accommodate a more compact layout, config commands are semantically grouped:

transient vs pretty-hydra

The interactive logic is consistent. If a shortcut key that is not within the interface is typed, the interface will exit and the corresponding command will be executed.

	transient	pretty-hydra
Dependency	Built-in since Emacs 28	pretty-hydra
Appearance Position	Depends on transient-display-buffer-action	Bottom of the current frame
ui

🛠️ Dependencies

• mpv.el control media inside emacs
• Currently provides two frontends, customizable via org-media-note-interface:
  • transient (default): Built into Emacs since version 28, displayed at the bottom of the current window.
  • pretty-hydra: create an amiable hydra, displayed at the bottom of the current frame.

  org-ref is not required, but it’s worth to have a try if you use bib to manage your media file!

🌐 Online Video

Using org-media-note for online video notes relies on mpv’s streaming feature and requires additional external dependencies. It requires the installation of yt-dlp to download videos from websites. You can find the list of supported websites here. yt-dlp is smoother and more powerful than youtube-dl, which is the default used by mpv. If you want to play online videos but haven’t installed yt-dlp, org-media-note will raise an error.

Settings can be applied in several places, with priority from low to high:

1. mpv.conf file: General settings for mpv.
2. org-media-note-mpv-general-options variable: General settings in org-media-note. The default value specifies using yt-dlp for downloads.
3. org-media-note-mpv-online-website-options-alist variable: Individual settings for websites, for example, Bilibili needs to download all subtitles and danmaku, while YouTube’s auto-generated subtitles only need to download specific languages. Please modify according to actual conditions, see org-media-note-mpv-online-website-options-alist demo and  FAQ · yt-dlp/yt-dlp Wiki.
4. org-media-note-mpv-webstream-download-path variable: Download directory for online video subtitles and other files. Default is temporary folder. If set to nil, it will download to the current directory.

As long as you can normally load subtitles in mpv, org-media-note can control playback, insert timestamps and screenshots, and even import subtitles just like with local media!

The following image demonstrates playing a Bilibili video, danmaku navigation, switching subtitles, importing subtitles, and other functions:

⚙️ Debug

The extension is essentially a wrapper around the functionality of mpv. If mpv cannot play properly, you can call org-media-note-copy-mpv-command to copy the mpv command, then paste it into the terminal and check if it works.

• If it cannot play correctly in the terminal, please try adjusting the mpv configuration.
• If it plays fine in the terminal but not in Emacs, please report the issue.