Empv.el

#+TITLE: empv.el

[[https://stable.melpa.org/#/empv][file:https://stable.melpa.org/packages/empv-badge.svg]] [[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, Subsonic/Navidrome client, local music/video library manager, lyrics manager etc.

Scroll to bottom of the page to see the [[#screenshots][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).

#+begin_quote [!TIP]

Existing users: Please see the [[file:CHANGELOG.org][CHANGELOG.org]] for new features & fixes! #+end_quote

• Contents :noexport: :PROPERTIES: :TOC: :include siblings :depth 3 :ignore this :END: :CONTENTS:

• [[#installation][Installation]]
• [[#basics][Basics]]
  • [[#keybindings][Keybindings]]
  • [[#playing-options][Playing options]]
• [[#extra-functionality-and-configuration][Extra functionality and configuration]]
  • [[#general-youtube-configuration][General YouTube configuration]]
    • [[#youtube-channel--playlist-search][YouTube Channel & Playlist search]]
    • [[#youtube-comments][YouTube Comments]]
  • [[#local-media-management][Local media management]]
  • [[#radiostream-management][Radio/stream management]]
  • [[#subsonicnavidrome-integration][Subsonic/Navidrome integration]]
  • [[#embark-and-consult-integration][Embark and Consult integration]]
  • [[#viewing-youtube-videos][Viewing YouTube videos]]
  • [[#lyrics-manager][Lyrics manager]]
  • [[#saving-playback-position][Saving playback position]]
  • [[#getting-notified-on-mediametadataproperty-change][Getting notified on media/metadata/property change]]
    • [[#using-variables--hooks][Using variables & hooks]]
    • [[#using-empv-observe][Using empv-observe]]
  • [[#overriding-the-quit-key-for-mpv][Overriding the quit key for mpv]]
  • [[#resetting-playback-speed-after-quit][Resetting playback speed after quit]]
  • [[#hydra][Hydra]]
• [[#screenshots][Screenshots]] :END:

• 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

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

You may also employ the use of a hydra instead - please see [[*Hydra][here]] for more details.

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

#+begin_quote [!TIP]

Also take a look at [[https://github.com/isamert/dotfiles/blob/054c00e2c3a1cbef79d88973b04b8f158da389dd/emacs/init.el#L7841][my /empv.el/ configuration]] after reading down below to see how they are applied. #+end_quote

** 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]].

#+begin_quote [!TIP]

Lately, YouTube has aggressively targeted Invidious instances, making working ones hard to find, and self‑hosting is not feasible for everyone, so I wrote ivjs: a simple TypeScript/[[https://deno.com/][Deno]] wrapper around [[https://github.com/LuanRT/YouTube.js][YouTube.js]] that provides an Invidious-like API exposing only the endpoints used by /empv.el/ for its YouTube features, and can be used as a lightweight alternative to running a full Invidious instance. To use it instead, do:

#+begin_src elisp (setq empv-invidious-instance 'ivjs) #+end_src

/empv.el/ will handle the lifecycle of ivjs process, you don't need to anything else. If you want to manually manage it, see [[file:ivjs/README.org][ivjs README]]. This requires [[https://deno.com/][Deno]] to be installed on your machine.

ivjs currently does not support pagination, you will only get the first page of the results. #+end_quote

#+begin_quote [!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 [[https://github.com/iv-org/invidious/issues/4734][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. #+end_quote

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

#+begin_quote [!TIP]

[[https://github.com/minad/consult][Consult]] and [[https://github.com/oantolin/embark][embark]] are essential part of YouTube workflow in /empv.el/. See the [[#embark-and-consult-integration][Embark and Consult integration]] down below. #+end_quote

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