#+TITLE: pipewire-0

pipewire-0 is an [[https://www.gnu.org/software/emacs][Emacs]] interface to [[https://pipewire.org][PipeWire]].  It provides a library
to access some PipeWire functionality and a simple user interface to
handle audio devices.  It allows displaying PipeWire devices and
clients, changing volumes and muting and unmuting of PipeWire sinks
and sources and setting default sinks and sources.

pipewire-0 currently relies on the output of the PipeWire command line
tools.  It works for me but it may not work in other environments.
Feel free to use it, fix it, fork it.  [[*Contact][Contact me]] if you want to
discuss anything.

* Usage

** Installation

pipewire-0 currently requires presence of PipeWire command line tools,
namely [[https://docs.pipewire.org/page_man_pw_cli_1.html][pw-cli]] and [[https://docs.pipewire.org/page_man_pw_metadata_1.html][pw-metadata]].

You can install pipewire-0 from [[https://melpa.org/#/pipewire][MELPA]].  If you use [[https://github.com/radian-software/straight.el][straight.el]] and
prefer using source repos directly, you can install pipewire-0 as
follows:

   #+begin_src elisp
(straight-use-package
 '(pipewire-0 :type git
              :repo "https://git.zamazal.org/pdm/pipewire-0"
              :local-repo "pipewire-0"))
   #+end_src

To install pipewire-0 manually, put the *.el files to a site-lisp
directory and add the following line to your Emacs configuration:

   #+begin_src elisp
(require ’pipewire)
   #+end_src

** User interface

=M-x pipewire= enters a buffer with PipeWire objects:

#+ATTR_HTML: :alt Emacs PipeWire buffer
[[./screenshot.jpg]]

Use =C-h m= to display basic help.

Most of the interactive functions can be used anywhere:

- =pipewire-increase-volume=
- =pipewire-decrase-volume=
- =pipewire-set-volume=
- =pipewire-toggle-muted=
- =pipewire-toggle-microphone=
- =pipewire-set-default=

They can be bound to multimedia keys:

   #+begin_src elisp
(global-set-key (kbd "<XF86AudioMute>") 'pipewire-toggle-muted)
(global-set-key (kbd "<XF86AudioLowerVolume>") 'pipewire-decrease-volume)
(global-set-key (kbd "<XF86AudioRaiseVolume>") 'pipewire-increase-volume)
   #+end_src

** Configuration

=M-x customize-group RET pipewire RET=

** Library

pipewire-0 consists of the following source files:

- [[file:pipewire-lib.el][pipewire-lib.el]] :: PipeWire library to be used in Elisp programs.
- [[file:pipewire-access.el][pipewire-access.el]] :: PipeWire communication interface, not supposed to be
  used outside =pipewire-lib=.
- [[file:pipewire.el][pipewire.el]] :: User commands and interface.

Look into [[file:pipewire-lib.el][pipewire-lib.el]] to see what public =pipewire-lib-*= functions are
available there.  For example, the following snippet can be used to
display current volume level of the default audio sink:

   #+begin_src elisp
(let ((object (pipewire-lib-default-audio-sink)))
  (format "%s%s"
          (pipewire-lib-volume object t)
          (if (pipewire-lib-muted-p object) "(M)" "")))
   #+end_src

* Notes

PipeWire is currently accessed using [[https://docs.pipewire.org/page_man_pw_cli_1.html][pw-cli]] command line utility.
pw-cli output is apparently undocumented and changes between versions
so this is not a reliable way to communicate with PipeWire.  But I
don’t know about anything better currently.  Nevertheless, it’s easy
to replace pw-cli with something else in [[file:pipewire-access.el][pipewire-access.el]].

** Why is it named pipewire-0?

I wrote pipewire-0 because I couldn’t find any Emacs interface to
PipeWire.  I would name it simply pipewire or pipewire-el but I expect
that someone will write a full-fledged PipeWire interface sooner or
later.  I’d like to avoid confusion and reserve the plain name for the
future interface, while having the basic above zero, pipewire-0,
support for now.

* Contact

pipewire-0 is available at [[https://git.zamazal.org/pdm/pipewire-0][git.zamazal.org]].  You can file issues
there.

If you don’t want to discuss things publicly or to bother registering
at yet another web site, you can reach me at [[mailto:pdm@zamazal.org][pdm@zamazal.org]].