API Reference

When you install Audio Tuner, you also get the audio_tuner Python package with the following modules:

There’s also the audio_tuner.argument_parser module, the audio_tuner.saved_options module (added in version 0.11) and the audio_tuner_gui package, which are not documented here but do include docstrings in the source.

Analysis module

audio_tuner.analysis

Tuning Systems module

audio_tuner.tuning_systems

Classes representing tuning systems. The API of each tuning system class is identical. They all take ref_note and ref_freq arguments at instantiation, and the instances are iterators that take start_freq and end_freq arguments and yield notes covering at least that range. Allowed values for ref_note may differ, however.

class audio_tuner.tuning_systems.EqualTemperament(ref_note='A4', ref_freq=None)

Iterate over notes in the equal temperament tuning system.

Parameters:

  • ref_note (str, optional) – The note who’s frequency is set by ref_freq. Acceptable note names are capital letters from A to G, optionally followed by a single sharp of flat sign and/or an octave number, with no spaces. The default octave if the number is left off is 4. Sharp and flat symbols can be ‘#’ and ‘b’, or the ‘MUSIC SHARP SIGN’ or ‘MUSIC FLAT SIGN’ Unicode characters. Default ‘A4’.

  • ref_freq (float, optional) – The frequency of ref_note in Hz. If None, a value is automatically chosen that will make A4 have a frequency of 440 Hz. Default None.

ref_note

The note who’s frequency is set by ref_freq.

Type:

str

ref_freq

The frequency of ref_note in Hz.

Type:

float

Raises:

ValueError – For invalid ref_note.

__call__(start_freq, end_freq)

Set the range of frequencies to cover. When iterating, the object will yield a range of notes covering AT LEAST the specified frequency range.

Parameters:

  • start_freq (float) – The lower end of the frequency range, in Hz.

  • end_freq – The upper end of the frequency range, in Hz.

Returns:

self, since it’s an iterator.

Return type:

EqualTemperament

__iter__()

Iterate over notes.

Yields:

  • note_freq (float) – The frequency of the note.

  • note_name (str) – The name of the note. This is normally no more than 6 characters long, but could be longer if the octave number has enough digits.

  • band_bottom (float)

  • band_top (float) – The top and bottom of a band of frequencies closer in pitch to the note than any other note (in other words, the Voronoi region on a log scale).

class audio_tuner.tuning_systems.Pythagorean(ref_note='A4', ref_freq=None)

Iterate over notes in the Pythagorean tuning system.

Parameters:

  • ref_note (str, optional) – The starting note when building the scale. Acceptable note names are capital letters from A to G, optionally followed by a single sharp of flat sign and/or an octave number, with no spaces. The default octave if the number is left off is 4. Sharp and flat symbols can be ‘#’ and ‘b’, or the ‘MUSIC SHARP SIGN’ or ‘MUSIC FLAT SIGN’ Unicode characters. Default ‘A4’.

  • ref_freq (float, optional) – The frequency of ref_note in Hz. If None, an appropriate value is automatically chosen from the A440 equal temperament system. This ensures the note frequencies won’t change too drastically as ref_note is changed. Default None.

ref_note

The note who’s frequency is set by ref_freq.

Type:

str

ref_freq

The frequency of ref_note in Hz.

Type:

float

Raises:

ValueError – For invalid ref_note.

__call__(start_freq, end_freq)

Set the range of frequencies to cover. When iterating, the object will yield a range of notes covering AT LEAST the specified frequency range.

Parameters:

  • start_freq (float) – The lower end of the frequency range, in Hz.

  • end_freq – The upper end of the frequency range, in Hz.

Returns:

self, since it’s an iterator.

Return type:

Pythagorean

__iter__()

Iterate over notes.

Yields:

  • note_freq (float) – The frequency of the note.

  • note_name (str) – The name of the note. This is normally no more than 6 characters long, but could be longer if the octave number has enough digits.

  • band_bottom (float)

  • band_top (float) – The top and bottom of a band of frequencies closer in pitch to the note than any other note (in other words, the Voronoi region on a log scale).

Common module

audio_tuner.common

Miscellaneous functions used by Audio Tuner. This also includes mpv_error, and thus should be imported by other modules before they import mpv so that they can check mpv_error first.

Added in version 0.11: platform_dirs PITCH_TEMPO_MIN PITCH_TEMPO_MAX

Added in version 0.12: CORRECTION_ST2 CORRECTION_RB

param mpv_error:

If there was a problem importing mpv, this contains the error message. None if there was no problem.

type mpv_error:

str

param ffmpeg_error:

If ffmpeg is not found, this contains an error message. None if ffmpeg is available.

type ffmpeg_error:

str

param ffprobe_error:

If ffprobe is not found, this contains an error message. None if ffprobe is available.

type ffprobe_error:

str

param FFMPEG_BINARY:

The path to ffmpeg, or None of it’s not found.

type FFMPEG_BINARY:

str

param FFPROBE_BINARY:

The path to ffprobe, or None of it’s not found.

type FFPROBE_BINARY:

str

param platform_dirs:

A platformdirs.PlatformDirs object that can be used to obtain the paths of various standard directories.

param PITCH_TEMPO_MIN:

The maximum allowable pitch and tempo correction factor. It’s an arbitrary limit that probably shouldn’t exist.

param PITCH_TEMPO_MAX:

The minimum allowable pitch and tempo correction factor. It’s an arbitrary limit that probably shouldn’t exist.

audio_tuner.common.cents_to_ratio(cents)

Convert a note difference in cents to a frequency ratio. This is the inverse of ratio_to_cents.

Parameters:

cents (float) – The note difference in cents.

Returns:

The ratio of frequencies.

Return type:

float

audio_tuner.common.normalize_path(path)

Convert a path into an absolute path with no symlinks in a format suitable for use as a header in the save file.

Added in version 0.11.

Parameters:

path (str) – The path to convert.

Returns:

The normalized path as a quoted string with special characters escaped using backslash.

Return type:

str

audio_tuner.common.ratio_to_cents(ratio)

Convert a ratio of frequencies to cents. Ratios greater than one convert to a positive number of cents, less than one convert to negative.

Parameters:

ratio (float) – The ratio of frequencies.

Returns:

The note difference in cents.

Return type:

float

audio_tuner.common.raw_to_string(path)

Convert a bytes object representing a path to a string.

Parameters:

path (bytes) – The path, or None.

Returns:

The path as a string, or None if path is None.

Return type:

str

audio_tuner.common.string_to_raw(path)

Convert a string representing a path to a bytes object.

Parameters:

path (str) – The path, or None.

Returns:

The path as a bytes object, or None if path is None.

Return type:

bytes

Error Handling module

audio_tuner.error_handling

Exceptions and functions for handling error messages in the Audio Tuner command line program.

exception audio_tuner.error_handling.LoadError

Raised when anything goes wrong reading file data

exception audio_tuner.error_handling.ShortError

Raised when the audio is too short

audio_tuner.error_handling.debug(msg)

Log a debug message.

Parameters:

msg (str) – The message.

audio_tuner.error_handling.error(msg, prefix='')

Log a error message.

Parameters:

msg (str) – The message.

audio_tuner.error_handling.warning(msg)

Log a warning message.

Parameters:

msg (str) – The message.