中文文档

Changelog

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

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!

ℹ 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-hydra/body))  ;; 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-hydra/body))  ;; 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-hydra/body))  ;; 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-hydra/body

ℹ 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 ;)

All functions can be reached from org-media-note-hydra/body :

• 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
  • <right> Backward 5s
  • 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.
  • t c When on，insert videocite or audiocite link instead of video or audio link if possible.
  • t p When on，auto pause media after inserting media link.
  • t s When on， <M-return> will auto insert both media link and current screenshot.
  • t l Set the method for capturing ab-loop clips
  • t S When on，save screenshot with subtitles
  • t t Toggle timestamp format between hh:mm:ss and hh:mm:ss.fff
  • t M Set the separator to be used when merging the selected items.

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

• mpv.el control media inside emacs
• pretty-hydra create an amiable hydra

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

Using org-media-note for online video notes relies on mpv’s streaming feature and requires additional external dependencies:

• yt-dlp/yt-dlp: A youtube-dl fork with additional features and fixes: Used for downloading website videos. List of supported websites. It 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.
• UlyssesZh/yt-dlp-danmaku: yt-dlp plugin for converting Bilibili danmaku into ASS format: If you need to load Bilibili danmaku.

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:

   --script-opts=ytdl_hook-ytdl_path=yt-dlp
       

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.
   • The default configuration will download Chinese and English subtitles for YouTube and load all subtitles together with danmaku for Bilibili. The subtitle feature for Bilibili requires loading cookies to obtain login information, please modify according to actual conditions, see 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.

Configure general streaming settings. For example, specify using yt-dlp to download:

script-opts=ytdl_hook-ytdl_path=yt-dlp

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: