Skip to content

Latest commit

 

History

History
349 lines (286 loc) · 22.3 KB

README.org

File metadata and controls

349 lines (286 loc) · 22.3 KB

👉 Support this work via GitHub Sponsors

Ready Player Mode

An Emacs major mode to open media (audio/video) files like any other file (via find-file, dired, etc).

Previewing videos is also supported.

Optionally, there are additional features like indexing and searching.

Install / Setup

This package is available on MELPA.

If you just want Emacs to recognize and open media files (find-file, dired, etc.), this is all you need:

(use-package ready-player
  :ensure t
  :config
  (ready-player-mode +1))

To customize supported media files, set ready-player-supported-media before toggling ready-player-mode.

Remember my music collection

(setq ready-player-my-media-collection-location "path/to/my/media/collection")

From then onwards, you can directly open your collection via M-x ready-player (unless you were last playing something else). If you want to explicitly open your media collection, invoke M-x ready-player-open-my-media-collection.

Ready player buffer key bindings

TABready-player-next-buttonNavigate to next button.
SPCready-player-toggle-play-stopToggle play/stop of media.
gready-player-reload-bufferReload media from file.
rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
fready-player-seek-forwardSeek forward.
qready-player-quitQuit `ready-player-major-mode’ window and kill buffer.
dready-player-view-dired-playback-bufferView associated `dired’ playback buffer.
sready-player-toggle-shuffleToggle shuffle setting.
bready-player-seek-backwardSeek backward.
aready-player-toggle-autoplayToggle autoplay setting.
o or eready-player-open-externallyOpen visited file in default external program.
nready-player-nextOpen the next media file in the same directory.
cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
iready-player-show-infoShow playback info in the echo area.
pready-player-previousOpen the previous media file in the same directory.
mready-player-mark-dired-fileMark the current file in the appropriate `dired’ buffer(s).
<backtab>ready-player-previous-buttonNavigate to previous button.
uready-player-unmark-dired-fileUnmark the current file in the appropriate `dired’ buffer(s).

Global key bindings

Global bindinds are under the C-c m prefix. If you prefer not to have these bindings disable them with:

(setq ready-player-set-global-bindings nil)
C-c m SPCready-player-toggle-play-stopToggle play/stop of media.
C-c m rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
C-c m mready-player-view-playerToggle switching between player buffer and previous buffer.
C-c m sready-player-toggle-shuffleToggle shuffle setting.
C-c m aready-player-toggle-autoplayToggle autoplay setting.
C-c m nready-player-nextOpen the next media file in the same directory.
C-c m cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
C-c m iready-player-show-infoShow playback info in the echo area.
C-c m pready-player-previousOpen the previous media file in the same directory.
C-c m /ready-player-searchSearch the `dired’ playlist for playback (experimental).

Toggle recognition

You can optionally toggle media recognition on and off interactively via M-x ready-player-mode.

External dependencies

Playback

ready-player-mode relies on command line utilities to play media.

By default, ready-player-mode will try to use either mpv, vlc, ffplay, or mplayer (in that order). Customize ready-player-open-playback-commands to your preference.

Install either of these using your favorite method.

On macOS:

brew install mpv

Metadata

Metadata is extracted using ffprobe, which comes bundled with ffmpeg.

Install using your favorite method.

On macOS:

brew install ffmpeg

Thumbnails

ready-player-mode prefers ffmpegthumbnailer to generate thumbnails, but will fallback to ffmpeg otherwise.

Install using your favorite method.

On macOS:

brew install ffmpegthumbnailer

Customizations

Video vs audio

If you’d like to use different utilities to play video and audio, you can use ready-player-open-playback-commands for this with something like:

(setq ready-player-open-playback-commands
      '((ready-player-is-audio-p "mpg123")
        (ready-player-is-video-p "mpv")))

Play all videos as audio

Ready player avoids auto-advancing video files to prevent awkward switching between video window and Emacs.

If you’d like to play all video files as audio (no video stream playback) and auto-advance via repeat, use the following settings:

;; Recognize video files as audio.
(setq ready-player-supported-audio (append ready-player-supported-audio
                                           ready-player-supported-video))
;; Don't recognize any file as video.
(setq ready-player-supported-video nil)

;; Disable video stream playback (mpv player)
(setq ready-player-open-playback-commands
      '(("mpv" "--audio-display=no" "--video=no" "--input-ipc-server=<<socket>>")))

Buttons (macOS SF Symbols)

If you have SF symbol rendering in Emacs on macOS, you can use enable usage in buttons by invoking (ready-player-macos-use-sf-symbols) prior to (ready-player-mode +1):

(ready-player-macos-use-sf-symbols)
(ready-player-mode +1)

Buttons (Linux)

Default icons are ◁◁ ▶ ■ ▷▷ ➦ ⇆. These can be customized (see all icon variables). I’m happy to take suggestions for improving default icons.

All customizations

Custom variableDescription
ready-player-hide-modelineIf non-nil, hides mode line in buffer.
ready-player-open-playback-commandsCommand line utilities to try for playback.
ready-player-show-thumbnailWhen non-nil, display file’s thumbnail if available.
ready-player-modeNon-nil if Ready-Player mode is enabled.
ready-player-supported-audioSupported audio media.
ready-player-open-externally-iconOpen externally button icon string, for example: “➦”.
ready-player-cache-thumbnailsWhen non-nil, cache thumbnail.
ready-player-open-my-media-collection-iconOpen my collection icon string, for example: “⌂”.
ready-player-autoplay-iconAutoplay icon string, for example: “⏻”.
ready-player-set-global-bindingsWhen non-nil, bind global keys under `ready-player-minor-mode-map-prefix’.
ready-player-cache-metadataWhen non-nil, cache metadata.
ready-player-multi-bufferWhen non-nil, enable opening multiple buffers with parallel playback.
ready-player-thumbnail-max-pixel-heightMaximum thumbnail pixel height.
ready-player-repeatContinue playing if there’s more media in directory or playlist.
ready-player-stop-iconStop icon string, for example: “■”.
ready-player-shuffle-iconShuffle icon string, for example: “⤮”.
ready-player-always-load-directory-recursivelyWhen non-nil, load directory recursively without prompt.
ready-player-shuffleNext media item is selected at random within current directory.
ready-player-minor-mode-map`ready-player’ minor mode map.
ready-player-major-mode-syntax-tableSyntax table for `ready-player-major-mode’.
ready-player-autoplayWhen non-nil, automatically start playing when media file opens.
ready-player-display-dired-playback-buffer-display-actionChoose how to display the associated playback `dired’ buffer.
ready-player-repeat-iconRepeat icon string, for example: “⇆”.
ready-player-major-mode-abbrev-tableAbbrev table for `ready-player-major-mode’.
ready-player-mode-hookHook run after entering or leaving `ready-player-mode’.
ready-player-supported-mediaSupported media types.
ready-player-major-mode-mapKeymap for `ready-player’.
ready-player-play-iconPlay button icon string, for example: “▶”.
ready-player-search-iconSearch icon string, for example: “⌕”.
ready-player-supported-videoSupported video media.
ready-player-major-mode-hookHook run after entering `ready-player-major-mode’.
ready-player-minor-mode-map-prefixThe global bindings prefix used in `ready-player-minor-mode’.
ready-player-my-media-collection-locationPath to your media collection.
ready-player-help-iconSearch icon string, for example: “⁈”.
ready-player-previous-iconPrevious button icon string, for example: “◁◁”.
ready-player-next-iconNext button icon string, for example: “▷▷”.

