jdxi_editor.midi.track.classification
=====================================

.. py:module:: jdxi_editor.midi.track.classification

.. autoapi-nested-parse::

   Track classification utilities for MIDI files.

   This module provides functions to classify MIDI tracks into categories:
   - Bass: Low-pitched, monophonic or low polyphony tracks
   - Keys/Guitars: Wide range, polyphonic tracks (piano, guitar, etc.)
   - Strings: Sustained, legato tracks with ensemble-like patterns



Attributes
----------

.. autoapisummary::

   jdxi_editor.midi.track.classification.BASS_RULES
   jdxi_editor.midi.track.classification.KEYS_RULES
   jdxi_editor.midi.track.classification.STRINGS_RULES


Classes
-------

.. autoapisummary::

   jdxi_editor.midi.track.classification.ScoreRule


Functions
---------

.. autoapisummary::

   jdxi_editor.midi.track.classification.name_contains
   jdxi_editor.midi.track.classification.percentage
   jdxi_editor.midi.track.classification.bass_percentage_gt
   jdxi_editor.midi.track.classification.max_polyphony_le
   jdxi_editor.midi.track.classification.avg_duration_gt
   jdxi_editor.midi.track.classification.note_range_ge
   jdxi_editor.midi.track.classification.has_pitch_bend
   jdxi_editor.midi.track.classification.max_polyphony_ge
   jdxi_editor.midi.track.classification.note_count_gt
   jdxi_editor.midi.track.classification.note_count_between
   jdxi_editor.midi.track.classification.legato_score_gt
   jdxi_editor.midi.track.classification.velocity_range_gt
   jdxi_editor.midi.track.classification.mid_percentage_between
   jdxi_editor.midi.track.classification.velocity_std_lt
   jdxi_editor.midi.track.classification.name_contains_string
   jdxi_editor.midi.track.classification.analyze_track_for_classification
   jdxi_editor.midi.track.classification.score_rules
   jdxi_editor.midi.track.classification.calculate_scores
   jdxi_editor.midi.track.classification.explain_score
   jdxi_editor.midi.track.classification._calculate_std_dev
   jdxi_editor.midi.track.classification.classify_tracks


Module Contents
---------------

.. py:function:: name_contains(keywords)

.. py:function:: percentage(part, whole)

.. py:function:: bass_percentage_gt(p)

.. py:function:: max_polyphony_le(n)

.. py:function:: avg_duration_gt(ticks)

.. py:function:: note_range_ge(n)

.. py:function:: has_pitch_bend(s: jdxi_editor.midi.track.stats.TrackStats)

.. py:function:: max_polyphony_ge(n)

.. py:function:: note_count_gt(n)

.. py:function:: note_count_between(lo, hi)

.. py:function:: legato_score_gt(x)

.. py:function:: velocity_range_gt(r)

.. py:function:: mid_percentage_between(lo, hi)

.. py:function:: velocity_std_lt(threshold)

.. py:class:: ScoreRule

   .. py:attribute:: name
      :type:  str


   .. py:attribute:: weight
      :type:  float


   .. py:attribute:: condition
      :type:  Callable[[jdxi_editor.midi.track.stats.TrackStats], bool]


   .. py:method:: evaluate(stats: jdxi_editor.midi.track.stats.TrackStats) -> float


.. py:data:: BASS_RULES

.. py:data:: KEYS_RULES

.. py:function:: name_contains_string(stats: jdxi_editor.midi.track.stats.TrackStats) -> bool

   True when track name contains 'string' or 'strings' (case-insensitive).


.. py:data:: STRINGS_RULES

.. py:function:: analyze_track_for_classification(track: mido.MidiTrack, track_index: int) -> jdxi_editor.midi.track.stats.TrackStats

.. py:function:: score_rules(stats: jdxi_editor.midi.track.stats.TrackStats, rules: list[ScoreRule]) -> float

.. py:function:: calculate_scores(stats: jdxi_editor.midi.track.stats.TrackStats) -> None

.. py:function:: explain_score(stats: jdxi_editor.midi.track.stats.TrackStats, rules: list[ScoreRule])

.. py:function:: _calculate_std_dev(values: List[float]) -> float

   Calculate standard deviation of a list of values.


.. py:function:: classify_tracks(midi_file: mido.MidiFile, exclude_drum_tracks: Optional[List[int]] = None, min_score: float = 30.0) -> dict

   Classify tracks in a MIDI file into Bass, Keys/Guitars, and Strings.

   :param midi_file: The MIDI file to analyze
   :param exclude_drum_tracks: List of track indices to exclude from classification
   :param min_score: Minimum score threshold for a track to be classified

   :returns:

             - "bass": List of (track_index, "TrackStats") tuples
             - "keys_guitars": List of (track_index, TrackStats) tuples
             - "strings": List of (track_index, TrackStats) tuples
             - "unclassified": List of (track_index, TrackStats) tuples
   :rtype: Dictionary with keys