Add freestyle detection for unpitchable vocal passages

[MrDix]

Summary

• Freestyle detection: HPSS-based harmonicity analysis marks unpitchable vocal passages (growls, screams, rap, spoken word) as UltraStar freestyle notes — displayed but not scored
• CLI flags: --detect_freestyle, --freestyle_harmonicity, --freestyle_energy, --freestyle_confidence, --freestyle_pitch_stdev, --freestyle_spectral_flatness, --freestyle_spectral (internal Settings fields unchanged for stability)
• Detection tiers: Primary via harmonic-to-percussive energy ratio (HPSS), fallback via SwiftF0 confidence + pitch stability + optional spectral flatness
• Syllable propagation: Freestyle marking propagates across tilde-connected syllables within the same word
• SABR warning filter: Suppresses harmless yt-dlp SABR streaming experiment warnings across all YouTube download entry points
• OGG cover art fix: Resizes embedded covers to ≤32 KB JPEG with zero mutagen padding, keeping Vorbis headers under Karedi's JOrbis 64 KB mark limit

Test plan

• Convert a song with harsh/growled vocals using --detect_freestyle and verify freestyle notes appear as F in the UltraStar txt
• Convert a clean vocal song and verify no false freestyle detections
• Verify SABR yt-dlp warning no longer appears in console output
• Open output in Karedi and confirm all OGG files (mix, vocals, instrumental) load successfully
• Run pytest pytest/modules/Pitcher/test_growl_detector.py — all tests pass

Summary by CodeRabbit

• New Features

  • Freestyle detection to mark unpitchable vocal passages as freestyle notes (displayed but not scored), with primary spectral analysis and pitch-based fallback, syllable propagation, and a GUI toggle.

• Config & CLI

  • New CLI flags (including --detect_freestyle and --no_freestyle_spectral) and persistent settings with tunable thresholds; settings are reported in outputs when enabled.

• Documentation

  • README section with usage examples and threshold-tuning commands.

• Improvements

  • Reduced audio tag padding and smaller cover embedding; quieter yt-dlp logging.

• Tests

  • Added comprehensive unit tests for freestyle detection.

[MrDix]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new freestyle/growl detection feature marks unpitchable vocal passages as UltraStar freestyle notes (displayed but not scored). It uses HPSS harmonicity when vocal audio is available, falls back to SwiftF0 confidence and pitch-stability metrics (with optional spectral-flatness), and integrates via CLI, GUI, settings, tests, and pipeline wiring.

Changes

Cohort / File(s)	Summary
Freestyle Detection Core src/modules/Pitcher/growl_detector.py	New module implementing detect_growl_segments() with HPSS harmonicity primary path, SwiftF0-based fallback (confidence + pitch stdev), optional spectral-flatness gating, context expansion, syllable/word propagation, and error-resilient handling.
CLI & Pipeline Integration src/UltraSinger.py, src/modules/common_print.py, src/gui/ultrasinger_runner.py	Added --detect_freestyle and threshold flags (--freestyle_harmonicity, --freestyle_energy, --freestyle_confidence, --freestyle_pitch_stdev, --freestyle_spectral_flatness, --no_freestyle_spectral); pipeline calls detector after syllable merge; help text and settings output extended.
Settings & GUI src/Settings.py, src/gui/config.py, src/gui/settings_tab.py	Added detect_growl boolean, numeric thresholds (growl_harmonicity_threshold, growl_energy_threshold, growl_confidence_threshold, growl_pitch_stdev_threshold, growl_spectral_flatness_threshold) and growl_use_spectral flag; GUI toggle and config defaults wired and persisted.
Testing pytest/modules/Pitcher/test_growl_detector.py	New comprehensive unit tests for growl detection covering HPSS harmonicity, SwiftF0 fallback, thresholds, propagation, edge cases, deterministic synthetic data, and API behavior.
Audio & Metadata src/modules/Audio/metadata_writer.py, src/modules/Audio/youtube.py	Changed OGG save to audio.save(padding=lambda x: 0) (zero padding) and reduced cover max bytes from 48 KB to 32 KB; added a filtered logger to suppress benign yt-dlp warnings and standardize logging.
Documentation README.md	Added "Freestyle Detection (--detect_freestyle)" section with usage examples, primary HPSS approach, SwiftF0 fallback, tunable thresholds, and example CLI tuning commands.

Sequence Diagram

