.. This file is part of Audio Tuner. Copyright 2025, 2026 Jessie Blue Cassell 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 . .. |triangle| unicode:: U+2023 .. |play| unicode:: U+25B6 Graphical User Interface ======================== This is a detailed reference guide for Audio Tuner's GUI. .. figure:: _static/Screenshot_main.png The main GUI, using the Qt port of the Adwaita-dark theme and the Tango icon theme. Starting ~~~~~~~~ Start the GUI by running ``tuner-gui``. If you start it from a command line, you can change the defaults for various options by passing arguments. You can also give it files to immediately analyze on startup, just like the CLI version. See `the man page`_ for details. .. _the man page: tuner-gui.html Menus ~~~~~ File ^^^^ .. rubric:: Reload saved options .. versionadded:: 0.11 If the current selection in the :ref:`analyzed_audio_panel` has saved options associated with it in the :ref:`savefile`, this loads them into the Option Panel. It does not automatically apply them, you need to use the :guilabel:`Apply to selected` button for that. .. rubric:: Save options .. versionadded:: 0.11 Saves the options that have been applied to the currently selected analyzed audio to the :ref:`savefile`. See :ref:`savingoptions`. .. rubric:: Delete saved options .. versionadded:: 0.11 Deletes the saved options associated with the currently selected analyzed audio from the :ref:`savefile`. .. rubric:: Export audio Opens the :ref:`export_window`. .. rubric:: Exit Exits Audio Tuner. View ^^^^ .. rubric:: Show dB plot *Requires matplotlib* Opens a window showing a log-log plot of power vs. frequency for the currently selected analyzed audio. .. rubric:: Show power plot *Requires matplotlib* Opens a window showing a linear-log plot of power vs. frequency for the currently selected analyzed audio. .. rubric:: Message log Opens the :ref:`message_log`. Options ^^^^^^^ .. rubric:: Show hidden files If checked, the :ref:`file_selector_panel` will show hidden files. .. rubric:: Play between Start time and End time If checked, the player will only play the audio between the :guilabel:`Start time` and :guilabel:`End time` as set in the :ref:`option_panel`. .. rubric:: Show option panel If checked, the :ref:`option_panel` will be shown instead of the :ref:`file_selector_panel`. .. rubric:: Select audio output device Opens a window for selecting the audio output device used by the player. .. rubric:: Correction backend .. versionadded:: 0.12 Choose the pitch correction backend. The available backends are **scaletempo2** (the default) and **rubberband**. **scaletempo2** uses less CPU and allows gapless playback. **rubberband** sounds smoother and less harsh at extreme settings (large differences between pitch and tempo correction factors), but uses a lot of CPU power and breaks gapless playback, making it unsuitable for playlists requiring seamless transitions between songs. .. rubric:: Debug dragging If checked, debug information will be added to the :ref:`message_log` whenever anything is dragged onto the Audio Tuner window. This can be useful for diagnosing problems with drag and drop. Go ^^ These all do the same thing as the buttons on the :ref:`file_selector_panel`. .. rubric:: Up Go to the parent directory. .. rubric:: Back Go to the previous directory in the navigation history. The status bar (at the bottom of the window) will tell you specifically which directory that is when you hover the mouse cursor over this menu item. .. rubric:: Forward Go to the next directory in the navigation history. The status bar (at the bottom of the window) will tell you specifically which directory that is when you hover the mouse cursor over this menu item. .. rubric:: Home Go to your home directory. Help ^^^^ .. rubric:: About Audio Tuner Open the :guilabel:`About` window, which shows the version, copyright information and the :ref:`config_file` and :ref:`savefile` paths. .. _toolbar: Toolbar ~~~~~~~ .. figure:: _static/Screenshot_Toolbar.png From left to right: .. rubric:: Option Panel/File Selector Panel toggle button Switches between the :ref:`option_panel` and the :ref:`file_selector_panel`. The icon shown on the button represents what you'll get if you push it, not what is currently shown. Keyboard shortcut: :kbd:`F2` .. rubric:: Message log button Opens the :guilabel:`Message log` window. The icon will change to alert you if there's any error messages in the log you haven't seen yet. .. rubric:: Play button Begins playing audio. What gets played depends on what is selected in the :ref:`analyzed_audio_panel`, and what's in the :ref:`playlist`. .. rubric:: Pause button Pauses and unpauses the player. .. rubric:: Stop button Stops the player and unloads the audio. .. rubric:: Previous button .. versionadded:: 0.12 Goes to the previous entry in the playlist. .. rubric:: Skip back button Backs up 10 seconds. If **Option** |triangle| **Play between Start time and End time** is selected, this won't put the play position before :guilabel:`Start time` (see :ref:`option_panel`). .. rubric:: Skip forward button Jumps forward 10 seconds. If **Option** |triangle| **Play between Start time and End time** is selected, this won't put the play position after :guilabel:`End time` (see :ref:`option_panel`). .. rubric:: Next button .. versionadded:: 0.12 Goes to the next entry in the playlist. .. rubric:: Play position Displays the time from the beginning of the audio in minutes and seconds. The rate at which this increases is affected by tempo correction, so this may not reflect the actual amount of time passed since the beginning of the audio. .. rubric:: Play position slider Shows the play position from :guilabel:`Start time` to :guilabel:`End time`. You can click and drag it to change the position. .. rubric:: Time remaining Displays the time to the end of the audio in minutes and seconds. The rate at which this decreases is affected by tempo correction, so this may not reflect the actual amount of time until the end of the audio. .. rubric:: Now Playing A label that shows the title of the audio loaded into the player. .. rubric:: Exit Exits Audio Tuner. .. _display: Display ~~~~~~~ .. figure:: _static/Screenshot_Display.png The **Display** displays information about the most prominent pitches in the audio. Lower pitches are on top and higher pitches are on the bottom, to maintain consistency with the output of the CLI front end. There may be an option in a future version to reverse this. If there's not enough room to show everything at once, a thin green scroll bar will appear on the right. You can scroll around using the scroll bar, the mouse wheel, or by clicking and dragging in the main display area. You can even use the :kbd:`Up`, :kbd:`Down`, :kbd:`PgUp` or :kbd:`PgDn` keys if the Display has keyboard focus. .. 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 with pitch correction applied. (If no pitch correction has been applied yet, it shows the original frequency unmodified.) .. 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. There's a tick mark on the bottom of the line every 25 c, while each tick mark on top of the line represents an increment of .005 in the frequency ratio (or .01 if you only count the major tick marks). .. rubric:: Correction This column shows the pitch correction factor needed to center the needle. .. note:: This does NOT show the correction that has been applied. In other words, "Correction" is short for "This is what correction is needed", not "Here's the correction factor you applied". .. _quick_tuner: Quick Tuner ~~~~~~~~~~~ .. figure:: _static/Screenshot_Quick_Tuner.png .. versionadded:: 0.12 The **Quick Tuner** shows the pitch correction applied to the currently selected analyzed audio, and is a convenient way to adjust it. It doesn't do anything you can't already do with the :ref:`option_panel`; it's purely there for convenience. The box with the number and the little up and down buttons changes pitch in 100 cent increments, which corresponds to a key change in the 12 Tone Equal Temperament system. The slider can be dragged with the mouse for fine adjustment. Any change is applied to the currently selected analyzed audio immediately. There's no need to push an apply button like in the :ref:`option_panel`. .. note:: Tempo is adjusted along with pitch by default. To adjust pitch only, turn off the :ref:`link_button` in the :ref:`option_panel` and apply the change. Note that Link is not a global setting. Each item in the :ref:`analyzed_audio_panel` has it's own Link setting, and doing this will only change the currently selected one. .. _file_selector_panel: File Selector Panel ~~~~~~~~~~~~~~~~~~~ .. figure:: _static/Screenshot_File_Selector_Panel.png This can be navigated with either the keyboard or the mouse. .. hint:: The way you navigate, highlight and select things here pretty much works the same as a standard GUI file manager. .. hint:: You can also select files for analysis by dragging them from a file manager and dropping them anywhere on the Audio Tuner main window. This means you don't even need to use the File Selector Panel at all if you don't want to. .. hint:: Dropping a directory onto Audio Tuner causes the File Selector Panel to go to that directory. * To select things, either double click on them or press :kbd:`Enter` once they're highlighted. * You can move up and down with the arrow keys. Hold down :kbd:`Shift` while doing that to highlight a range of things. * You can also highlight a range of things by dragging with the mouse. * Hold down :kbd:`Ctrl` while clicking things to highlight multiple non-contiguous things. * Selecting a file or files will cause them to be analyzed. The ones for which analysis is successful will appear in the :ref:`analyzed_audio_panel`. While analysis is happening, a progress bar and a stop button appears in the status bar (at the bottom of the window). * Selecting a file which has already been analyzed will cause it to be selected in the :ref:`analyzed_audio_panel`. * Select a directory to go to that directory. * Selecting multiple directories at once does nothing. The File Selector Panel has its own little toolbar. Here's what's on it, from left to right: .. rubric:: Back button Go to the previous directory in the navigation history. The status bar will tell you specifically which directory that is when you hover the mouse cursor over the button. .. rubric:: Forward button Go to the next directory in the navigation history. The status bar will tell you specifically which directory that is when you hover the mouse cursor over the button. .. rubric:: Up button Go to the parent directory. .. rubric:: Home button Go to your home directory. .. rubric:: Path Shows the current directory. You can edit it to change directories. You can also add a filename to the end of the path to select that file for analysis. It includes autocomplete functionality so you don't have to type out entire directory or file names. .. _option_panel: Option Panel ~~~~~~~~~~~~ .. figure:: _static/Screenshot_Options_Panel.png If the Option Panel is not visible, you can toggle it by pressing :kbd:`F2`, using the :guilabel:`Option Panel/File Selector Panel toggle button` in the toolbar, or by using the **Options** |triangle| **Show option panel** menu option. The Option Panel has two jobs: #. It's where you set options that you want to be applied, either to the next analysis or to the currently selected analyzed audio. #. It shows you the options that are currently applied to the selected analyzed audio. Doing two jobs at once can be confusing, so there's some controls to help you manage things: .. rubric:: Hold * If :guilabel:`Hold` is **checked**, the Option Panel will hold on to whatever options you have set in it. * If :guilabel:`Hold` is **unchecked**, selecting something in the :ref:`analyzed_audio_panel` will show the options associated with the selection in the Option Panel. .. rubric:: Use in next analysis .. versionadded:: 0.11 * If :guilabel:`Use in next analysis` is **checked**, the next file you select for analysis in the :ref:`file_selector_panel` will use the options currently set in the Option Panel. * If :guilabel:`Use in next analysis` is **unchecked**, the next file you select for analysis will use the default options, or it's own saved options if there are any. .. note:: Checking the :guilabel:`Use in next analysis` box will automatically check the :guilabel:`Hold` box, to prevent the options you set from getting accidentally clobbered. There's also some important buttons: .. rubric:: Revert to defaults Makes everything in the option panel revert to its default value. .. rubric:: Apply to selected Applies the settings in the option panel to what's currently selected in the :ref:`analyzed_audio_panel`. If you try to apply an invalid value, the offending text box will turn red to attract your attention to the problem. The Options ^^^^^^^^^^^ .. tip:: On any option where you can type in a value, setting it to an empty value will cause it to set itself back to the default. .. tip:: In addition to typing in a number, the **Pitch correction factor**, **Tempo correction factor** and **Max peaks** can be adjusted with the mouse wheel, or by using the :kbd:`Up` and :kbd:`Down` keys on the keyboard, or clicking the little arrows. .. rubric:: Pitch correction factor Multiply all frequencies in the audio by this number. Adjusting this for already analyzed audio will cause "ghost needles" to appear in the :ref:`display`'s discrepancy meters until you apply the change. This is to visually show you how big of a pitch change you're making, and let you know when you've made enough of a correction to center the needles. .. figure:: _static/Screenshot_Ghosts.png Ghosts! .. rubric:: Tempo correction factor The tempo correction factor to apply to the audio. .. note:: Pitch and tempo correction factors have a range of 0.243 to 4.117. This covers 4 octaves plus another 50 cents on either end of the range. This should be more than enough for any normal corrections, but if you do need more for whatever reason, make a bug report to let me know. See :ref:`bug_tracker` .. _link_button: .. rubric:: Link button Toggles the link between the pitch and tempo corrections. The default is linked, which means they will always have the same value. Adjusting one will adjust the other one along with it so they stay the same. This is like adjusting the tape speed on a tape player, with pitch and tempo changing together. Unlink them to adjust pitch and tempo independently. .. note:: The Link setting is not saved when you save options. Instead, the correct setting is guessed during the saved option loading process. If pitch and tempo are different, :guilabel:`Link` will be off, otherwise it will be on. .. versionchanged:: 0.8 Link used to be off by default. .. versionchanged:: 0.11.2 Link didn't used to automatically update .. versionchanged:: 0.12 Items in the Analyzed Audio Panel now store their Link setting, to avoid having to guess when selecting analyzed audio. Guessing the Link setting still happens when loading saved options, however. .. rubric:: -100c button .. rubric:: +100c button These change the pitch correction factor by 100 cents. This is equivalent to one half-step in the 12 Tone Equal Temperament tuning system. In other words, these buttons change the key. Keyboard shortcuts: :kbd:`<` = -100c :kbd:`>` = +100c (That's :kbd:`Shift+,` and :kbd:`Shift+.` on a US English keyboard.) .. rubric:: Reread file with correction Normally when a pitch correction is applied, the display doesn't show the actual result of the pitch correction calculation. Instead, it fakes it by just applying an offset to all the measured frequency values. This is usually good enough, but sometimes you want more accuracy than that. Pushing :guilabel:`Reread file with correction` instead of :guilabel:`Apply to selected` forces a reread of the file with pitch correction applied and a complete reanalysis, so you can see what the result of the pitch shift *really* is. This matters because the pitch shift algorithm isn't perfect, and will cause subtle changes that make the frequency analysis come out differently. .. warning:: If the pitch and tempo correction factors are different, this can be very computationally expensive, especially when using the **rubberband** pitch correction backend. The worst part is that reading the file with pitch correction applied is not something that can be interrupted with the stop button. .. rubric:: Tuning system Which tuning system to use. Right now there's only 12 Tone Equal Temperament and Pythagorean, but future versions will have more tuning systems to cover a wider variety of music. The default is Equal Temperament. .. rubric:: Reference frequency The frequency of the **Reference note**, in Hz. Default is 440 Hz (Stuttgart pitch). .. rubric:: Reference note The note to which the **Reference pitch** applies. Default A4 (The A above middle C). When typing in a note, you can use "#" (hash) as a sharp symbol and "b" (lowercase B) as a flat symbol. .. rubric:: Low cut Don't show pitches below this frequency. Default is 20 Hz. .. rubric:: High cut Don't show pitches above this frequency. Default is 15000 Hz. .. rubric:: Start time .. rubric:: End time These control which part of the audio gets analyzed. By default, it analyzes the whole thing, from Beginning to End. Set different times here to narrow that down to a specific part. If **Option** |triangle| **Play between Start time and End time** is checked, this will also control which portion of the audio the player plays. Times can be specified as a number of seconds, or in **mm:ss** or **hh:mm:ss** format. It doesn't have to be an integer number of seconds; decimal points are allowed. Negative times are relative to the end of the audio (for example, -5 means 5 seconds before the end). Percentages are also allowed (for example. 50% means halfway through). The special value "Beginning" is allowed for the start time, and the special value "End" is allowed for the end time. They mean exactly what you think they do. If the audio is loaded in the player, you can use the :guilabel:`Set to now` buttons to set the :guilabel:`Start time` or :guilabel:`End time` to the current play position. .. rubric:: dB range Controls the sensitivity of spectral peak detection. Any peak in the spectrum this much weaker than the most prominent peak will be ignored. The default is 30 dB. Set it higher if not enough pitches are being detected. .. rubric:: Max peaks The maximum number of pitches to show. The default is 10. .. _savingoptions: Saving Options ^^^^^^^^^^^^^^ .. versionadded:: 0.11 Once you're happy with the options you've set for a particular audio file, you can save them by pressing :kbd:`Ctrl+S` or using the **File** |triangle| **Save options** menu item. The next time you analyze that file, it will use the saved options (unless of course :guilabel:`Use in next analysis` is checked, in which case it will use whatever options are set in the Option Panel instead). If you're made changes to the options for a particular file, you can reload the saved ones into the Option Panel using **File** |triangle| **Reload saved options**. Don't forget to push :guilabel:`Apply to selected` if you want the options applied. There's also **File** |triangle| **Delete saved options**, which will delete the saved options associated with the currently selected analyzed audio after asking for confirmation. The options are saved in a file called ``saved_options.ini`` by default. It's location on your system is given in the About window (**Help** |triangle| **About Audio Tuner**). See :ref:`savefile`. .. attention:: The saved options are stored by path, so if the audio file is renamed or moved, Audio Tuner won't recognize it as the same file unless ``saved_options.ini`` is manually updated. A future version may have the option to identify files by hashes instead of paths. .. warning:: Saving options from multiple instances of the Audio Tuner GUI running at the same time results in undefined behavior. It is very likely you'll lose some of the saved options. Don't do this. .. _analyzed_audio_panel: Analyzed Audio Panel ~~~~~~~~~~~~~~~~~~~~ .. figure:: _static/Screenshot_Analyzed_Audio_Panel.png This is a list of audio files that have been analyzed. Whichever one is selected will show up on the :ref:`display`, and will be the one that plays when you push the play button. You can edit the titles. This will not change the title tag in the original file (Audio Tuner will never modify or overwrite the original file). It *will* affect the title tag as it appears in the :ref:`export_window`'s tag editor. .. tip:: If you set the title to a blank value, it will revert to the original title. .. tip:: You can rearrange things by dragging the small boxes on the left side of the list. .. rubric:: Remove button Removes the currently selected analyzed audio from the list. It only works if :guilabel:`Enable removal` is checked, to prevent accidental removal. .. rubric:: Enable removal Makes the remove button work. .. _playlist: Playlist ^^^^^^^^ .. versionadded:: 0.12 The column with the play symbol ( |play| ) at the top is the **playlist** column. This affects what gets played when you push the play button in the :ref:`toolbar`. You can add items to the playlist by checking their checkboxes in this column, and remove them from the playlist by unchecking their checkboxes. If you push the play button in the toolbar with nothing checked, it will play the currently selected item and then stop. .. note:: The player should smoothly go from one song to the next in the playlist with no gap. However, this doesn't work when using the **rubberband** pitch correction backend. If you need gapless playback, only use the default **scaletempo2** backend. Context Menu ^^^^^^^^^^^^ .. versionadded:: 0.12 Right clicking opens the context menu, which contains up to 3 items: .. rubric:: Add everything to playlist Checks every Playlist checkbox. .. rubric:: Clear playlist Unchecks every Playlist checkbox. .. rubric:: Go to containing directory This one is only available when right clicking on one of the items in the list. It tells the :ref:`file_selector_panel` to go to the directory containing the file associated with that item. .. _message_log: Message Log ~~~~~~~~~~~ .. figure:: _static/Screenshot_Message.png This is a log of what's happened since Audio Tuner started (or since the last time the log was cleared). Warnings are bold and errors are red. Right-clicking brings up a context menu containing :guilabel:`Copy`, :guilabel:`Select All` and :guilabel:`Clear log`. .. _export_window: Export Window ~~~~~~~~~~~~~ .. figure:: _static/Screenshot_Export.png This allows you to export audio with the pitch and tempo correction applied. #. Pick a path (directory and filename) either by typing it directly into the line edit box, or pushing the :guilabel:`Choose path...` button to open a standard file selector dialog window. #. Pick a file format. #. Choose whether or not you want to limit the export to between :guilabel:`Start time` and :guilabel:`End time` (as set in the :ref:`option_panel`). #. Edit the tags if you want. #. Push :guilabel:`Export`. The Export window closes when and if the export finishes successfully. Warnings and errors will show up the :ref:`message_log`. .. note:: Don't try to overwrite a file that already exists. Audio Tuner won't do it. It doesn't matter if the file selector dialog asks you if you want to overwrite it and you say yes, it still won't do it. .. note:: If the tag editor is empty, it means the original file didn't have any tags. If you want tags in the exported file, you'll have to write them all yourself. .. note:: Unlike with the :ref:`option_panel` or :ref:`analyzed_audio_panel`, setting a tag to an empty value will not reset it to it's original value. However, you can undo all your changes by closing the export window and opening it again. Keyboard cheat sheet ~~~~~~~~~~~~~~~~~~~~ General commands: ^^^^^^^^^^^^^^^^^ **Exit**: :kbd:`Ctrl+Q` **Toggle File Selector/Option Panel**: :kbd:`F2` **Message Log**: :kbd:`Ctrl+E` File Selector Panel commands: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Show Hidden Files**: :kbd:`Ctrl+H` **Highlight Multiple**: :kbd:`Ctrl` **Highlight Contiguous**: :kbd:`Shift` **Select**: :kbd:`Enter` **Up**: :kbd:`Alt+Up` **Back**: :kbd:`Alt+Left` **Forward**: :kbd:`Alt+Right` **Home**: :kbd:`Alt+Home` Option Panel commands: ^^^^^^^^^^^^^^^^^^^^^^ **Link**: :kbd:`=` **-100c**: :kbd:`Shift+<` **+100c**: :kbd:`Shift+>` **Hold**: :kbd:`Alt+L` **Use in next analysis**: :kbd:`Alt+U` **Revert to defaults**: :kbd:`Alt+D` **Apply to selected**: :kbd:`Alt+A` **Save options**: :kbd:`Ctrl+S` .. versionchanged:: 0.11 Alt+L used to toggle Link Analyzed Audio commands: ^^^^^^^^^^^^^^^^^^^^^^^^ **Toggle playlist checkbox**: :kbd:`Insert` **Cancel analysis**: :kbd:`Esc` **Remove from list**: :kbd:`Backspace` Player commands: ^^^^^^^^^^^^^^^^ **Play**: :kbd:`Ctrl+P` **Pause**: :kbd:`Spacebar` **Previous entry in playlist**: :kbd:`Shift+Left` **Back 10 seconds** :kbd:`Left` **Forward 10 seconds** :kbd:`Right` **Next entry in playlist**: :kbd:`Shift+Right` :kbd:`Play`, :kbd:`Pause` and :kbd:`Stop` media keys will also work if your keyboard has them. A combination :kbd:`Play/Pause` key will not work. .. versionchanged:: 0.11 Ctrl+S used to stop the player