empv.el

An Emacs media player, based on 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 mpv, go check out its installation instructions for your operating system/distribution.

empv is available through MELPA. If you have it set up already, just do M-x package-install empv and you are good to go. Otherwise please see 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 straight or quelpa package managers:

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

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:

(require 'empv)

Some functionality may require the external program 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:

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

…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.

Tip

Also take a look at my empv.el configuration after reading down below to see how they are applied.

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 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:

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

You can select an invidious instance from here.

Important

empv.el doesn’t use Invidious to play videos; it redirects YouTube links that it gathers from Invidious directly to MPV. This is beneficial, especially given this issue affecting Invidious. Since empv.el only utilizes Invidious for metadata retrieval, the issue doesn’t impact playback. But it’s important to note this distinction for privacy considerations.

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 do M-x empv-toggle-youtube-tabulated-results to switch to a tabulated search result interface with video thumbnails in a dedicated buffer. To make this behavior permanent 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. (There is also an embark action named empv-youtube-become-tabulated which does the same thing, but without closing the completing-read first.)

Tip

Consult and embark are essential part of YouTube workflow in empv.el. See the Embark and Consult integration down below.

YouTube Channel & Playlist search

empv also supports YouTube playlists and channels:

• Do empv-youtube-channel to search for YouTube channels. After that, you can select a channel to list it’s videos (sorted by either popular or newest order), or you can directly enqueue all videos of the channel (by issuing empv-play embark action in completing-read interface or by hitting P (empv-youtube-results-play-current) in tabulated results mode).
• Do empv-youtube-playlist to search for YouTube playlists. After that you can enqueue all playlist items by selecting a playlist. Then you can use normal playlist functions (i.e. empv-playlist-select etc.).

YouTube Comments

Just hit c (or do empv-youtube-results-show-comments) in a tabulated search results buffer to show comments (and a little details) of the selected video. Or use empv-youtube-show-comments embark action to show comments in a completing-read results buffer.

You can use empv-youtube-show-current-comments to show comments of currently playing YouTube video.

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):

(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")))

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 consult and 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:

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

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:

(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.

See 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.

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

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 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:

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

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.

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

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).

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

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

Actions
Info
Playlist & Chapters
Lyrics
YouTube search suggestion
YouTube results
YouTube tabulated results