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

Command Line Interface
======================

You can analyze audio files by running ``tuner`` and passing the filename(s)
as arguments.  See `the man page`_ for details about option arguments.

.. _the man page: tuner.html

.. admonition:: Wildcards

    :command:`tuner` expects the shell to handle the expanstion of wildcard
    characters such as ``*``.  The default shell on Windows doesn't do this.

.. note::

    ``tuner`` will use saved options from ``saved_options.ini``, except for
    the **pitch** and **tempo** options.  Pitch and tempo correction is only
    done in the GUI.

    See :ref:`savefile`.

    Saved options can be overridden by command line arguments.

    If you don't want to use saved options at all, use the ``--savefile``
    option to set the save file to /dev/null (or your operating system's
    equivalent).  A nonexistent file will also work.

.. versionchanged:: 0.11.2
   Command line arguments didn't used to override saved options.

Output
~~~~~~

The result should look something like this:

.. literalinclude:: _static/cli_example

This shows information about the most prominent pitches in the audio.

Lower pitches are on top and higher pitches are on the bottom.  There may be
an option in a future version to reverse this.

.. rubric:: Note

This column shows which note in the selected tuning system the pitch is
closest to.  (It's not necessarily the note it's *supposed* to be, since
sometimes audio is so far off it ends up in a completely different key!)

.. rubric:: Standard

This column shows the ideal frequency of the note in the selected tuning
system.

.. rubric:: Measured

This column shows the actual frequency of the pitch in the audio.

.. rubric:: Discrepancy

This column shows the discrepancy between the frequencies shown in the
**Standard** and **Measured** columns.

The number on the left is the discrepancy in cents.

The meters range from -50 c to 50 c.  A needle left of center means the pitch
is too flat, and a needle right of center means the pitch is too sharp.

.. rubric:: Correction

This column shows the pitch correction factor that would center the needle.

If you have `mpv`_ installed (not just libmpv2 but the actual **mpv**
program), you can play the audio with the correction applied like this:

.. code:: bash

   mpv --af=rubberband=pitch-scale=$CORRECTION "$FILE"

For example, to play Getting In Tune with a correction factor of 0.995, do
this:

.. code:: bash

   mpv --af=rubberband=pitch-scale=.995 "06.Getting_In_Tune_(1995_remix).ogg"

Writing a wrapper shell script to make this more convenient is left as an
exercise for the reader.

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

.. admonition:: Color output

    When outputting directly to a terminal, :command:`tuner` makes the dashed
    lines gray to make the important parts of the meters stand out and be
    easier to read.  This doesn't work on Windows unless `colorama`_ is
    available.

    Use the ``-c`` or ``--color`` option to force color output even when
    stdout is going to a file or pipe.  If you're piping to :command:`less`,
    use less's ``-R`` option to make it display color, like this:
    :code:`tuner -c * | less -R`

.. _colorama: https://github.com/tartley/colorama

Tab Completion
~~~~~~~~~~~~~~

.. versionadded:: 0.12.0

``tuner`` and ``tuner-gui`` can generate their own scripts to be added to your
shell's tab completion system.  This works for **bash**, **zsh** and **tcsh**.
This is done with the ``--print-completion`` command line argument, followed
by the name of the shell.  For example, to generate a bash shell completion
script for ``tuner`` and write it to a file called "tuner", run:

.. code:: bash

    tuner --print-completion bash > tuner

The hardest part is figuring out where that file should go.  Here's an excerpt
from the **bash-completion** readme file
(``/usr/share/doc/bash-completion/README.md.gz`` on Debian systems):

   | Q. Where should I install my own local completions?
   | 
   | A. Put them in the ``completions`` subdir of ``$BASH_COMPLETION_USER_DIR``
   |    (defaults to ``$XDG_DATA_HOME/bash-completion`` or
   |    ``~/.local/share/bash-completion``
   |    if ``$XDG_DATA_HOME`` is not set) to have them loaded automatically
   |    on demand when the respective command is being completed.
   |
   |    [...]
   |
   |    Alternatively, you can write them directly in ``~/.bash_completion``
   |    which is loaded eagerly by our main script.
   |
   |    [...]
   |
   |    ...completions are automatically loaded on demand based on invoked
   |    commands' names, so be sure to name your completion file
   |    accordingly...

For other shells, refer to the appropriate documentation.