..  This file is part of Audio Tuner.

    Copyright 2025, 2026 Jessie Blue Cassell <bluesloth600@gmail.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.

Installation on a Unix-Like OS
==============================

Audio Tuner and its GUI are available on PyPI:

https://pypi.org/project/audio-tuner/

https://pypi.org/project/audio-tuner-gui/

You will have to install some dependencies manually.

Dependencies
~~~~~~~~~~~~

Use your system's package manager to make sure **Python version 3.11 or
higher** and **libmpv2 version 0.40.0 or higher** are installed.  You'll also
need :command:`pip` or :command:`pipx` to install Audio Tuner.
:command:`pipx` is recommended, because it can install Audio Tuner in a
virtual environment in your home directory without messing with the system
Python environment.

.. note::

    :command:`pip` may or may not be included in your distro's python package.
    :command:`pipx` is usually a separate package.

.. note::

    Audio Tuner can use **ffmpeg** instead of **libmpv2**, with some caveats:
    The player and export functionality in the GUI won't work, among other
    things.  See the :code:`backends` option in the :ref:`config_file` for
    details.

The following dependencies will be installed automatically inside Audio Tuner's
virtual environment by :command:`pipx`:

* `numpy`_
* `python-mpv`_
* `platformdirs`_
* `shtab`_

.. versionadded:: 0.12.0
   shtab dependency

.. versionremoved:: 0.10.0
   namedpipe dependency

If you install the GUI, one more dependency will be automatically installed:

* `PyQt6`_

.. _numpy: https://www.numpy.org
.. _PyQt6: https://www.riverbankcomputing.com/software/pyqt/
.. _python-mpv: https://github.com/jaseg/python-mpv
.. _platformdirs: https://github.com/platformdirs/platformdirs
.. _shtab: https://github.com/iterative/shtab

Installing the GUI
~~~~~~~~~~~~~~~~~~

To install the graphical user interface, run this as a regular user (not root):

.. code:: bash

    pipx install audio-tuner-gui

``tuner-gui`` should now be available.

.. note::

    The audio-tuner base package is included in the same virtual environment
    as a dependency of audio-tuner-gui, but pipx doesn't make the ``tuner``
    CLI app available by default.  If you want it, you can pass the
    **--include-deps** option in the above command to tell pipx to make it
    available (along with whatever apps other dependencies have), or you can
    follow the instructions below to install audio-tuner into it's own virtual
    environment.

Installing the CLI on it's own
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run this as a regular user (not root):

.. code:: bash

    pipx install audio-tuner

``tuner`` should now be available.

Uninstalling
~~~~~~~~~~~~

If the GUI's installed:

.. code:: bash

    pipx uninstall audio-tuner-gui

If the CLI is installed in it's own virtual environment:

.. code:: bash

    pipx uninstall audio-tuner

Upgrading from a Previous Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the GUI's installed:

.. code:: bash

    pipx upgrade audio-tuner-gui

If the CLI is installed in it's own virtual environment:

.. code:: bash

    pipx upgrade audio-tuner

Optional Extras
~~~~~~~~~~~~~~~

You can install additional dependencies into Audio Tuner's virtual environment
for more features.

Matplotlib
^^^^^^^^^^

http://matplotlib.org/

Matplotlib enables ``tuner`` and ``tuner-gui`` to display plots of the audio
spectrum.

To install:

If the GUI's installed:

.. code:: bash

    pipx inject audio-tuner matplotlib

If the CLI is installed in it's own virtual environment:

.. code:: bash

    pipx inject audio-tuner matplotlib