+TITLE: empv.el

[[https://melpa.org/#/empv][file:https://melpa.org/packages/empv-badge.svg]]

An Emacs media player, based on [[https://mpv.io/][mpv]]. More precisely this package provides somewhat comprehensive interface to mpv with bunch of convenient functionality like an embedded radio manager, YouTube interface, local music/video library manager, lyrics manager etc.

Scroll to bottom of the page to see the screenshots.

/empv/ is mostly focused on audio but it also provides some means to manage videos. It also supports YouTube searches for consuming audios or videos.

Workflow is generally =M-x empv-something= and =completing-read= based, no buffers or complex interfaces (except for the tabulated YouTube results with thumbnails).

• Installation First, you need to install [[https://mpv.io][mpv]], go check out its installation instructions for your operating system/distribution.

empv is available through [[https://melpa.org/#/empv][MELPA]]. If you have it set up already, just do ~M-x package-install empv~ and you are good to go. Otherwise please see [[https://melpa.org/#/getting-started][MELPA getting started]] page to learn how you can install packages through MELPA or see the following installation options.

Another way to install =empv.el= would be using either [[https://github.com/radian-software/straight.el][straight]] or [[https://github.com/quelpa/quelpa-use-package][quelpa]] package managers:

+begin_src elisp

;; Using straight: (use-package empv :straight (:host github :repo "isamert/empv.el"))

;; Using quelpa: (use-package empv :quelpa (empv :fetcher github :repo "isamert/empv.el"))

+end_src

Yet another option is just downloading =empv.el= file and putting into your =load-path=, afterwards you can simply do the following in your =init.el=:

+begin_src elisp

(require 'empv)

+end_src

Some functionality may require the external program [[https://github.com/sharkdp/fd][fd]]. You are also advised to install it.

• Basics See /Keybindings/ section down below to learn more about the bindings and the commands. Here are a few basic functions that'll get you started:

• empv-play

• empv-play-{file,audio,video,directory,radio,random-channel}

• empv-playlist-{select,next,prev,clear,shuffle}

• empv-display-current

• empv-toggle

• empv-toggle-video

• empv-youtube

• empv-volume-{down,up}

• empv-chapter-{prev,next,select}

• empv-exit

** Keybindings No default keybindings are provided but there is ~empv-map~ keymap which contains all the useful empv actions. You can bind this keymap to a key, like following:

+begin_src emacs-lisp

(bind-key "C-x m" empv-map)

+end_src

...and now you can do ~C-x m t~ to toggle playback, for example. Do ~M-x describe-keymap empv-map~ to list all actions in this keymap.

Some keys are repeatable in this keymap. Continuing with the example above, you can do ~C-x m n~ to switch to the next media item in the playlist and if you want to go to the next item again just hit ~n~ this time (or ~N~ to go back one item), as it's repeatable. Keys that control sound level, playback speed are also repeatable.

** Playing options When you invoke one of the functions that triggers playing a media, you'll be automatically presented with some options that asks you whether you want to /play directly/, /enqueue next/ or /enqueue last/. By default this uses ~read-multiple-choice~ to ask you about your choices. You can change this to use ~completing-read~ based interface if you want by setting ~empv-action-handler~ variable to ~completing-read~. See the variable documentation for more information.

• Extra functionality and configuration Do =M-x= and then search for =empv-= to list all available functions. Currently there are ~66 interactive functions. Also check out all configuration options by doing =M-x customize-group empv RET=. I'll go over some extra configuration options that you may want to use:

** General YouTube configuration /empv.el/ lets you search in YouTube videos/playlists and play them in background or just play the video itself. It also let's you view YouTube comments of a video in a nicely formatted org buffer. This is done through [[https://github.com/iv-org/invidious][invidious]] API. It's a privacy respecting front-end (and API) for YouTube. To be able to use these features, you need to set an invidious instance manually, like:

+begin_src elisp

(setq empv-invidious-instance "https://some-invidious-instance.com/api/v1")

+end_src

You can select an invidious instance from [[https://api.invidious.io/][here]].

The entry-point function is ~empv-youtube~ which asks your input to search in YouTube videos. If you have ~consult~ installed, it'll also show you search suggestions while you are typing.

Thumbnails greatly help to identify the right video in a search. Using ~completing-read~ may sometimes fall short here and for that you can use ~empv-youtube-tabulated~. This function searches given term in YouTube and display them in a buffer with video thumbnails.

You can also set ~empv-youtube-use-tabulated-results~ to a non-nil value to make YouTube commands use the tabulated interface by default at all times.

There is also functions for reopening the last YouTube search results: ~empv-youtube-last-results~ and ~empv-youtube-tabulated-last-results~ which helps if you accidentally close the search results or you did a ~completing-read~ search and you actually wanted to see thumbnails with the tabulated results.

** Local media management ~empv-play-audio~ and ~empv-play-video~ functions let's you quickly select a local media file found on your computer through ~completing-read~ and play it. This works by finding all files under ~empv-audio-dir~ or ~empv-video-dir~ (Also see ~empv-video-file-extensions~, ~empv-audio-file-extensions~ and ~empv-max-directory-search-depth~ variables). You can even enqueue multiple files at the same time by using ~embark~. See down below to learn how you can configure embark support.

You can still use ~empv-play-file~ to select and play files using classic ~read-file-name~ interface or ~empv-play-thing-at-point~ on a URI or in a dired buffer to play selected media.

** Radio/stream management /Radio manager/ is just a way to easily play internet streams (any type of stream that mpv supports, it might be even YouTube videos etc. It doesn't event need to be internet resources, might be just local files too). You just need to set ~empv-radio-channels~ as you wish in the following format (following is the default value, so actually you don't need to set it if you want to only use these radios):

+begin_src emacs-lisp

(setq empv-radio-channels '(("SomaFM - Groove Salad" . "http://www.somafm.com/groovesalad.pls") ("SomaFM - Drone Zone" . "http://www.somafm.com/dronezone.pls") ("SomaFM - Sonic Universe" . "https://somafm.com/sonicuniverse.pls") ("SomaFM - Metal" . "https://somafm.com/metal.pls") ("SomaFM - Vaporwaves" . "https://somafm.com/vaporwaves.pls")))

+end_src

Now you can use ~empv-play-radio~ to select and play one of these streams. You can also use ~empv-play-random-channel~ to start playing one of these channels randomly. There is also ~empv-log-current-radio-song-name~ which logs the current song/media title to a file in the specified format. This is useful for quickly capturing name of the song you liked that is currently playing on the selected radio (See ~empv-radio-log-file~ and ~empv-radio-log-format~ variables and their documentations).

** Embark and Consult integration If you have [[https://github.com/minad/consult][consult]] and [[https://github.com/oantolin/embark][embark]] installed on your Emacs, ~empv.el~ will automatically integrate itself with them. If you have ~consult~ installed, you get search suggestions during YouTube searches (~empv-youtube~) and if you have embark installed you get embark actions for playing/enqueueing selected media. This makes it easy to enqueue bunch of media results using ~embark-act-all~, or you can call ~embark-act~ on a file inside a ~dired~ buffer and you'll see options to play or enqueue given file or folder.

To enable extra embark integration, add the following to your init file:

+begin_src emacs-lisp

(with-eval-after-load 'embark (empv-embark-initialize-extra-actions))

+end_src

This is not automatically applied because it has some drawbacks, please refer to the documentation of ~empv-embark-initialize-extra-actions~.

** Viewing YouTube videos If you start playing a YouTube video, it'll start playing in background. You may be tempted to call =empv-toggle-video= to start watching the video itself but it'll not work. /mpv/ tries to be smart when it's in background and it only downloads the audio if it's possible. If you want to be able to watch YouTube videos whenever you want, you need to add something like this to your configuration to change the default ~--ytdl-format~ of mpv to force download videos:

+begin_src elisp

(add-to-list 'empv-mpv-args "--ytdl-format=bestvideo+bestaudio/best[ext=mp4]/best") ;; It's bestvideo+bestaudio/best by default, we slightly change it to ;; override the default no-video behavior.

+end_src

See [[https://github.com/ytdl-org/youtube-dl/blob/master/README.md#format-selection][this page]] for how you can use =--ytdl-format= option.

** Lyrics manager empv has two functions for managing lyrics:

• ~empv-lyrics-current~ :: Get the lyrics for currently playing (or paused) song. First, it checks if there is a lyrics embedded in the media file, otherwise it tries to fetch it from web. This works fairly well for popular songs, may have false positives for more obscure songs.
  • The resulting buffer is editable and you can embed the lyrics to media file by doing ~C-c C-c~ (or by calling ~empv-lyrics-save~). For this to work, you need to have ~eyeD3~ program available in your path. Also check out ~empv-lyrics-save-automatically~ variable.
• ~empv-lyrics-show~ :: Like ~empv-lyrics-current~ but asks you for a song name.

** Saving playback position =empv-save-and-exit= shuts down empv and saves the current playing position but you can also add ~--save-position-on-quit~ to ~empv-mpv-args~ to get the same effect by default so that every time you quit empv, it'll automatically save the playback position of the currently playing file and it'll seek to previous position on start.

+begin_src emacs-lisp

(add-to-list 'empv-mpv-args "--save-position-on-quit")

+end_src

** Getting notified on media change empv already notifies you when media changes by default (see ~empv-display-events~), or you can always call ~empv-display-current~ to get the details for currently playing media and status of the media player itself. But you may also want to take an action programatically when current media (or any other property of mpv) changes. You can register an observer to underlying property changes of /mpv/ through ~empv-observe~ function. See [[https://github.com/mpv-player/mpv/blob/master/DOCS/man/input.rst#property-list][list of properties]] that you can subscribe to their changes. Here is an example showing you how you can register an observer to ~metadata~ change event:

+begin_src emacs-lisp

(empv-observe 'metadata (lambda (data) (message "Metadata changed, new metadata is: %s" data)))

+end_src

** Overriding the quit key for mpv If you are watching something in mpv window and hit ~q~ key, it will close mpv altogether and you may loose your current playlist etc. A more graceful way to handle this would be simply hiding mpv instead of shutting it down. Add this to your init file to override quit key with a functionality that simply pauses the video and hides the mpv window.

+begin_src elisp

(add-hook 'empv-init-hook #'empv-override-quit-key)

+end_src

** Resetting playback speed after quit If you have applied the workaround above, you can set the following option to non-nil and from then on, whenever you hit ~q~ in mpv's video view, the playback speed will be reset to 1. This should be set before starting empv (or quit it first by doing ~empv-quit~ and re-start it to apply this configuration).

+begin_src emacs-lisp

(setq empv-reset-playback-speed-on-quit t)

+end_src

This is useful if you watch videos on higher speeds but you want to quickly restore the playback speed after being done with the video.

• Screenshots