Voice Coach

Measures the pitch accuracy of sung audio (solo voice, one melodic line). Args: audio: audio path (wav/flac/mp3/m4a) or a name returned by record_audio. reference_midi: optional path to a .mid with the expected melody. Tolerates singing an octave up/down, starting at another moment and a somewhat different tempo. key: optional when there is no MIDI, e.g. "A minor", "G major", "F#" (Spanish names such as "La menor" also work): each note is compared with the nearest note of that scale. Without it, with the nearest equal-tempered note. midi_track: index of the MIDI track to use (default: the non-drum track with most notes). Returns `summary` (notes, range, pct_within_25_cents, signed mean_deviation_cents, tendency flat/sharp/centered, drift_cents between 1st and 2nd half, stability counts; with MIDI also missed, extra_notes, wrong_notes, onsets on_time/late/early, octave_shift, start_offset_ms and relative_tempo >1 = slower) and `notes`: t (s), dur, note or expected/sung, cents (+ = sharp), stability (stable | vibrato with vibrato_hz and vibrato_pp_cents | unstable with std_cents), drift_cents within the note and, with MIDI, onset_ms/onset; reference notes not sung have status=missed and unmatched sung notes status=extra. If the list does not fit, the most problematic notes are shown and the rest is in `full_details`.

Compares the pronounced phonemes with the expected ones for a text read aloud (English). Args: audio: audio path or a name returned by record_audio (up to 60 s; short sentences work best). expected_text: the exact text that was read. language: "en-US" (default) or "en-GB". Returns `summary` (overall_score 0–100, words_with_errors, error counts by type, frequent_confusions expected→detected) and `words`: word, score, t (s) and, when there are errors, expected/detected in IPA and errors [{type: substitution|deletion|insertion, expected, detected}]; `missing` when the word was not said. `phonemes` holds both full sequences. Word score = 100·(1 − (S + D + 0.5·I)/expected phonemes). Allophonic variants (flap, schwa, linking r) do not count as errors. The text_mismatch warning means a different text was probably read. Backend: local wav2vec2, or Azure when VOICE_COACH_PRONUNCIATION_BACKEND=azure (then the audio is sent to Azure).

Appends a session to the progress log (~/VoiceCoach/progress.md). Args: entry: markdown of the session. It should start with "## YYYY-MM-DD · mode · exercise"; if it does not start with "## ", the date and time are added as the title.

Reads the latest sessions from the progress log (~/VoiceCoach/progress.md). Use it at the start of a session to pick up the previous focus. Returns `file`, `total_entries` and `entries` (markdown of each session, oldest to newest).

Records from the computer's microphone and saves a 16 kHz mono .wav. Args: seconds: recording length (max 120 by default). Tell the user before calling. name: optional file name (without extension); defaults to date and time. Returns `audio` (path of the .wav), levels (peak/RMS in dBFS, estimated SNR, % clipping), `confidence` and `warnings`. The `no_microphone_permission` warning means macOS delivered no audio: the user must enable the microphone for the app in System Settings.

Measures pace, pauses, filler words and pitch/volume variation of a speech. Args: audio: audio path or a name returned by record_audio. language: language of the speech ("en" or "es"; filler lists exist for both). pause_threshold_s: minimum silence between words to count as a long pause. Returns: - `pace`: words, speaking_time_s, words_per_minute, wpm_excluding_long_pauses. - `pauses`: count, total_s, max_s, per_minute and items [{t, dur, after: previous word}]. - `fillers`: total, per_minute, by_type and occurrences [{t, text}]. Ambiguous words ("like", "so") only count when isolated by a comma or a pause. - `pitch`: median_f0_hz, std_semitones, range_p10_p90_semitones, monotone (std < 2 st) and monotone_stretches [{t, end}] over 8 s windows. - `volume`: mean_dbfs, std_between_words_db, range_p10_p90_db, low_variation (std < 3 dB). - `segments` of the transcript [{t, end, text}].

Transcribes audio with timestamps (faster-whisper, local). Args: audio: audio path or a name returned by record_audio. language: "en", "es", "en-US", "Spanish"…; auto-detected when omitted. Returns `language`, `language_prob`, `text`, `segments` [{t, end, text}] and `words` [{w, t, end}]. If it does not fit, words are dropped first and then segments (everything stays in `full_details`). The first call downloads the model (VOICE_COACH_WHISPER_MODEL).