sequenceDiagram
    participant UltraSinger as UltraSinger.run()
    participant Detector as detect_growl_segments()
    participant HPSS as HPSS Analysis
    participant SwiftF0 as SwiftF0/PitchedData
    participant Midi as MidiSegments

    UltraSinger->>Detector: midi_segments, pitched_data, vocal_audio_path, thresholds
    Detector->>HPSS: vocal_audio_path available? / attempt HPSS
    alt HPSS available
        HPSS->>Detector: per-frame harmonic & percussive energy
        Detector->>Detector: compute harmonicity ratio, check energy_threshold
        Detector->>Detector: classify vs harmonicity_threshold
    else HPSS unavailable/failed
        SwiftF0->>Detector: median confidence, voiced ratio, pitch stdev
        Detector->>Detector: apply confidence & pitch_stdev thresholds
        Detector->>Detector: optional spectral_flatness check
    end
    Detector->>Detector: mark segments (note_type="F") and propagate to continuations
    Detector->>Midi: return updated midi_segments
    Midi->>UltraSinger: updated segments consumed downstream

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• PR #58: Implements the same freestyle/growl detection feature (overlapping module, settings, CLI/GUI, and tests) — directly related.
• PR #57: Adds propagation/handling of note_type = "F" in merge/split/output logic — touches the same metadata and propagation behavior.
• PR #14: Modifies UltraSinger.run() post-processing insertion points — relates to where this detector is invoked in the pipeline.

Poem

🐰 I sniffed the spectrogram at night,
Found growls that shone but missed the pitch light.
HPSS hummed, SwiftF0 chimed in,
I flagged the wild notes with a floppy-ear grin.
Freestyle now hops across the song — what a sight!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main feature added: a freestyle detection system for identifying unpitchable vocal passages, which is the central theme across all changed files (Settings, CLI, detector implementation, tests, and UI).
Docstring Coverage	✅ Passed	Docstring coverage is 82.98% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/growl-detection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

src/UltraSinger.py (1)

1689-1689: Minor: Error messages missing ULTRASINGER_HEAD prefix.

The error messages for freestyle threshold validation don't include the ULTRASINGER_HEAD prefix that other error messages in this file use (e.g., lines 1554, 1557, 1574).

🔧 Suggested consistency fix

         elif opt in ("--freestyle_harmonicity"):
             val = float(arg)
             if not 0.0 <= val <= 1.0:
-                print(f"Error: --freestyle_harmonicity must be between 0.0 and 1.0, got {val}")
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_harmonicity must be between 0.0 and 1.0, got {val}")
                 sys.exit(1)
             settings.growl_harmonicity_threshold = val
         elif opt in ("--freestyle_energy"):
             val = float(arg)
             if val < 0:
-                print(f"Error: --freestyle_energy must be non-negative, got {val}")
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_energy must be non-negative, got {val}")
                 sys.exit(1)
             settings.growl_energy_threshold = val
         elif opt in ("--freestyle_confidence"):
             val = float(arg)
             if not 0.0 <= val <= 1.0:
-                print(f"Error: --freestyle_confidence must be between 0.0 and 1.0, got {val}")
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_confidence must be between 0.0 and 1.0, got {val}")
                 sys.exit(1)
             settings.growl_confidence_threshold = val
         elif opt in ("--freestyle_pitch_stdev"):
             val = float(arg)
             if val <= 0:
-                print(f"Error: --freestyle_pitch_stdev must be positive, got {val}")
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_pitch_stdev must be positive, got {val}")
                 sys.exit(1)
             settings.growl_pitch_stdev_threshold = val
         elif opt in ("--freestyle_spectral_flatness"):
             val = float(arg)
             if not 0.0 <= val <= 1.0:
-                print(f"Error: --freestyle_spectral_flatness must be between 0.0 and 1.0, got {val}")
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_spectral_flatness must be between 0.0 and 1.0, got {val}")
                 sys.exit(1)
             settings.growl_spectral_flatness_threshold = val

