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

Audio Tuner
===========

A tool for musicians that analyzes and corrects the pitch of recorded audio.

Base package on PyPI:  https://pypi.org/project/audio-tuner/

GUI on PyPI:  https://pypi.org/project/audio-tuner-gui/

Codeberg page:  https://codeberg.org/bluesloth/audio_tuner

Motivation
~~~~~~~~~~

A surprisingly high proportion of recorded music doesn't conform to any
standard tuning system.  You expect an A4 to be 440 Hz, but when you try to
play along you realize it's not.  Audio Tuner is a tool for measuring the
frequencies in an audio recording so it can be corrected if necessary.  It has
a CLI and an optional GUI, both of which are designed to be convenient enough
to use that you can do it with a musical instrument strapped to you.

The primary use case is to correct the tuning of your favorite songs so you
can practice playing an instrument by playing along with them, but it can be
used in any situation where you need to analyze and correct the pitch of a
recording.

What it's not
~~~~~~~~~~~~~

Audio Tuner is not autotune.  It pitch corrects entire songs, not individual
notes.

Graphical User Interface
~~~~~~~~~~~~~~~~~~~~~~~~

:doc:`GUI Quick Start <gui_quick_start>`

:doc:`GUI Documentation <gui>`

The GUI program is ``tuner-gui``.  In addition to frequency analysis, it
includes an integrated audio player and file export capability with pitch
and/or tempo correction.  Pitch and tempo can be adjusted on the fly while the
audio is playing.

The GUI is under active development, with more features and usability
improvements planned for future versions.  The current version is already
usable, however.

``tuner-gui`` man page in html format:  `tuner-gui`_

.. _tuner-gui: tuner-gui.html

Command Line Interface
~~~~~~~~~~~~~~~~~~~~~~

:doc:`CLI Documentation <cli>`

The CLI program is ``tuner``.  It's designed in the spirit of the Unix
philosophy of small simple programs that do one thing well.  It can give you
the pitch correction factor, and then you'll need a different program such as
`mpv`_ to play the audio with the correction applied.

.. _mpv: https://mpv.io/

``tuner`` man page in html format:  `tuner`_

.. _tuner: tuner.html

Python Library
~~~~~~~~~~~~~~

The package with the CLI program also includes the Python library
``audio_tuner`` which can be used to analyze audio frequencies in your own
projects.

:doc:`Audio Tuner library API <api>`

Free as in Freedom
~~~~~~~~~~~~~~~~~~

Audio Tuner and it's documentation are licensed under the `GNU General Public
License`_ version 3 or later.

.. _GNU General Public License: https://gnu.org/licenses/gpl.html

See
`What is Free Software? <https://www.gnu.org/philosophy/free-sw.html>`_
and
`Copyleft: Pragmatic Idealism
<https://www.gnu.org/philosophy/pragmatic.html>`_.

Versioning
~~~~~~~~~~

Audio Tuner attempts to use `Semantic Versioning`_, but with :pep:`440`
compatible version numbers.

New versions of the base Audio Tuner package and Audio Tuner GUI are released
at the same time with the same version numbers.  The API is already reasonably
stable, but of course nothing's guaranteed until it reaches version 1.0.0.  

.. _Semantic Versioning: https://semver.org

Installation
~~~~~~~~~~~~

* :doc:`Installation on a Unix-like OS <install_on_nix>`
* :doc:`Installation on Microsoft Windows <install_on_windows>`

Configuration File
~~~~~~~~~~~~~~~~~~

A configuration file is not required, but you can make one to change the
default settings if you like.

:ref:`config_file`

Troubleshooting
~~~~~~~~~~~~~~~

:doc:`Troubleshooting guide <troubleshooting>`

The bug tracker is at https://codeberg.org/bluesloth/audio_tuner/issues

.. toctree::
    :maxdepth: 2
    :hidden:

    gui_quick_start
    gui
    cli
    install_on_nix
    install_on_windows
    config_file
    troubleshooting
    api

..  Indices and tables
    ==================

    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`