Commands

TABready-player-next-buttonNavigate to next button.
SPC or C-c m SPCready-player-toggle-play-stopToggle play/stop of media.
ready-player-modeToggle Ready Player mode media file recognition.
gready-player-reload-bufferReload media from file.
r or C-c m rready-player-toggle-repeatCycle through repeat settings: file, directory, off.
fready-player-seek-forwardSeek forward.
ready-player-set-album-artworkSelect image and set as album artwork.
qready-player-quitQuit `ready-player-major-mode’ window and kill buffer.
ready-player-versionShow Ready Player Mode version.
ready-player-download-album-artworkDownload album artwork to media directory.
C-c m mready-player-view-playerToggle switching between player buffer and previous buffer.
ready-player-toggle-modelineToggle displaying the mode line.
dready-player-view-dired-playback-bufferView associated `dired’ playback buffer.
ready-player-load-dired-bufferLoad a `dired’ buffer.
s or C-c m sready-player-toggle-shuffleToggle shuffle setting.
ready-player-playStart media playback.
bready-player-seek-backwardSeek backward.
a or C-c m aready-player-toggle-autoplayToggle autoplay setting.
o or eready-player-open-externallyOpen visited file in default external program.
ready-player-stopStop media playback.
n or C-c m nready-player-nextOpen the next media file in the same directory.
ready-player-download-album-artwork-and-set-metadataDownload album artwork set media metadata.
c or C-c m cready-player-open-my-media-collectionOpen my media collection from `ready-player-my-media-collection-location’.
C-c m mready-playerToggle switching between player buffer and previous buffer.
ready-player-lookup-songLook up current song on Discogs.
ready-player-major-modeMajor mode to preview and play media files.
ready-player-load-directoryLoad all media from directory (experimental).
i or C-c m iready-player-show-infoShow playback info in the echo area.
p or C-c m pready-player-previousOpen the previous media file in the same directory.
mready-player-mark-dired-fileMark the current file in the appropriate `dired’ buffer(s).
<backtab>ready-player-previous-buttonNavigate to previous button.
uready-player-unmark-dired-fileUnmark the current file in the appropriate `dired’ buffer(s).
/ or C-c m /ready-player-searchSearch the `dired’ playlist for playback (experimental).
ready-player-load-m3u-playlistLoad an .m3u playlist.
ready-player-load-last-knownAttempt to load last known media.

👉 Support this work via GitHub Sponsors