Also applies to: 1695-1695, 1701-1701, 1707-1707, 1713-1713

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/UltraSinger.py` at line 1689, The freestyle threshold validation print
statements (e.g., the one emitting "Error: --freestyle_harmonicity must be
between 0.0 and 1.0, got {val}") should include the ULTRASINGER_HEAD prefix for
consistency with other errors; update each affected print call (the occurrences
at the shown diff and the ones around 1695, 1701, 1707, 1713) to prepend
ULTRASINGER_HEAD (or format it into the f-string) so the error messages match
the file's existing logging style.

src/modules/Pitcher/growl_detector.py (1)

166-173: Consider using logger.info() for consistency.

The module uses logger for warnings elsewhere (lines 202, 334), but this status message uses print(). While the ULTRASINGER_HEAD prefix suggests this may be intentional for console UI consistency, using the logger would enable filtering/redirection of these messages.

♻️ Suggested change (optional)

     if growl_count > 0:
         detail = ""
         if propagated > 0:
             detail = f" ({propagated} via syllable propagation)"
-        print(
-            f"{ULTRASINGER_HEAD} Freestyle detection: marked {growl_count}/{len(midi_segments)} "
-            f"segments as freestyle (unpitchable){detail}"
-        )
+        logger.info(
+            "%s Freestyle detection: marked %d/%d segments as freestyle (unpitchable)%s",
+            ULTRASINGER_HEAD, growl_count, len(midi_segments), detail
+        )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/modules/Pitcher/growl_detector.py` around lines 166 - 173, Replace the
print() status message with a logger.info call to keep logging consistent: in
the block that checks growl_count (uses ULTRASINGER_HEAD, growl_count,
midi_segments, and propagated) swap the print(...) for logger.info(...) and
preserve the same message text and ULTRASINGER_HEAD prefix (and the propagated
detail string) so the message goes through the module logger and can be
filtered/redirected like other warnings.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/modules/Pitcher/growl_detector.py`:
- Around line 166-173: Replace the print() status message with a logger.info
call to keep logging consistent: in the block that checks growl_count (uses
ULTRASINGER_HEAD, growl_count, midi_segments, and propagated) swap the
print(...) for logger.info(...) and preserve the same message text and
ULTRASINGER_HEAD prefix (and the propagated detail string) so the message goes
through the module logger and can be filtered/redirected like other warnings.

In `@src/UltraSinger.py`:
- Line 1689: The freestyle threshold validation print statements (e.g., the one
emitting "Error: --freestyle_harmonicity must be between 0.0 and 1.0, got
{val}") should include the ULTRASINGER_HEAD prefix for consistency with other
errors; update each affected print call (the occurrences at the shown diff and
the ones around 1695, 1701, 1707, 1713) to prepend ULTRASINGER_HEAD (or format
it into the f-string) so the error messages match the file's existing logging
style.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9bc51aee-976d-4385-8484-2f9b2b412b0a

📥 Commits

Reviewing files that changed from the base of the PR and between d0f6072 and 9547289.

📒 Files selected for processing (11)

• README.md
• pytest/modules/Pitcher/test_growl_detector.py
• src/Settings.py
• src/UltraSinger.py
• src/gui/config.py
• src/gui/settings_tab.py
• src/gui/ultrasinger_runner.py
• src/modules/Audio/metadata_writer.py
• src/modules/Audio/youtube.py
• src/modules/Pitcher/growl_detector.py
• src/modules/common_print.py

[MrDix]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

src/UltraSinger.py (1)

1686-1715: Missing ValueError handling for float(arg) conversions.

If a user passes a non-numeric string (e.g., --freestyle_harmonicity abc), float(arg) will raise an unhandled ValueError with a cryptic traceback. The --bpm option (lines 1551-1558) demonstrates the preferred pattern with a try/except block.

However, this matches the existing pattern used by --vad_onset, --vad_offset, --no_speech_threshold, and --denoise_nr, which also lack this handling. Consider addressing this consistently across all float options in a follow-up refactor.

🔧 Example fix for one option (apply pattern to others)

         elif opt in ("--freestyle_harmonicity"):
+            try:
+                val = float(arg)
+            except ValueError:
+                print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_harmonicity must be a number, got {arg}")
+                sys.exit(1)
-            val = float(arg)
             if not 0.0 <= val <= 1.0:
                 print(f"{ULTRASINGER_HEAD} {red_highlighted('Error:')} --freestyle_harmonicity must be between 0.0 and 1.0, got {val}")
                 sys.exit(1)
             settings.growl_harmonicity_threshold = val

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/UltraSinger.py` around lines 1686 - 1715, The float conversions for the
freestyle CLI options (handlers for "--freestyle_harmonicity",
"--freestyle_energy", "--freestyle_confidence", "--freestyle_pitch_stdev",
"--freestyle_spectral_flatness") should be wrapped in try/except to catch
ValueError from float(arg); on ValueError print the same ULTRASINGER_HEAD
red_highlighted('Error:') message indicating the option requires a numeric value
and call sys.exit(1), then proceed with the existing range checks and
assignments to settings.growl_harmonicity_threshold,
settings.growl_energy_threshold, settings.growl_confidence_threshold,
settings.growl_pitch_stdev_threshold, and
settings.growl_spectral_flatness_threshold respectively; apply the same pattern
used by the --bpm handler for consistent error handling.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/UltraSinger.py`:
- Around line 1686-1715: The float conversions for the freestyle CLI options
(handlers for "--freestyle_harmonicity", "--freestyle_energy",
"--freestyle_confidence", "--freestyle_pitch_stdev",
"--freestyle_spectral_flatness") should be wrapped in try/except to catch
ValueError from float(arg); on ValueError print the same ULTRASINGER_HEAD
red_highlighted('Error:') message indicating the option requires a numeric value
and call sys.exit(1), then proceed with the existing range checks and
assignments to settings.growl_harmonicity_threshold,
settings.growl_energy_threshold, settings.growl_confidence_threshold,
settings.growl_pitch_stdev_threshold, and
settings.growl_spectral_flatness_threshold respectively; apply the same pattern
used by the --bpm handler for consistent error handling.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: abfcdbc9-c4e2-46ce-98d6-e6e06c134db8

📥 Commits

Reviewing files that changed from the base of the PR and between 9547289 and ebf22cd.

📒 Files selected for processing (2)

• src/UltraSinger.py
• src/modules/Pitcher/growl_detector.py

✅ Files skipped from review due to trivial changes (1)

• src/modules/Pitcher/growl_detector.py