[[file:README_CN.org][中文文档]]
[[file:CHANGELOG.org][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:
📚 Working with [[https://github.com/jkitchin/org-ref][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
[[../demo/org-media-note-add.gif?raw=true]]
Insert current screenshot. Also, you can customize to auto insert screenshot when create a new note item
[[../demo/org-media-note-screenshot.gif?raw=true]]
Jump to the right position by clicking link
[[../demo/org-media-note-follow.gif?raw=true]]
Open online video, then operate the same as local files!
[[../demo/org-media-note-online-video-en.gif?raw=true]]
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: [[http://ergoemacs.org/emacs/emacs_hyper_super_keys.html][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 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
[[../demo/org-media-note-hydra.png?raw=true]]
- 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:
- When point at a file link, play it in mpv.
- 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=
- 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.
- 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
- == 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.
- == Forward 5s (default). Step can be customized by =t =.
- == Backward 5s (default). Step can be customized by =t =.
- =C-= Skip to previous subtitle
- =C-= Skip to next subtitle
- == (==) Previous chapter
- == (==) 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=, == 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 ==.
- =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=, == will auto insert media link if this toggles on. (=org-media-note-toggle-auto-insert-item=)
- =t s= When on， == 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 =: 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:
[[../demo/org-media-note-transient.png?raw=true]]
** 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 | [[https://github.com/jerrypnz/major-mode-hydra.el][pretty-hydra]] |
| Appearance Position | Depends on =transient-display-buffer-action= | Bottom of the current frame |
| ui | [[../demo/org-media-note-transient.png?raw=true]] | [[../demo/org-media-note-hydra.png?raw=true]] |
Using org-media-note for online video notes relies on mpv's streaming feature and requires additional external dependencies. It requires the installation of [[https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#installation][yt-dlp]] to download videos from websites. You can find the list of supported websites [[https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md][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:
- =mpv.conf= file: General settings for mpv.
- =org-media-note-mpv-general-options= variable: General settings in org-media-note. The default value specifies using yt-dlp for downloads.
- =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 [[https://github.com/yuchen-lea/org-media-note/wiki/org%E2%80%90media%E2%80%90note%E2%80%90mpv%E2%80%90online%E2%80%90website%E2%80%90options%E2%80%90alist-demo][org-media-note-mpv-online-website-options-alist demo]] and [[https://github.com/yt-dlp/yt-dlp/wiki/FAQ#how-do-i-pass-cookies-to-yt-dlp][FAQ · yt-dlp/yt-dlp Wiki]].
- =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:
[[../demo/org-media-note-online-video-en.gif?raw=true]]
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.